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

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(), and suppressWarnings(). 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()

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.

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

Options for how futures are partitioned and resolved

Description

Options for how futures are partitioned and resolved

Usage

futurize_options(
  seed = FALSE,
  globals = TRUE,
  packages = NULL,
  stdout = TRUE,
  conditions = "condition",
  scheduling = 1,
  chunk_size = NULL,
  ...
)

Arguments

Value

A named list of future options. Attribute specified is a character vector of future options that were explicitly specified.

Examples

# Default futurize options
str(futurize_options())

List packages and functions supporting futurization

Description

List packages and functions supporting futurization

Usage

futurize_supported_packages()

futurize_supported_functions(package)

Arguments

Value

A character vector of package or function names.

Examples

pkgs <- futurize_supported_packages()
pkgs

fcns <- futurize_supported_functions("base")
fcns

Transpile an R expression

Description

Transpile an R expression

Usage

transpile(
  expr,
  options = list(...),
  ...,
  when = TRUE,
  eval = TRUE,
  envir = parent.frame(),
  type = "built-in",
  what = "transpile",
  unwrap = list(base::`{`, base::`(`, base::`!`, base::local, base::I, base::identity,
    base::invisible, base::suppressMessages, base::suppressWarnings,
    base::suppressPackageStartupMessages),
  debug = FALSE
)

Arguments

Value

Returns the value of the evaluated expression expr if eval = TRUE, otherwise the transpiled expression. If expr is NA, then TRUE is returned if the transpiler is enabled, otherwise FALSE.

Options used by futurize

Description

Below are the R options and environment variables that are used by the futurize package and packages enhancing it.

WARNING: Note that the names and the default values of these options may change in future versions of the package. Please use with care until further notice.

Packages must not change future options

Just like for other R options, as a package developer you must not change any of the below ⁠futurize.*⁠ options. Only the end-user should set these. If you find yourself having to tweak one of the options, make sure to undo your changes immediately afterward.

Options for debugging

futurize.debug:

(logical) If TRUE, extensive debug messages are generated. (Default: FALSE)

Environment variables that set R options

All of the above R futurize.* options can be set by corresponding environment variable R_FUTURIZE_* when the futurize package is loaded. This means that those environment variables must be set before the futurize package is loaded in order to have an effect. For example, if R_FUTURIZE_DEBUG=true, then option futurize.debug is set to TRUE (logical).

See Also

To set R options or environment variables when R starts (even before the future package is loaded), see the Startup help page. The startup package provides a friendly mechanism for configuring R's startup process.