future (version 1.0.1)

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)

Arguments

strategy

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

substitute

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

.call

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

...

Additional arguments overriding the default arguments of the evaluation function.

Value

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

Implemented evaluation strategies

• eager: Resolves futures sequentially in the current R process.
• lazy: Resolves futures synchronously (sequentially) in the current R process, but only if their values are requested. Futures for which the values are never requested will not be evaluated.
• transparent: Resolves futures synchronously (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,
• 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 eager, 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_

# A lazy future
plan(lazy)
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


# An eager future
plan(eager)
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 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