mlr3misc (version 0.12.0)

encapsulate: Encapsulate Function Calls for Logging

Description

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().

• "try-catch": Similar to "none", but catches error. Output is printed to the console and not logged.

• "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.

Usage

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

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()).

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.

.timeout

(numeric(1))
Timeout in seconds. Uses setTimeLimit() for "none" and "evaluate" encapsulation. For "callr" encapsulation, the timeout is passed to callr::r().

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)

if (requireNamespace("evaluate", quietly = TRUE)) {
  encapsulate("evaluate", f, list(n = 1), .seed = 1)
}

if (requireNamespace("callr", quietly = TRUE)) {
  encapsulate("callr", f, list(n = 1), .seed = 1)
}