Package 'futurize'

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

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

Description

Some futures require specific resources and capabilities (e.g., RNG, packages, and globals) in order to be evaluated. These can be declared via this function. In addition, this function can control how futures are evaluated, including what is collected from futures (e.g., standard output and conditions). It can also control how future are scheduled, including how a set of futures are partitioned (e.g. chunking).

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

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. futurize_supported_functions() produces an error if packages required by the futurize transpiler are not installed.

Examples

pkgs <- futurize_supported_packages()
pkgs

if (requireNamespace("future.apply")) {
  fcns <- futurize_supported_functions("base")
  print(fcns)
}

if (requireNamespace("doFuture")) {
  fcns <- futurize_supported_functions("foreach")
  print(fcns)
}

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

Options for controlling futurization

futurize.enable:

(logical) If TRUE (default), futurize() transpilation will be applied, otherwise not.

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 futurize package is loaded), see the Startup help page. The startup package provides a friendly mechanism for configuring R's startup process.