R: Plan how to resolve a future

plan {future} | R Documentation

## Plan how to resolve a future

### Description

This function allows the user 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. Which additional arguments are supported depends on what evaluation function is used, e.g. several support argument `workers` but not all. For details, see the individual functions of which some are linked to below.
`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.

### 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")`.

### 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.batchtools 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.

### For package developers

Please refrain from modifying the future strategy inside your packages / functions, i.e. do not call `plan()` in your code. Instead, leave the control on what backend to use to the end user. This idea is part of the core philosophy of the future framework - as a developer you can never know what future backends the user have access to. Moreover, by not making any assumptions about what backends are available, your code will also work automatically will any new backends developed after you wrote your code.

If you think it is necessary to modify the future strategy within a function, then make sure to undo the changes when exiting the function. This can be done using:

      oplan <- plan()
      on.exit(plan(oplan), add = TRUE)
      [...]

### 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 (specified as a string)
    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 (specified via a string variable)
    strategy <- "future::multisession"
    plan(strategy)
    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

[Package future version 1.8.0 Index]