future (version 1.3.0)

plan: Plan how to resolve a future

Description

This function allows you to plan the future, more specifically, it specifies how future():s are resolved, e.g. sequentially or in parallel.

Usage

plan(strategy = NULL, ..., substitute = TRUE, .call = TRUE,
  .cleanup = TRUE, .init = TRUE)

Arguments

strategy

The evaluation function (or name of it) to use for resolving a future. If NULL, then the current strategy is returned.

…

Additional arguments overriding the default arguments of the evaluation function.

substitute

If TRUE, the strategy expression is substitute():d, otherwise not.

.call

(internal) Used for recording the call to this function.

.cleanup

(internal) Used to stop implicitly started clusters.

.init

(internal) Used to initiate workers.

Value

If a new strategy is chosen, then the previous one is returned (invisible), otherwise the current one is returned (visibly).

Implemented evaluation strategies

• sequential: Resolves futures sequentially in the current R process.
• transparent: Resolves futures sequentially in the current R process and assignments will be done to the calling environment. Early stopping is enabled by default.
• multisession: Resolves futures asynchronously (in parallel) in separate R sessions running in the background on the same machine.
• multicore: Resolves futures asynchronously (in parallel) in separate forked R processes running in the background on the same machine. Not supported on Windows.
• multiprocess: If multicore evaluation is supported, that will be used, otherwise multisession evaluation will be used.
• cluster: Resolves futures asynchronously (in parallel) in separate R sessions running typically on one or more machines.
• remote: Resolves futures asynchronously in a separate R session running on a separate machine, typically on a different network.

Other package may provide additional evaluation strategies. Notably, the future.BatchJobs package implements a type of futures that will be resolved via job schedulers that are typically available on high-performance compute (HPC) clusters, e.g. LSF, Slurm, TORQUE/PBS, Sun Grid Engine, and OpenLava.

Details

The default strategy is sequential, but the default can be configured by option future.plan and, if that is not set, system environment variable R_FUTURE_PLAN. To reset the strategy back to the default, use plan("default").

Examples

a <- b <- c <- NA_real_

# An sequential future
plan(sequential)
f <- future({
  a <- 7
  b <- 3
  c <- 2
  a * b * c
})
y <- value(f)
print(y)
str(list(a=a, b=b, c=c)) ## All NAs


# A sequential future with lazy evaluation
plan(sequential)
f <- future({
  a <- 7
  b <- 3
  c <- 2
  a * b * c
}) %lazy% TRUE
y <- value(f)
print(y)
str(list(a=a, b=b, c=c)) ## All NAs


# A multicore future
plan(multicore)
f <- future({
  a <- 7
  b <- 3
  c <- 2
  a * b * c
})
y <- value(f)
print(y)
str(list(a=a, b=b, c=c)) ## All NAs


## Multisession futures gives an error on R CMD check on
## Windows (but not Linux or OS X) for unknown reasons.
## The same code works in package tests.

# A multisession future
plan(multisession)
f <- future({
  a <- 7
  b <- 3
  c <- 2
  a * b * c
})
y <- value(f)
print(y)
str(list(a=a, b=b, c=c)) ## All NAs