Evaluates a function while both recording an output log and measuring the elapsed time. There are currently three different modes implemented to encapsulate a function call:

  • "none": Just runs the call in the current session and measures the elapsed time. Does not keep a log, output is printed directly to the console. Works well together with traceback().

  • "evaluate": Uses the package evaluate to call the function, measure time and do the logging.

  • "callr": Uses the package callr to call the function, measure time and do the logging. This encapsulation spawns a separate R session in which the function is called. While this comes with a considerable overhead, it also guards your session from being teared down by segfaults.

encapsulate(
  method,
  .f,
  .args = list(),
  .opts = list(),
  .pkgs = character(),
  .seed = NA_integer_
)

Arguments

method

(character(1))
One of "none", "evaluate" or "callr".

.f

(function())
Function to call.

.args

(list())
Arguments passed to .f.

.opts

(named list())
Options to set for the function call. Options get reset on exit.

.pkgs

(character())
Packages to load (not attach).

.seed

(integer(1))
Random seed to set before invoking the function call. Gets reset to the previous seed on exit.

Value

(named list()) with three fields:

  • "result": the return value of .f

  • "elapsed": elapsed time in seconds. Measured as proc.time() difference before/after the function call.

  • "log": data.table() with columns "class" (ordered factor with levels "output", "warning" and "error") and "message" (character()).

Examples

f = function(n) { message("hi from f") if (n > 5) { stop("n must be <= 5") } runif(n) } encapsulate("none", f, list(n = 1), .seed = 1)
#> hi from f
#> $result #> [1] 0.2655087 #> #> $log #> Empty data.table (0 rows and 2 cols): class,msg #> #> $elapsed #> [1] 0.001 #>
if (requireNamespace("evaluate", quietly = TRUE)) { encapsulate("evaluate", f, list(n = 1), .seed = 1) }
#> $result #> [1] 0.570045 #> #> $log #> class msg #> 1: output hi from f #> #> $elapsed #> [1] 0.003 #>
if (requireNamespace("callr", quietly = TRUE)) { encapsulate("callr", f, list(n = 1), .seed = 1) }
#> $result #> [1] 0.2655087 #> #> $log #> class msg #> 1: output hi from f #> #> $elapsed #> elapsed #> 0.371 #>