mirai: mirai (Evaluate Async)

In mirai: Minimalist Async Evaluation Framework for R

mirai (Evaluate Async)

Description

Evaluate an expression asynchronously in a new background R process or persistent daemon (local or remote). This function will return immediately with a 'mirai', which will resolve to the evaluated result once complete.

Usage

mirai(.expr, ..., .args = list(), .timeout = NULL, .compute = NULL)

Arguments

.expr	(expression) code to evaluate asynchronously, or a language object. Wrap multi-line expressions in {}.
...	(named arguments | environment) objects required by .expr, assigned to the daemon's global environment. See 'evaluation' section below.
.args	(named list | environment) objects required by .expr, kept local to the evaluation environment (unlike ...). See 'evaluation' section below.
.timeout	(integer) timeout in milliseconds. The mirai resolves to an 'errorValue' 5 (timed out) if evaluation exceeds this limit. NULL (default) for no timeout.
.compute	(character) name of the compute profile. Each profile has its own independent set of daemons. NULL (default) uses the 'default' profile.

Details

The value of a mirai may be accessed at any time at ⁠$data⁠, and if yet to resolve, an 'unresolved' logical NA will be returned instead. Each mirai has an attribute id, which is a monotonically increasing integer identifier in each session.

unresolved() may be used on a mirai, returning TRUE if a 'mirai' has yet to resolve and FALSE otherwise. This is suitable for use in control flow statements such as while or if.

Alternatively, to call (and wait for) the result, use call_mirai() on the returned 'mirai'. This will block until the result is returned.

Specify .compute to send the mirai using a specific compute profile (if previously created by daemons()), otherwise leave as "default".

Value

A 'mirai' object.

Evaluation

The expression .expr will be evaluated in a separate R process in a clean environment (not the global environment), consisting only of the objects supplied to .args, with the objects passed as ... assigned to the global environment of that process.

As evaluation occurs in a clean environment, all undefined objects must be supplied through ... and/or .args, including self-defined functions. Functions from a package should use namespaced calls such as mirai::mirai(), or else the package should be loaded beforehand as part of .expr.

Supply objects to ... rather than .args for evaluation to occur as if in your global environment. This is needed for non-local variables or helper functions required by other functions, which scoping rules may otherwise prevent from being found.

Timeouts

Specifying the .timeout argument ensures that the mirai always resolves. When using dispatcher, the mirai will be cancelled after it times out (as if stop_mirai() had been called). However, cancellation is not guaranteed – for example, compiled code may not be interruptible. When not using dispatcher, the mirai task continues to completion in the daemon process, even if it times out in the host process.

Errors

If an error occurs in evaluation, the error message is returned as a character string of class 'miraiError' and 'errorValue'. is_mirai_error() may be used to test for this. The elements of the original condition are accessible via $ on the error object. A stack trace comprising a list of calls is also available at ⁠$stack.trace⁠, and the original condition classes at ⁠$condition.class⁠.

If a daemon crashes or terminates unexpectedly during evaluation, an 'errorValue' 19 (Connection reset) is returned.

is_error_value() tests for all error conditions including 'mirai' errors, interrupts, and timeouts.

Examples

# specifying objects via '...'
n <- 3
m <- mirai(x + y + 2, x = 2, y = n)
m
m$data
Sys.sleep(0.2)
m$data

# passing the calling environment to '...'
df1 <- data.frame(a = 1, b = 2)
df2 <- data.frame(a = 3, b = 1)
df_matrix <- function(x, y) {
  mirai(as.matrix(rbind(x, y)), environment(), .timeout = 1000)
}
m <- df_matrix(df1, df2)
m[]

# using unresolved()
m <- mirai(
  {
    res <- rnorm(n)
    res / rev(res)
  },
  n = 1e6
)
while (unresolved(m)) {
  cat("unresolved\n")
  Sys.sleep(0.1)
}
str(m$data)

# evaluating scripts using source() in '.expr'
n <- 10L
file <- tempfile()
cat("r <- rnorm(n)", file = file)
m <- mirai({source(file); r}, file = file, n = n)
call_mirai(m)$datado
unlink(file)

# use source(local = TRUE) when passing in local variables via '.args'
n <- 10L
file <- tempfile()
cat("r <- rnorm(n)", file = file)
m <- mirai({source(file, local = TRUE); r}, .args = list(file = file, n = n))
call_mirai(m)$data
unlink(file)

# passing a language object to '.expr' and a named list to '.args'
expr <- quote(a + b + 2)
args <- list(a = 2, b = 3)
m <- mirai(.expr = expr, .args = args)
collect_mirai(m)

mirai documentation built on Feb. 13, 2026, 9:07 a.m.