| % 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} |
| |