| plan {future} | R Documentation |
This function allows you to plan the future, more specifically,
it specifies how future():s are resolved,
e.g. sequentially or in parallel.
plan(strategy = NULL, ..., substitute = TRUE, .call = TRUE, .cleanup = TRUE, .init = TRUE)
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. Which additional arguments are supported
depends on what evaluation function is used, e.g. several support
argument |
substitute |
If TRUE, the |
.call |
(internal) Used for recording the call to this function. |
.cleanup |
(internal) Used to stop implicitly started clusters. |
.init |
(internal) Used to initiate workers. |
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").
If a new strategy is chosen, then the previous one is returned (invisible), otherwise the current one is returned (visibly).
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.
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