profmem() evaluates and memory profiles an R expression.
profmem_begin() starts the memory profiling of all the following R
evaluations until profmem_end() is called.
profmem(
expr,
envir = parent.frame(),
substitute = TRUE,
threshold = getOption("profmem.threshold", 0L),
on_error = c("ignore", "warning", "error")
)
profmem_begin(threshold = getOption("profmem.threshold", 0L))
profmem_end()
profmem_suspend()
profmem_resume()
profmem_status()
profmem_depth()An R expression to be evaluated and profiled.
The environment in which the expression should be evaluated.
Should expr be base::substitute():d or not.
The smallest memory allocation (in bytes) to log.
(character) Controls whether evaluation errors should
signal an error ("error"), a warning ("warning"), or be ignored ("ignore"`; default).
profmem() and profmem_end() returns the collected allocation
data as an Rprofmem data.frame with additional attributes set.
An Rprofmem data.frame has columns what, bytes, and trace, with:
what: (character) type of memory event;
either "alloc" or "new page"
bytes: (numeric) number of bytes allocated or NA_real_
(when what is "new page")
trace: (list of character vectors) zero or more function names
The attributes set are:
threshold : The threshold used (= argument threshold)
expression: The expression profiled (= argument expr)
value : The value of the evaluated expression
(only set if there was no error)
error : The error object in case the evaluation failed
(only set if there was an error)
profmem_begin() returns (invisibly) the number of nested profmem
session currently active.
profmem_suspend() and profmem_resume() returns nothing.
profmem_status() returns "inactive", "active",
or "suspended".
promem_depth() returns a non-negative integer.
In order for memory profiling to work, R must have been built with memory
profiling enabled. Function
base::capabilities("profmem") will
return TRUE of it is enabled, otherwise FALSE.
If memory profiling is not supported, profmem() and profmem_begin()
will produce an informative error. The pre-built R binaries on
CRAN support memory profiling.
What is logged? The profmem() function uses utils::Rprofmem() for
logging memory, which logs all memory allocations that are done via the
R framework. Specifically, the logger is tied to allocVector3() part
of R's native API. This means that nearly all memory allocations done
in R are logged. Neither memory deallocations nor garbage collection
events are logged. Furthermore, allocations done by non-R native libraries
or R packages that use native code Calloc() / Free() for internal objects
are also not logged.
Any memory events that would occur due to calling any of the profmem functions themselves will not be logged and not be part of the returned profile data (regardless whether memory profiling is active or not). This is intentional.
If a profmem profiling is already active, profmem() and profmem_begin()
performs an independent, nested profiling, which does not affect the
already active one. When the active one completes, it will contain all
memory events also collected by the nested profiling as if the nested one
never occurred.
Profiling gathered by profmem will be corrupted if the code profiled
calls utils::Rprofmem(), with the exception of such calls done via the
profmem package itself.
if (capabilities("profmem")) {
## Memory profile an R expression
p <- profmem({
x <- raw(1000)
A <- matrix(rnorm(100), ncol = 10)
})
## Display the results
print(p)
## Total amount of memory allocation
total(p)
## Allocations greater than 1 kB
p2 <- subset(p, bytes > 1000)
print(p2)
## The expression is evaluated in the calling environment
str(x)
str(A)
}
#> Rprofmem memory profiling of:
#> {
#> x <- raw(1000)
#> A <- matrix(rnorm(100), ncol = 10)
#> }
#>
#> Memory allocations:
#> Number of 'new page' entries not displayed: 1
#> what bytes calls
#> 1 alloc 1048 eval() -> raw()
#> 2 alloc 280 eval() -> matrix()
#> 3 alloc 560 eval() -> matrix()
#> 4 alloc 560 eval() -> matrix()
#> 5 alloc 1072 eval() -> matrix()
#> 7 alloc 848 eval() -> matrix() -> rnorm()
#> 8 alloc 848 eval() -> matrix()
#> 9 alloc 528 <internal>
#> 10 alloc 1648 <internal>
#> 11 alloc 1648 <internal>
#> 12 alloc 1072 <internal>
#> 13 alloc 256 <internal>
#> 14 alloc 456 <internal>
#> 15 alloc 216 <internal>
#> 16 alloc 256 <internal>
#> total 11296
#> Rprofmem memory profiling of:
#> {
#> x <- raw(1000)
#> A <- matrix(rnorm(100), ncol = 10)
#> }
#>
#> Memory allocations:
#> what bytes calls
#> 1 alloc 1048 eval() -> raw()
#> 5 alloc 1072 eval() -> matrix()
#> 10 alloc 1648 <internal>
#> 11 alloc 1648 <internal>
#> 12 alloc 1072 <internal>
#> total 6488
#> raw [1:1000] 00 00 00 00 ...
#> num [1:10, 1:10] -1.40004 0.25532 -2.43726 -0.00557 0.62155 ...