\HeaderA{tracemem}{Trace Copying of Objects}{tracemem}
\aliasA{retracemem}{tracemem}{retracemem}
\aliasA{untracemem}{tracemem}{untracemem}
\keyword{utilities}{tracemem}
\begin{Description}\relax
This function marks an object so that a message is printed whenever the
internal function \code{duplicate} is called.   This happens when two
objects share the same memory  and one of them is modified.  It is a
major cause of hard-to-predict memory use in R.
\end{Description}
\begin{Usage}
\begin{verbatim}
tracemem(x)
untracemem(x)
retracemem(x, previous = NULL)
\end{verbatim}
\end{Usage}
\begin{Arguments}
\begin{ldescription}
\item[\code{x}] An R object, not a function or environment or \code{NULL}.
\item[\code{previous}] A value as returned by \code{tracemem} or \code{retracemem}.
\end{ldescription}
\end{Arguments}
\begin{Details}\relax
This functionality is optional, determined at compilation, because it
makes R run a little more slowly even when no objects are being
traced. \code{tracemem} and \code{untracemem} give errors when R is not
compiled with memory profiling; \code{retracemem} does not (so it can be
left in code during development).

When an object is traced any copying of the object by the C function
\code{duplicate} or by arithmetic or mathematical operations produces a
message to standard output.  The message consists of the string
\code{tracemem}, the identifying strings for the object being copied and
the new object being created, and a stack trace showing where the
duplication occurred.  \code{retracemem()} is used to indicate that a
variable should be considered a copy of a previous variable (e.g. after
subscripting).

The messages can be turned off with \code{\LinkA{tracingState}{tracingState}}.

It is not possible to trace functions, as this would conflict with
\code{\LinkA{trace}{trace}} and it is not useful to trace \code{NULL},
environments, promises, weak references, or external pointer objects, as
these are not duplicated.

These functions are \LinkA{primitive}{primitive} and use positional matching of
arguments.
\end{Details}
\begin{Value}
A character string for identifying the object in the trace output (an
address in hex enclosed in angle brackets), or \code{NULL} (invisibly
for \code{untracemem}.
\end{Value}
\begin{SeeAlso}\relax
\code{\LinkA{trace}{trace}}, \code{\LinkA{Rprofmem}{Rprofmem}}

\url{http://developer.r-project.org/memory-profiling.html}
\end{SeeAlso}
\begin{Examples}
\begin{ExampleCode}## Not run: 
a <- 1:10
tracemem(a)
## b and a share memory
b <- a
b[1] <- 1
untracemem(a)

## copying in lm
d <- stats::rnorm(10)
tracemem(d)
lm(d ~ a+log(b))

## f is not a copy and is not traced
f <- d[-1]
f+1
## indicate that f should be traced as a copy of d
retracemem(f, retracemem(d))
f+1
## End(Not run)\end{ExampleCode}
\end{Examples}

