futurize: Turn common R function calls into concurrent calls for...

In futurize: Parallelize Common Functions via One Magic Function

Turn common R function calls into concurrent calls for parallel evaluation

Description

Usage

futurize(
  expr,
  substitute = TRUE,
  options = futurize_options(...),
  ...,
  when = TRUE,
  eval = TRUE,
  envir = parent.frame()
)

Arguments

expr	An R expression, typically a function call to futurize. If FALSE, then futurization is disabled, and if TRUE, it is re-enabled.
substitute	If TRUE, argument expr is substitute():d, otherwise not.
options, ...	Named options, passed to futurize_options(), controlling how futures are resolved.
when	If TRUE (default), the expression is futurized, otherwise not.
eval	If TRUE (default), the futurized expression is evaluated, otherwise it is returned.
envir	The environment from where global objects should be identified.

Value

Returns the value of the evaluated expression expr.

If expr is TRUE or FALSE, then a logical is returned indicating whether futurization was previously enabled or disabled.

Expression unwrapping

The transpilation mechanism includes logic to "unwrap" expressions enclosed in constructs such as !, { }, ⁠( )⁠, local(), I(), identity(), invisible(), suppressMessages(), suppressWarnings(), suppressPackageStartupMessages(), withCallingHandlers(), and with(). The transpiler descends through wrapping constructs until it finds a transpilable expression, avoiding the need to place futurize() inside such constructs. This allows for patterns like:

y <- {
  lapply(xs, fcn)
} |> suppressMessages() |> futurize()

avoiding having to write:

y <- {
  lapply(xs, fcn) |> futurize()
} |> suppressMessages()

Generic functions

Some functions can be futurized only via their S3 or S4 methods, e.g. influence() of the stats package dispatches to the influence.merMod() method of the lme4 package. To identify which method is called, futurize() has to evaluate the first argument of the generic function. If the first argument is a variable, a formula, or a list() or c() of variables, it is evaluated directly. Otherwise, futurize() makes sure it is evaluated only once, by first assigning it to a temporary variable. For example,

inf <- influence(lmer(...)) |> futurize()

is evaluated as:

inf <- local({
  ...futurize.x <- lmer(...)
  influence(...futurize.x) |> futurize()
})

Because of this, methods that use substitute() or match.call() on the first argument, e.g. for labeling, see ...futurize.x. To avoid this, assign the first argument to a variable yourself, e.g.

fit <- lmer(Reaction ~ Days + (Days | Subject), data = sleepstudy)
inf <- influence(fit) |> futurize()

Conditional futurization

It is possible to control whether futurization should take place at run-time. For example,

y <- lapply(xs, fun) |> futurize(when = { length(xs) >= 10 })

will be futurized, unless length(xs) is less than ten, in which case it is evaluated as:

y <- lapply(xs, fun)

Disable and re-enable all futurization

It is possible to globally disable the effect of all futurize() calls by calling futurize(FALSE). The effect is as if futurize() was never applied. For example,

futurize(FALSE)
y <- lapply(xs, fun) |> futurize()

evaluates as:

y <- lapply(xs, fun)

To re-enable futurization, call futurize(TRUE). Please note that it is only the end-user that may control whether futurization should be disabled and enabled. A package must never disable or enable futurization.

See Also

To see which CRAN and Bioconductor packages are supported, use futurize_supported_packages(). To see which functions a specific package supports, use futurize_supported_functions().

Examples

xs <- list(1, 1:2, 1:2, 1:5)

# ------------------------------------------
# Base R apply functions
# ------------------------------------------
# Sequential lapply()
y <- lapply(X = xs, FUN = function(x) {
  sum(x)
})
   
# Parallel version
y <- lapply(X = xs, FUN = function(x) {
  sum(x)
}) |> futurize()
str(y)


# ------------------------------------------
# purrr map-reduce functions with pipes
# ------------------------------------------
if (require("purrr") && requireNamespace("furrr", quietly = TRUE)) {

# Sequential map()
y <- xs |> map(sum)
   
# Parallel version
y <- xs |> map(sum) |> futurize()
str(y)

} ## if (require ...)


# ------------------------------------------
# foreach map-reduce functions
# ------------------------------------------
if (require("foreach") && requireNamespace("doFuture", quietly = TRUE)) {

# Sequential foreach()
y <- foreach(x = xs) %do% {
  sum(x)
}
   
# Parallel version
y <- foreach(x = xs) %do% {
  sum(x)
} |> futurize()
str(y)


# Sequential times()
y <- times(3) %do% rnorm(1)
str(y)
   
# Parallel version
y <- times(3) %do% rnorm(1) |> futurize()
str(y)

} ## if (require ...)


# ------------------------------------------
# plyr map-reduce functions
# ------------------------------------------
if (require("plyr") && requireNamespace("doFuture", quietly = TRUE)) {

# Sequential llply()
y <- llply(xs, sum)
   
# Parallel version
y <- llply(xs, sum) |> futurize()
str(y)

} ## if (require ...)

futurize documentation built on Oct. 20, 2026, 1:06 a.m.