encapsulate {mlr3misc} | R Documentation

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

- `"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
    )

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

### 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)

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

[Package mlr3misc version 0.8.0 Index]