R: Options used for futures

future.options {future} | R Documentation

## Options used for futures

### Description

Below are all R options that are currently used by the future 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.

### Options for controlling futures

future.plan:

  Default future strategy plan used unless otherwise specified via `plan()`. This will also be the future plan set when calling `plan("default")`. If not specified, this option may be set when the future package is loaded if command-line option `--parallel=ncores` (short `-p ncores`) is specified; if `ncores > 1`, then option future.plan is set to `multiprocess` otherwise `sequential` (in addition to option mc.cores being set to `ncores`, if `ncores >= 1`). If system environment variable R_FUTURE_PLAN is set, then that overrides the future plan set by the command-line option. (Default: `sequential`)

future.globals.onMissing:

  Action to take when non-existing global variables ("globals" or "unknowns") are identified when the future is created. If `"error"`, an error is generated immediately. If `"ignore"`, no action is taken and an attempt to evaluate the future expression will be made. The latter is useful when there is a risk for false-positive globals being identified, e.g. when future expression contains non-standard evaluation (NSE). (Default: `"error"`; likely to change to `"ignore"` in a future release)

future.globals.method:

  Method used to identify globals. For details, see `globalsOf()`. (Default: `"ordered"`)

future.globals.maxSize:

  Maximum allowed total size (in bytes) of global variables identified. Used to prevent too large exports. If set of `+Inf`, then the check for large globals is skipped. (Default: `500 * 1024 ^ 2` = 500 MiB)

future.globals.resolve:

  If `TRUE`, globals that are `Future` objects (typically created as explicit futures) will be resolved and have their values (using `value()`) collected. Because searching for unresolved futures among globals (including their content) can be expensive, the default is not to do it and instead leave it to the run-time checks that assert proper ownership when resolving futures and collecting their values. (Default: `FALSE`)

future.globals.onReference: (beta version - may change)

  Controls whether the identified globals should be scanned for so called references (e.g. external pointers and connections) or not. It is unlikely that another R process ("worker") can use a global that uses a internal reference of the master R process - we call such objects non-exportable globals. If this option is `"error"`, an informative error message is produced if a non-exportable global is detected. If `"warning"` (default; but may change), a warning is produced, but the processing will continue; it is likely that the future will be resolved with a run-time error unless processed in the master R process (e.g. `plan(sequential)` and `plan(multicore)`). If `"ignore"`, no scan is performed.

future.resolve.recursive:

  An integer specifying the maximum recursive depth to which futures should be resolved. If negative, nothing is resolved. If `0`, only the future itself is resolved. If `1`, the future and any of its elements that are futures are resolved, and so on. If `+Inf`, infinite search depth is used. (Default: `0`)

future.wait.timeout:

  Maximum waiting time (in seconds) for a free worker before a timeout error is generated. (Default: `30 * 24 * 60 * 60` (= 30 days))

future.wait.interval:

  Initial interval (in seconds) between polls. (Default: `0.2` (0.2 seconds))

future.wait.alpha:

  Positive scale factor used to increase the interval after each poll. (Default: `1.01`)

### Options for debugging futures

future.debug:

  If `TRUE`, extensive debug messages are generated. (Default: `FALSE`)

future.progress:

  If `TRUE`, progress is displayed while blocked waiting for futures to be resolved. (Default: `FALSE`)

### Options for controlling package startup

future.startup.script:

  If `FALSE`, any ‘.future.R’ startup scripts, which may exist in the current directory and / or the user's home directory, are ignored. Such startup scripts are otherwise sourced when the future package is attached. Importantly, this option is always set to `FALSE` if the future package is loaded as part of a future expression being evaluated, e.g. in a background process. In order words, they are sourced in the main R process but not in future processes. (Default: `TRUE` in main R process and `FALSE` in future processes / during future evaluation)

future.cmdargs:

  Overrides `commandArgs()` when the future package is loaded.

### Options for configuring low-level system behaviors

future.availableCores.methods:

  Default lookup methods for `availableCores()`. (Default: `c("system", "mc.cores", "_R_CHECK_LIMIT_CORES_", "PBS", "SGE", "Slurm", "fallback")`)

future.availableWorkers.methods:

  Default lookup methods for `availableWorkers()`. (Default: `c("mc.cores", "_R_CHECK_LIMIT_CORES_", "PBS", "SGE", "Slurm", "system", "fallback")`)

future.availableCores.fallback:

  Number of cores to use when no core-specifying settings are detected other than `"system"`. If not specified, this option is set according to system environment variable R_FUTURE_AVAILABLECORES_FALLBACK when the future package is loaded. This options makes it possible to set the default number of cores returned by `availableCores()` / `availableWorkers()` yet allow users and schedulers to override it. In HPC environment, it is useful to set `R_FUTURE_AVAILABLECORES_FALLBACK=1`.

future.availableCores.system:

  Number of "system" cores used instead of what is reported by `availableCores(which = "system")`. If not specified, this option is set according to system environment variable R_FUTURE_AVAILABLECORES_SYSTEM when the future package is loaded. This option allows you to effectively override what `parallel::detectCores()` reports the system has.

### Options for demos

future.demo.mandelbrot.region:

  Either a named list of `mandelbrot()` arguments or an integer in [1,3] specifying a predefined Mandelbrot region. (Default: `1L`)

future.demo.mandelbrot.nrow:

  Number of rows and columns of tiles. (Default: `3L`)

### See Also

To set R options when R starts (even before the future package is loaded), see the Startup help page. The startup package provides a friendly mechanism for configurating R's startup process.

[Package future version 1.8.0 Index]