% File src/library/base/man/tracemem.Rd
% Part of the R package, https://www.R-project.org
% Copyright 1995-2016 R Core Team
% Distributed under GPL 2 or later

\name{tracemem}
\alias{tracemem}
\alias{untracemem}
\alias{retracemem}
\title{Trace Copying of Objects}
\description{
  This function marks an object so that a message is printed whenever the
  internal code copies the object.  It is a
  major cause of hard-to-predict memory use in R.
}
\usage{
tracemem(x)
untracemem(x)
retracemem(x, previous = NULL)
}
\arguments{
  \item{x}{An R object, not a function or environment or \code{NULL}.}
  \item{previous}{A value as returned by \code{tracemem} or \code{retracemem}.}
}
\details{
  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).

  It is enabled in the CRAN macOS and Windows builds of \R.

  When an object is traced any copying of the object by the C function
  \code{duplicate} produces a message to standard output, as does type
  coercion and copying when passing arguments to \code{.C} or
  \code{.Fortran}.

  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{\link{tracingState}}.

  It is not possible to trace functions, as this would conflict with
  \code{\link{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 \link{primitive}.
}
\value{
  A character string for identifying the object in the trace output (an
  address in hex enclosed in angle brackets), or \code{NULL} (invisibly).
}

\seealso{
  \code{\link{capabilities}("profmem")} to see if this was enabled for
  this build of \R.

  \code{\link{trace}}, \code{\link{Rprofmem}}

  \url{https://developer.r-project.org/memory-profiling.html}
}
\examples{\dontrun{
a <- 1:10
tracemem(a)
## b and a share memory
b <- a
b[1] <- 1
untracemem(a)

## copying in lm: less than R <= 2.15.0
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
}}
\keyword{utilities}