future (version 1.16.0)

future.options: 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.

Arguments

Options for controlling futures

future.plan:

(character string or future function) 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:

(character string) 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: "ignore")

future.globals.method:

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

future.globals.maxSize:

(numeric) 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:

(logical) 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 feature - may change)

(character string) 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", 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. If the option is not set, then environment variable R_FUTURE_GLOBALS_ONREFERENCE is used. (Default: "ignore" but may change)

future.resolve.recursive:

(integer) 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.rng.onMisuse: (beta feature - may change)

(character string) If random numbers are used in futures, then parallel (L'Ecuyer-CMRG) RNG should be used in order to get statistical sound RNGs. The defaults in the future framework assume that no random number generation (RNG) is taken place in the future expression because L'Ecuyer-CMRG RNGs come with an unnecessary overhead if not needed. To protect against mistakes, the future framework attempts to detect when random numbers are used despite L'Ecuyer-CMRG RNGs are not in place. If this is detected, and future.rng.onMisuse = "error", then an informative error message is produced. If "warning", then a warning message is produced. If "ignore", no check is performed. If the option is not set, then environment variable R_FUTURE_RNG_ONMISUSE is used. (Default: "ignore" but may change)

future.wait.timeout:

(numeric) Maximum waiting time (in seconds) for a free worker before a timeout error is generated. If the option is not set, then environment variable R_FUTURE_WAIT_TIMEOUT is used. (Default: 30 * 24 * 60 * 60 (= 30 days))

future.wait.interval:

(numeric) Initial interval (in seconds) between polls. If the option is not set, then environment variable R_FUTURE_WAIT_INTERVAL is used. (Default: 0.2 = 0.2 seconds)

future.wait.alpha:

(numeric) Positive scale factor used to increase the interval after each poll. If the option is not set, then environment variable R_FUTURE_WAIT_ALPHA is used. (Default: 1.01)

Options for debugging futures

future.debug:

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

Options for controlling package startup

future.startup.script:

(character vector or a logical) Specifies zero of more future startup scripts to be sourced when the future package is attached. It is only the first existing script that is sourced. If none of the specified files exist, nothing is sourced - there will be neither a warning nor an error. If this option is not specified, environment variable R_FUTURE_STARTUP_SCRIPT is considered, where multiple scripts may be separated by either a colon (:) or a semicolon (;). If neither is set, or either is set to TRUE, the default is to look for a .future.R script in the current directory and then in the user's home directory. To disable future startup scripts, set the option or the environment variable to FALSE. 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:

(character vector) Overrides commandArgs() when the future package is loaded.

Options for configuring low-level system behaviors

future.availableCores.methods:

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

future.availableCores.custom:

(function) If set and a function, then this function will be called (without arguments) by availableCores() where its value, coerced to an integer, is interpreted as a number of cores.

future.availableCores.fallback:

(integer) 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 multi-tenant environment, such as HPC clusters, it is useful to set R_FUTURE_AVAILABLECORES_FALLBACK to 1.

future.availableCores.system:

(integer) 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.

future.availableWorkers.methods:

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

future.availableWorkers.custom:

(function) If set and a function, then this function will be called (without arguments) by availableWorkers() where its value, coerced to a character vector, is interpreted as hostnames of available workers.

future.fork.enable:

(logical) Enable or disable forked processing. If FALSE, multicore futures becomes sequential futures. If not specified, this option is set according to environment variable R_FUTURE_FORK_ENABLE. If NA, or not set (the default), the a set of best-practices rules decide whether should be supported or not. See supportsMulticore() for more details.

future.fork.multithreading.enable (beta feature - may change):

(logical) Enable or disable multi-threading while using forked parallel processing. If FALSE, different multi-thread library settings are overridden such that they run in single-thread mode, which requires that the RhpcBLASctl package is installed. If not specified, this option is set according to environment variable R_FUTURE_FORK_MULTITHREADING_ENABLE. If TRUE, or not set (the default), multi-threading is allowed. Parallelization via multi-threaded processing (done in native code by some packages and external libraries) while at the same time using forked (aka "multicore") parallel processing is known to unstable. Note that this is not only true when using plan(multicore) but also when using, for instance, parallel::mclapply().

future.supportsMulticore.unstable:

(character) Controls whether a warning should be produced or not whenever multicore processing is automatically disabled because the environment in which R runs is considered unstable for forked processing, e.g. in the RStudio environment. If "warning" (default), then an informative warning is produces the first time 'multicore' or 'multiprocess' futures are used. If "quiet", no warning is produced. If not specified, this option is set according to environment variable R_FUTURE_SUPPORTSMULTICORE_UNSTABLE. See supportsMulticore() for more details.

Options for demos

future.demo.mandelbrot.region:

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

future.demo.mandelbrot.nrow:

(integer) 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.