Movatterモバイル変換

Version:	1.68.0
Title:	Unified Parallel and Distributed Processing in R for Everyone
Depends:	R (≥ 3.2.0)
Imports:	digest, globals (≥ 0.18.0), listenv (≥ 0.8.0), parallel,parallelly (≥ 1.44.0), utils
Suggests:	methods, RhpcBLASctl, R.rsp, markdown
VignetteBuilder:	R.rsp
Description:	The purpose of this package is to provide a lightweight and unified Future API for sequential and parallel processing of R expression via futures. The simplest way to evaluate an expression in parallel is to use 'x %<-% { expression }' with 'plan(multisession)'. This package implements sequential, multicore, multisession, and cluster futures. With these, R expressions can be evaluated on the local machine, in parallel a set of local machines, or distributed on a mix of local and remote machines. Extensions to this package implement additional backends for processing futures via compute cluster schedulers, etc. Because of its unified API, there is no need to modify any code in order switch from sequential on the local machine to, say, distributed processing on a remote compute cluster. Another strength of this package is that global variables and functions are automatically identified and exported as needed, making it straightforward to tweak existing code to make use of futures.
License:	LGPL-2.1 |LGPL-3 [expanded from: LGPL (≥ 2.1)]
LazyLoad:	TRUE
ByteCompile:	TRUE
URL:	https://future.futureverse.org,https://github.com/futureverse/future
BugReports:	https://github.com/futureverse/future/issues
Language:	en-US
Encoding:	UTF-8
RoxygenNote:	7.3.3
Collate:	'000.bquote.R' '000.import.R' '000.re-exports.R''010.tweakable.R' '010.utils-parallelly.R''backend_api-01-FutureBackend-class.R''backend_api-03.MultiprocessFutureBackend-class.R''backend_api-11.ClusterFutureBackend-class.R''backend_api-11.MulticoreFutureBackend-class.R''backend_api-11.SequentialFutureBackend-class.R''backend_api-13.MultisessionFutureBackend-class.R''backend_api-ConstantFuture-class.R''backend_api-Future-class.R' 'backend_api-FutureRegistry.R''backend_api-UniprocessFuture-class.R''backend_api-evalFuture.R' 'core_api-cancel.R''core_api-future.R' 'core_api-reset.R' 'core_api-resolved.R''core_api-value.R' 'delayed_api-futureAssign.R''delayed_api-futureOf.R' 'demo_api-mandelbrot.R''infix_api-01-futureAssign_OP.R' 'infix_api-02-globals_OP.R''infix_api-03-seed_OP.R' 'infix_api-04-stdout_OP.R''infix_api-05-conditions_OP.R' 'infix_api-06-lazy_OP.R''infix_api-07-label_OP.R' 'infix_api-08-plan_OP.R''infix_api-09-tweak_OP.R''protected_api-FutureCondition-class.R''protected_api-FutureGlobals-class.R''protected_api-FutureResult-class.R' 'protected_api-futures.R''protected_api-globals.R' 'protected_api-journal.R''protected_api-resolve.R' 'protected_api-signalConditions.R''testme.R' 'utils-basic.R' 'utils-conditions.R''utils-connections.R' 'utils-debug.R''utils-immediateCondition.R' 'utils-marshalling.R''utils-objectSize.R' 'utils-options.R' 'utils-prune_pkg_code.R''utils-registerClusterTypes.R' 'utils-rng_utils.R''utils-signalEarly.R' 'utils-stealth_sample.R''utils-sticky_globals.R' 'utils-tweakExpression.R''utils-uuid.R' 'utils-whichIndex.R' 'utils_api-backtrace.R''utils_api-capture_journals.R' 'utils_api-futureCall.R''utils_api-futureSessionInfo.R' 'utils_api-makeClusterFuture.R''utils_api-minifuture.R' 'utils_api-nbrOfWorkers.R''utils_api-plan.R' 'utils_api-plan-with.R''utils_api-sessionDetails.R' 'utils_api-tweak.R' 'zzz.R'
NeedsCompilation:	no
Packaged:	2025-11-16 21:57:30 UTC; hb
Author:	Henrik Bengtsson [aut, cre, cph]
Maintainer:	Henrik Bengtsson <henrikb@braju.com>
Repository:	CRAN
Date/Publication:	2025-11-17 06:10:09 UTC

Gets the length of an object without dispatching

Description

Gets the length of an object without dispatching

Usage

.length(x)

Arguments

Details

This function returnslength(unclass(x)), but tries to avoidcallingunclass(x) unless necessary.

Value

A non-negative integer.

See Also

.subset() and.subset2().

A future represents a value that will be available at some point in the future

Description

Afuture is an abstraction for avalue that mayavailable at some point in the future. A future can either beunresolved orresolved, a state which can be checkedwithresolved(). As long as it isunresolved, thevalue is not available. As soon as it isresolved, the valueis available viavalue().

Usage

Future(  expr = NULL,  envir = parent.frame(),  substitute = TRUE,  stdout = TRUE,  conditions = "condition",  globals = list(),  packages = NULL,  seed = FALSE,  lazy = FALSE,  gc = FALSE,  earlySignal = FALSE,  label = NULL,  ...)

Arguments

Details

A Future object is itself anenvironment.

Value

Future() returns an object of classFuture.

See Also

One function that creates a Future isfuture().It returns a Future that evaluates anR expression in the future.An alternative approach is to use the%<-% infixassignment operator, which creates a future from theright-hand-side (RHS)R expression and assigns its future valueto a variable as apromise.

Configure a backend that controls how and where futures are evaluated

Description

This functionality is only for developers who wish to implement theirown future backend. End-users and package developers use futureverse,does not need to know about these functions.

If you are looking for available future backends to choose from, pleasesee the 'A Future for R: Available Future Backends' vignette andhttps://www.futureverse.org/backends.html.

Usage

FutureBackend(  ...,  earlySignal = FALSE,  gc = FALSE,  maxSizeOfObjects = getOption("future.globals.maxSize", +Inf),  interrupts = TRUE,  hooks = FALSE)launchFuture(backend, future, ...)listFutures(backend, ...)interruptFuture(backend, future, ...)validateFutureGlobals(backend, future, ...)stopWorkers(backend, ...)MultiprocessFutureBackend(  ...,  wait.timeout = getOption("future.wait.timeout", 24 * 60 * 60),  wait.interval = getOption("future.wait.interval", 0.01),  wait.alpha = getOption("future.wait.alpha", 1.01))ClusterFutureBackend(  workers = availableWorkers(constraints = "connections"),  gc = TRUE,  earlySignal = TRUE,  interrupts = FALSE,  persistent = FALSE,  ...)MulticoreFutureBackend(  workers = availableCores(constraints = "multicore"),  maxSizeOfObjects = +Inf,  ...)SequentialFutureBackend(..., maxSizeOfObjects = +Inf)MultisessionFutureBackend(  workers = availableCores(constraints = "connections-16"),  rscript_libs = .libPaths(),  interrupts = TRUE,  gc = FALSE,  earlySignal = FALSE,  ...)

Arguments

Details

TheClusterFutureBackend is selected byplan(cluster, workers = workers).

TheMulticoreFutureBackend backend is selected byplan(multicore, workers = workers).

TheSequentialFutureBackend is selected byplan(sequential).

TheMultisessionFutureBackend backend is selected byplan(multisession, workers = workers).

Value

FutureBackend() returns a FutureBackend object, which inherits anenvironment. Specific future backends are defined by subclassesimplementing the FutureBackend API.

launchFuture() returns the launchedFuture object.

interruptFuture() returns the interruptedFuture object,if supported, other the unmodified future.

stopWorkers() returns TRUE if the workers were shut down,otherwise FALSE.

The FutureBackend API

TheFutureBackend class specifies FutureBackend API,that all backends must implement and comply to. Specifically,

See Also

For alternative future backends, see the 'A Future for R: Available FutureBackends' vignette andhttps://www.futureverse.org/backends.html.

For alternative future backends, see the 'A Future for R: Available FutureBackends' vignette andhttps://www.futureverse.org/backends.html.

A condition (message, warning, or error) that occurred while orchestrating a future

Description

Whileorchestrating (creating, launching, querying, collection)futures, unexpected run-time errors (and other types of conditions) mayoccur. Such conditions are coerced to a corresponding FutureConditionclass to help distinguish them from conditions that occur due to theevaluation of the future.

Usage

FutureCondition(message, call = NULL, uuid = future[["uuid"]], future = NULL)FutureMessage(message, call = NULL, uuid = future[["uuid"]], future = NULL)FutureWarning(message, call = NULL, uuid = future[["uuid"]], future = NULL)FutureError(message, call = NULL, uuid = future[["uuid"]], future = NULL)RngFutureCondition(  message = NULL,  call = NULL,  uuid = future[["uuid"]],  future = NULL)RngFutureWarning(...)RngFutureError(...)UnexpectedFutureResultError(future, hint = NULL)GlobalEnvMisuseFutureCondition(  message = NULL,  call = NULL,  differences = NULL,  uuid = future[["uuid"]],  future = NULL)GlobalEnvMisuseFutureWarning(...)GlobalEnvMisuseFutureError(...)ConnectionMisuseFutureCondition(  message = NULL,  call = NULL,  differences = NULL,  uuid = future[["uuid"]],  future = NULL)ConnectionMisuseFutureWarning(...)ConnectionMisuseFutureError(...)DeviceMisuseFutureCondition(  message = NULL,  call = NULL,  differences = NULL,  uuid = future[["uuid"]],  future = NULL)DeviceMisuseFutureWarning(...)DeviceMisuseFutureError(...)DefaultDeviceMisuseFutureCondition(  message = NULL,  incidents = NULL,  call = NULL,  uuid = future[["uuid"]],  future = NULL)DefaultDeviceMisuseFutureWarning(...)DefaultDeviceMisuseFutureError(...)FutureLaunchError(..., future = NULL)FutureInterruptError(..., future = NULL)FutureCanceledError(..., future = NULL)FutureDroppedError(..., future = NULL)FutureJournalCondition(  message,  journal,  call = NULL,  uuid = future[["uuid"]],  future = NULL)

Arguments

Value

An object of class FutureCondition which inherits from classcondition and FutureMessage, FutureWarning,and FutureError all inherits from FutureCondition.Moreover, a FutureError inherits fromerror,a FutureWarning fromwarning, anda FutureMessage frommessage.

A representation of a set of globals used with futures

Description

A representation of a set of globals used with futures

Usage

FutureGlobals(object = list(), resolved = FALSE, total_size = NA_real_, ...)

Arguments

Details

This class extends theGlobals class by addingattributesresolved andtotal_size.

Value

An object of classFutureGlobals.

Results from resolving a future

Description

Results from resolving a future

Usage

FutureResult(  value = NULL,  visible = TRUE,  stdout = NULL,  conditions = NULL,  rng = FALSE,  ...,  uuid = NULL,  started = .POSIXct(NA_real_),  finished = Sys.time(),  version = "1.8")## S3 method for class 'FutureResult'as.character(x, ...)## S3 method for class 'FutureResult'print(x, ...)

Arguments

Details

This function is only part of thebackend Future API.This function isnot part of the frontend Future API.

Value

An object of class FutureResult.

Note to developers

The FutureResult structure isunder development and may change at anytime,e.g. elements may be renamed or removed. Because of this, please avoidaccessing the elements directly in code. Feel free to reach out if you needto do so in your code.

A multiprocess future is a future whose value will be resolved asynchronously in a parallel process

Description

A multiprocess future is a future whose value will be resolved asynchronously in a parallel process

Usage

MultiprocessFuture(expr = NULL, substitute = TRUE, envir = parent.frame(), ...)

Arguments

Value

MultiprocessFuture() returns an object of classMultiprocessFuture.

An uniprocess future is a future whose value will be resolved synchronously in the current process

Description

An uniprocess future is a future whose value will be resolved synchronously in the current process

Usage

UniprocessFuture(expr = NULL, substitute = TRUE, envir = parent.frame(), ...)

Arguments

Value

UniprocessFuture() returns an object of classUniprocessFuture.

Back trace the expressions evaluated when an error was caught

Description

Back trace the expressions evaluated when an error was caught

Usage

backtrace(future, envir = parent.frame(), ...)

Arguments

Value

A list with the future's call stack that led up to the error.

Examples

my_log <- function(x) log(x)foo <- function(...) my_log(...)f <- future({ foo("a") })res <- tryCatch({  v <- value(f)}, error = function(ex) {  t <- backtrace(f)  print(t)})

Cancel a future

Description

Cancels futures, with the option to interrupt running ones.

Usage

cancel(x, interrupt = TRUE, ...)

Arguments

Value

cancel() returns (invisibly) the canceledFutures afterflagging them as "canceled" and possibly interrupting them as well.

Canceling a lazy or a finished future has no effect.

See Also

A canceled future can bereset() to a lazy, vanilla futuresuch that it can be relaunched, possible on another future backend.

Examples

## Set up two parallel workersplan(multisession, workers = 2)## Launch two long running futurefs <- lapply(c(1, 2), function(duration) {  future({    Sys.sleep(duration)    42  })})## Wait until at least one of the futures is resolvedwhile (!any(resolved(fs))) Sys.sleep(0.1)## Cancel the future that is not yet resolvedr <- resolved(fs)cancel(fs[!r])## Get the value of the resolved futuref <- fs[r]v <- value(f)message("Result: ", v)## The value of the canceled future is an errortry(v <- value(fs[!r]))## Shut down parallel workersplan(sequential)

Create a cluster future whose value will be resolved asynchronously in a parallel process

Description

WARNING: This function must never be called.It may only be used withplan()

Usage

cluster(  ...,  workers = availableWorkers(constraints = "connections"),  persistent = FALSE)

Arguments

Details

A cluster future is a future that uses cluster evaluation,which means that itsvalue is computed and resolved inparallel in another process.

This function is mustnot be called directly. Instead, thetypical usages are:

# Evaluate futures via a single background R process on the local machineplan(cluster, workers = I(1))# Evaluate futures via two background R processes on the local machineplan(cluster, workers = 2)# Evaluate futures via a single R process on another machine on on the# local area network (LAN)plan(cluster, workers = "raspberry-pi")# Evaluate futures via a single R process running on a remote machineplan(cluster, workers = "pi.example.org")# Evaluate futures via four R processes, one running on the local machine,# two running on LAN machine 'n1' and one on a remote machineplan(cluster, workers = c("localhost", "n1", "n1", "pi.example.org"))

See Also

For alternative future backends, see the 'A Future for R: Available FutureBackends' vignette andhttps://www.futureverse.org/backends.html.

Examples

## Use cluster futurescl <- parallel::makeCluster(2, timeout = 60)plan(cluster, workers = cl)## A global variablea <- 0## Create future (explicitly)f <- future({  b <- 3  c <- 2  a * b * c})## A cluster future is evaluated in a separate process.## Regardless, changing the value of a global variable will## not affect the result of the future.a <- 7print(a)v <- value(f)print(v)stopifnot(v == 0)## CLEANUPparallel::stopCluster(cl)

Export globals to the sticky-globals environment of the cluster nodes

Description

Export globals to the sticky-globals environment of the cluster nodes

Usage

clusterExportSticky(cl, globals)

Arguments

Details

This requires that thefuture package is installed on the clusternodes.

Value

(invisible; cluster) The cluster object.

Get the first or all references of anR object

Description

Get the first or all references of anR object

Assert that there are no references among the identified globals

Usage

find_references(x, first_only = FALSE)assert_no_references(  x,  action = c("error", "warning", "message", "string"),  source = c("globals", "value"))

Arguments

Value

find_references() returns a list of zero or more referencesidentified.

If a reference is detected, an informative error, warning, message,or a character string is produced, otherwiseNULL is returnedinvisibly.

Create a future

Description

Creates a future that evaluates anR expression ora future that calls anR function with a set of arguments.How, when, and where these futures are evaluated can be configuredusingplan() such that it is evaluated in parallel on,for instance, the current machine, on a remote machine, or via ajob queue on a compute cluster.Importantly, anyR code using futures remains the same regardlesson these settings and there is no need to modify the code whenswitching from, say, sequential to parallel processing.

Usage

future(  expr,  envir = parent.frame(),  substitute = TRUE,  lazy = FALSE,  seed = FALSE,  globals = TRUE,  packages = NULL,  stdout = TRUE,  conditions = "condition",  label = NULL,  gc = FALSE,  earlySignal = FALSE,  ...)futureCall(  FUN,  args = list(),  envir = parent.frame(),  lazy = FALSE,  seed = FALSE,  globals = TRUE,  packages = NULL,  stdout = TRUE,  conditions = "condition",  earlySignal = FALSE,  label = NULL,  gc = FALSE,  ...)minifuture(  expr,  substitute = TRUE,  globals = NULL,  packages = NULL,  stdout = NA,  conditions = NULL,  seed = NULL,  ...,  envir = parent.frame())

Arguments

Details

The state of a future is either unresolved or resolved.The value of a future can be retrieved usingv <-value(f).Querying the value of a non-resolved future willblock the calluntil the future is resolved.It is possible to check whether a future is resolved or notwithout blocking by usingresolved(f).It is possible tocancel() a future that is being resolved.Failed, canceled, and interrupted futures can bereset() to alazy, vanilla future that can be relaunched.

ThefutureCall() function works analogously todo.call(), which calls a function with a set ofarguments. The difference is thatdo.call() returns the value ofthe call whereasfutureCall() returns a future.

Value

future() returnsFuture that evaluates expressionexpr.

futureCall() returns aFuture that calls functionFUN withargumentsargs.

minifuture(expr) creates a future with minimal overhead, by disablinguser-friendly behaviors, e.g. automatic identification of globalvariables and packages needed, and relaying of output. Unless you havegood reasons for using this function, please usefuture() instead.This function exists mainly for the purpose of profiling and identifyingwhich automatic features offuture() introduce extra overhead.

Eager or lazy evaluation

By default, a future is resolved usingeager evaluation(lazy = FALSE). This means that the expression starts tobe evaluated as soon as the future is created.

As an alternative, the future can be resolved usinglazyevaluation (lazy = TRUE). This means that the expressionwill only be evaluated when the value of the future is requested.Note that this means that the expression may not be evaluatedat all - it is guaranteed to be evaluated if the value is requested.

Globals used by future expressions

Global objects (shortglobals) are objects (e.g. variables andfunctions) that are needed in order for the future expression to beevaluated while not being local objects that are defined by the futureexpression. For example, in

  a <- 42  f <- future({ b <- 2; a * b })

variablea is a global of future assignmentf whereasb is a local variable.In order for the future to be resolved successfully (and correctly),all globals need to be gathered when the future is created such thatthey are available whenever and wherever the future is resolved.

The default behavior (globals = TRUE),is that globals are automatically identified and gathered.More precisely, globals are identified via code inspection of thefuture expressionexpr and their values are retrieved withenvironmentenvir as the starting point (basically viaget(global, envir = envir, inherits = TRUE)).In most cases, such automatic collection of globals is sufficientand less tedious and error prone than if they are manually specified.

However, for full control, it is also possible to explicitly specifyexactly which the globals are by providing their names as a charactervector.In the above example, we could use

  a <- 42  f <- future({ b <- 2; a * b }, globals = "a")

Yet another alternative is to explicitly specify also their valuesusing a named list as in

  a <- 42  f <- future({ b <- 2; a * b }, globals = list(a = a))

or

  f <- future({ b <- 2; a * b }, globals = list(a = 42))

Specifying globals explicitly avoids the overhead added fromautomatically identifying the globals and gathering their values.Furthermore, if we know that the future expression does not make useof any global variables, we can disable the automatic search forglobals by using

  f <- future({ a <- 42; b <- 2; a * b }, globals = FALSE)

Future expressions often make use of functions from one or more packages.As long as these functions are part of the set of globals, the futurepackage will make sure that those packages are attached when the futureis resolved. Because there is no need for such globals to be frozenor exported, the future package will not export them, which reducesthe amount of transferred objects.For example, in

  x <- rnorm(1000)  f <- future({ median(x) })

variablex andmedian() are globals, but onlyxis exported whereasmedian(), which is part of thestatspackage, is not exported. Instead it is made sure that thestatspackage is on the search path when the future expression is evaluated.Effectively, the above becomes

  x <- rnorm(1000)  f <- future({    library(stats)    median(x)  })

To manually specify this, one can either do

  x <- rnorm(1000)  f <- future({    median(x)  }, globals = list(x = x, median = stats::median)

or

  x <- rnorm(1000)  f <- future({    library(stats)    median(x)  }, globals = list(x = x))

Both are effectively the same.

Although rarely needed, a combination of automatic identification and manualspecification of globals is supported via attributesadd (to addfalse negatives) andignore (to ignore false positives) on valueTRUE. For example, withglobals = structure(TRUE, ignore = "b", add = "a") any globalsautomatically identified, exceptb, will be used, in addition toglobala.

Author(s)

The future logo was designed by Dan LaBar and tweaked by Henrik Bengtsson.

See Also

How, when and where futures are resolved is given by thefuture backend, which can be set by the end user using theplan() function.

Examples

## Evaluate futures in parallelplan(multisession)## Datax <- rnorm(100)y <- 2 * x + 0.2 + rnorm(100)w <- 1 + x ^ 2## EXAMPLE: Regular assignments (evaluated sequentially)fitA <- lm(y ~ x, weights = w)      ## with offsetfitB <- lm(y ~ x - 1, weights = w)  ## without offsetfitC <- {  w <- 1 + abs(x)  ## Different weights  lm(y ~ x, weights = w)}print(fitA)print(fitB)print(fitC)## EXAMPLE: Future assignments (evaluated in parallel)fitA %<-% lm(y ~ x, weights = w)      ## with offsetfitB %<-% lm(y ~ x - 1, weights = w)  ## without offsetfitC %<-% {  w <- 1 + abs(x)  lm(y ~ x, weights = w)}print(fitA)print(fitB)print(fitC)## EXAMPLE: Explicitly create futures (evaluated in parallel)## and retrieve their valuesfA <- future( lm(y ~ x, weights = w) )fB <- future( lm(y ~ x - 1, weights = w) )fC <- future({  w <- 1 + abs(x)  lm(y ~ x, weights = w)})fitA <- value(fA)fitB <- value(fB)fitC <- value(fC)print(fitA)print(fitB)print(fitC)## EXAMPLE: futureCall() and do.call()x <- 1:100y0 <- do.call(sum, args = list(x))print(y0)f1 <- futureCall(sum, args = list(x))y1 <- value(f1)print(y1)

Create a future assignment

Description

x %<-% value (also known as a "future assignment") andfutureAssign("x", value) create aFuture that evaluates the expression(value) and binds it to variablex (as apromise). The expression is evaluated in parallelin the background. Later on, whenx is first queried, the value of futureis automatically retrieved as it were a regular variable andx ismaterialized as a regular value.

Usage

futureAssign(  x,  value,  envir = parent.frame(),  substitute = TRUE,  lazy = FALSE,  seed = FALSE,  globals = TRUE,  packages = NULL,  stdout = TRUE,  conditions = "condition",  earlySignal = FALSE,  label = NULL,  gc = FALSE,  ...,  assign.env = envir)x %<-% valuefassignment %globals% globalsfassignment %packages% packagesfassignment %seed% seedfassignment %stdout% capturefassignment %conditions% capturefassignment %lazy% lazyfassignment %label% labelfassignment %plan% strategyfassignment %tweak% tweaks

Arguments

Details

For a future created via a future assignment,x %<-% value orfutureAssign("x", value), the value is bound to a promise, which whenqueried will internally callvalue() on the future and which will thenbe resolved into a regular variable bound to that value. For example, withfuture assignmentx %<-% value, the first time variablex is queriedthe call blocks if, and only if, the future is not yet resolved. As soonas it is resolved, and any succeeding queries, queryingx willimmediately give the value.

The future assignment constructx %<-% value is not a formal assignmentper se, but a binary infix operator on objectsx and expressionvalue.However, by using non-standard evaluation, this constructs can emulate anassignment operator similar tox <- value. Due toR's precedence rulesof operators, future expressions often need to be explicitly bracketed,e.g.x %<-% { a + b }.

Value

futureAssign() andx %<-% expr returns theFuture invisibly,e.g.f <- futureAssign("x", expr) andf <- (x %<-% expr).

Adjust future arguments of a future assignment

future() andfutureAssign() take several arguments that can be usedto explicitly specify what global variables and packages the future shoulduse. They can also be used to override default behaviors of the future,e.g. whether output should be relayed or not. When using a futureassignment, these arguments can be specified via correspondingassignment expression. For example,x %<-% { rnorm(10) } %seed% TRUEcorresponds tofutureAssign("x", { rnorm(10) }, seed = TRUE). Here area several examples.

To explicitly specify variables and functions that a future assignmentshould use, use⁠%globals%⁠. To explicitly specify which packages needto be attached for the evaluate to success, use⁠%packages%⁠. Forexample,

> x <- rnorm(1000)> y %<-% { median(x) } %globals% list(x = x) %packages% "stats"> y[1] -0.03956372

Themedian() function is part of the 'stats' package.

To declare that you will generate random numbers, use⁠%seed%⁠, e.g.

> x %<-% { rnorm(3) } %seed% TRUE> x[1] -0.2590562 -1.2262495  0.8858702

To disable relaying of standard output (e.g.print(),cat(), andstr()), while keeping relaying of conditions (e.g.message() and

> x %<-% { cat("Hello\n"); message("Hi there"); 42 } %stdout% FALSE> y <- 13> z <- x + yHi there> z[1] 55

To disable relaying of conditions, use⁠%conditions%⁠, e.g.

> x %<-% { cat("Hello\n"); message("Hi there"); 42 } %conditions% character(0)> y <- 13> z <- x + yHello> z[1] 55

> x %<-% { print(1:10); message("Hello"); 42 } %stdout% FALSE> y <- 13> z <- x + yHello> z[1] 55

To create a future without launching in such that it will only beprocessed if the value is really needed, use⁠%lazy%⁠, e.g.

> x %<-% { Sys.sleep(5); 42 } %lazy% TRUE> y <- sum(1:10)> system.time(z <- x + y)  user  system elapsed   0.004   0.000   5.008> z[1] 97

Error handling

Because future assignments are promises, errors produced by the thefuture expression will not be signaled until the value of the future isrequested. For example, if you create a future assignment that producean error, you will not be affected by the error until you "touch" thefuture-assignment variable. For example,

> x %<-% { stop("boom") }> y <- sum(1:10)> z <- x + yError in eval(quote({ : boom

Use alternative future backend for future assignment

Futures are evaluated on the future backend that the user has specifiedbyplan(). With regular futures, we can temporarily use another futurebackend by wrapping our code in⁠with(plan(...), { ... }]⁠, or temporarilyinside a function usingwith(plan(...), local = TRUE). To achieve thesame for a specific future assignment, use⁠%plan%⁠, e.g.

> plan(multisession)> x %<-% { 42 }> y %<-% { 13 } %plan% sequential> z <- x + y> z[1] 55

Herex is resolved in the background via themultisession backend,whereasy is resolved sequentially in the main R session.

Getting the future object of a future assignment

The underlyingFuture of a future variablex can be retrieved withoutblocking usingf <-futureOf(x), e.g.

> x %<-% { stop("boom") }> f_x <- futureOf(x)> resolved(f_x)[1] TRUE> xError in eval(quote({ : boom> value(f_x)Error in eval(quote({ : boom

Technically, both the future and the variable (promise) are assigned atthe same time to environmentassign.env where the name of the future is⁠.future_<name>⁠.

Get the future of a future variable

Description

Get the future of a future variable that has been created directlyor indirectly viafuture().

Usage

futureOf(  var = NULL,  envir = parent.frame(),  mustExist = TRUE,  default = NA,  drop = FALSE)

Arguments

Value

AFuture (ordefault).Ifvar is NULL, then a named list of Future:s are returned.

Examples

a %<-% { 1 }f <- futureOf(a)print(f)b %<-% { 2 }f <- futureOf(b)print(f)## All futuresfs <- futureOf()print(fs)## Futures part of environmentenv <- new.env()env$c %<-% { 3 }f <- futureOf(env$c)print(f)f2 <- futureOf(c, envir = env)print(f2)f3 <- futureOf("c", envir = env)print(f3)fs <- futureOf(envir = env)print(fs)

Get future-specific session information and validate current backend

Description

Get future-specific session information and validate current backend

Usage

futureSessionInfo(test = TRUE, anonymize = TRUE)

Arguments

Value

Nothing.

Examples

plan(multisession, workers = 2)futureSessionInfo()plan(sequential)

Get all futures in a container

Description

Gets all futures in an environment, a list, or a list environmentand returns an object of the same class (and dimensions).Non-future elements are returned as is.

Usage

futures(x, ...)

Arguments

Details

This function is useful for retrieve futures that were created viafuture assignments (⁠%<-%⁠) and therefore stored as promises.This function turns such promises into standardFutureobjects.

Value

An object of same type asx and with the same namesand/or dimensions, if set.

Inject code for the next type of future to use for nested futures

Description

Inject code for the next type of future to use for nested futures

Usage

getExpression(future, ...)

Arguments

Details

If there is no future backend specified after this one, the defaultis to usesequential futures. This conservative approach protectsagainst spawning off recursive futures by mistake, especiallymulticore andmultisession ones.The default will also setoptions(mc.cores = 1L) (*) so thatno parallelR processes are spawned off by functions such asparallel::mclapply() and friends.

Currently it is not possible to specify what type of nestedfutures to be used, meaning the above default will always beused.SeeIssue #37for plans on adding support for custom nested future types.

(*) Ideally we would setmc.cores = 0 but that will unfortunatelycausemclapply() and friends to generate an error saying"'mc.cores' must be >= 1". Ideally those functions shouldfall back to using the non-multicore alternative in thiscase, e.g.mclapply(...) =>lapply(...).Seehttps://github.com/HenrikBengtsson/Wishlist-for-R/issues/7for a discussion on this.

Value

A future expression with code injected to set whattype of future to use for nested futures, iff any.

Retrieves global variables of an expression and their associated packages

Description

Retrieves global variables of an expression and their associated packages

Usage

getGlobalsAndPackages(  expr,  envir = parent.frame(),  tweak = tweakExpression,  globals = TRUE,  locals = getOption("future.globals.globalsOf.locals", TRUE),  resolve = getOption("future.globals.resolve"),  persistent = FALSE,  maxSize = getOption("future.globals.maxSize", 500 * 1024^2),  onReference = getOption("future.globals.onReference", "ignore"),  ...)

Arguments

Value

A named list with elementsexpr (the tweaked expression),globals (a named list of classFutureGlobals) andpackages (a character string).

See Also

Internally,globalsOf() is used to identify globals and associated packages from the expression.

Create a Future Cluster of Stateless Workers for Parallel Processing

Description

WARNING: Please note that this sets up a stateless set of cluster nodes,which means thatclusterEvalQ(cl, { a <- 3.14 }) will not work.Consider this a first beta version and use it with great care,particularly because of the stateless nature of the cluster.For now, I recommend to manually validate that you can get identicalresults using this cluster type with what you get from using theclassicalparallel::makeCluster() cluster type.

Usage

makeClusterFuture(specs = nbrOfWorkers(), ...)

Arguments

Value

Returns aparallelcluster object of classFutureCluster.

Future Clusters are Stateless

Traditionally, a cluster nodes has a one-to-one mapping to a clusterworker process. For example,cl <- makeCluster(2, type = "PSOCK")launches two parallel worker processes in the background, wherecluster nodecl[[1]] maps to worker #1 and nodecl[[2]] toworker #2, and that never changes through the lifespan of theseworkers. This one-to-one mapping allows for deterministicconfiguration of workers. For examples, some code may assign globalswith values specific to each worker, e.g.clusterEvalQ(cl[1], { a <- 3.14 }) andclusterEvalQ(cl[2], { a <- 2.71 }).

In contrast, there is no one-to-one mapping between cluster nodesand the parallel workers when using a future cluster. This is becausewe cannot make assumptions on where are parallel task will beprocessed. Where a parallel task is processes is up to the futurebackend to decide - some backends do this deterministically, whereasothers other resolves task at the first available worker. Also, theworker processes might betransient for some future backends, i.e.the only exist for the life-span of the parallel task and thenterminates.

Because of this, one must not rely in node-specific behaviors,because that concept does not make sense with a future cluster.To protect against this, any attempt to address a subset of futurecluster nodes, results in an error, e.g.clusterEvalQ(cl[1], ...),clusterEvalQ(cl[1:2], ...), andclusterEvalQ(cl[2:1], ...) inthe above example will all give an error.

Exceptions to the latter limitation areclusterSetRNGStream()andclusterExport(), which can be safely used with future clusters.See below for more details.

clusterSetRNGStream

parallel::clusterSetRNGStream() distributes "L'Ecuyer-CMRG" RNGstreams to the cluster nodes, which record them such that the nextround of futures will use them. When used, the RNG state after thefutures are resolved are recorded accordingly, such that the nextround again of future will use those, and so on. This strategymakes sureclusterSetRNGStream() has the expected effect althoughfutures are stateless.

clusterExport

parallel::clusterExport() assign values to the cluster nodes.Specifically, these values are recorded and are used as globalsfor all futures created there on.

clusterEvalQ

IfclusterEvalQ() is called, the call is ignored, and an erroris produced. The error can be de-escalated to a warning by settingR optionfuture.ClusterFuture.clusterEvalQ to"warning".

Examples

plan(multisession)cl <- makeClusterFuture()parallel::clusterSetRNGStream(cl)y <- parallel::parLapply(cl, 11:13, function(x) {  message("Process ID: ", Sys.getpid())  mean(rnorm(n = x))})str(y)plan(sequential)

Mandelbrot convergence counts

Description

Mandelbrot convergence counts

Usage

mandelbrot(...)## S3 method for class 'matrix'mandelbrot(Z, maxIter = 200L, tau = 2, ...)## S3 method for class 'numeric'mandelbrot(  xmid = -0.75,  ymid = 0,  side = 3,  resolution = 400L,  maxIter = 200L,  tau = 2,  ...)

Arguments

Value

Returns an integer matrix (of class Mandelbrot) withnon-negative counts.

Author(s)

The internal Mandelbrot algorithm was inspired by andadopted from similar GPL code of Martin Maechler availablefrom ftp://stat.ethz.ch/U/maechler/R/ on 2005-02-18 (sic!).

Examples

counts <- mandelbrot(xmid = -0.75, ymid = 0, side = 3)str(counts)## Not run: plot(counts)## End(Not run)## Not run: demo("mandelbrot", package = "future", ask = FALSE)## End(Not run)

Create a multicore future whose value will be resolved asynchronously in a forked parallel process

Description

WARNING: This function must never be called.It may only be used withplan()

Usage

multicore(..., workers = availableCores(constraints = "multicore"))

Arguments

Details

A multicore future is a future that uses multicore evaluation,which means that itsvalue is computed and resolved inparallel in another process.

This function is mustnot be called directly. Instead, thetypical usages are:

# Evaluate futures in parallel on the local machine via as many forked# processes as available to the current R processplan(multicore)# Evaluate futures in parallel on the local machine via two forked processesplan(multicore, workers = 2)

Support for forked ("multicore") processing

Not all operating systems support process forking and thereby not multicorefutures. For instance, forking is not supported on Microsoft Windows.Moreover, process forking may break some R environments such as RStudio.Because of this, the future package disables process forking also insuch cases. Seeparallelly::supportsMulticore() for details.Trying to create multicore futures on non-supported systems or whenforking is disabled will result in multicore futures falling back tobecomingsequential futures. If used in RStudio, there will be aninformative warning:

> plan(multicore)Warning message:In supportsMulticoreAndRStudio(...) :  [ONE-TIME WARNING] Forked processing ('multicore') is not supported whenrunning R from RStudio because it is considered unstable. For more details,how to control forked processing or not, and how to silence this warning infuture R sessions, see ?parallelly::supportsMulticore

See Also

For processing in multiple backgroundR sessions, seemultisession futures.

For alternative future backends, see the 'A Future for R: Available FutureBackends' vignette andhttps://www.futureverse.org/backends.html.

Useparallelly::availableCores() to see the total number ofcores that are available for the currentR session.UseavailableCores("multicore") > 1L to checkwhether multicore futures are supported or not on the currentsystem.

Examples

## Use multicore futuresplan(multicore)## A global variablea <- 0## Create future (explicitly)f <- future({  b <- 3  c <- 2  a * b * c})## A multicore future is evaluated in a separate forked## process.  Changing the value of a global variable## will not affect the result of the future.a <- 7print(a)v <- value(f)print(v)stopifnot(v == 0)

Create a multisession future whose value will be resolved asynchronously in a parallelR session

Description

WARNING: This function must never be called.It may only be used withplan()

Usage

multisession(  ...,  workers = availableCores(constraints = "connections-16"),  rscript_libs = .libPaths())

Arguments

Details

A multisession future is a future that uses multisession evaluation,which means that itsvalue is computed and resolved inparallel in anotherR session.

This function is mustnot be called directly. Instead, thetypical usages are:

# Evaluate futures in parallel on the local machine via as many background# processes as available to the current R processplan(multisession)# Evaluate futures in parallel on the local machine via two background# processesplan(multisession, workers = 2)

The backgroundR sessions (the "workers") are created usingmakeClusterPSOCK().

For the total number ofR sessions available including the current/mainR process, seeparallelly::availableCores().

A multisession future is a special type of cluster future.

Value

A MultisessionFuture.Ifworkers == 1, then all processing is done in thecurrent/mainR session and we therefore fall back to using alazy future. To override this fallback, useworkers = I(1).

See Also

For processing in multiple forkedR sessions, seemulticore futures.

Useparallelly::availableCores() to see the total number ofcores that are available for the currentR session.

Examples

## Use multisession futuresplan(multisession)## A global variablea <- 0## Create future (explicitly)f <- future({  b <- 3  c <- 2  a * b * c})## A multisession future is evaluated in a separate R session.## Changing the value of a global variable will not affect## the result of the future.a <- 7print(a)v <- value(f)print(v)stopifnot(v == 0)## Explicitly close multisession workers by switching planplan(sequential)

Get the number of workers available

Description

Get the number of workers available

Usage

nbrOfWorkers(evaluator = NULL)nbrOfFreeWorkers(evaluator = NULL, background = FALSE, ...)

Arguments

Value

nbrOfWorkers() returns a positive number in{1, 2, 3, ...}, whichfor some future backends may also be+Inf.

nbrOfFreeWorkers() returns a non-negative number in{0, 1, 2, 3, ...} which is less than or equal tonbrOfWorkers().

Examples

plan(multisession)nbrOfWorkers()  ## == availableCores()plan(sequential)nbrOfWorkers()  ## == 1

Creates a connection to the system null device

Description

Creates a connection to the system null device

Usage

nullcon()

Value

Returns a open, binarybase::connection().

Plan how to resolve a future

Description

This function allowsthe user to plan the future, more specifically,it specifies howfuture():s are resolved,e.g. sequentially or in parallel.

Usage

plan(  strategy = NULL,  ...,  substitute = TRUE,  .skip = FALSE,  .call = TRUE,  .cleanup = NA,  .init = TRUE)## S3 method for class 'FutureStrategyList'with(data, expr, ..., local = FALSE, envir = parent.frame(), .cleanup = NA)tweak(strategy, ..., penvir = parent.frame())

Arguments

Details

The default backend issequential, but another one can be setusingplan(), e.g.plan(multisession) will launch parallel workersrunning in the background, which then will be used to resolve future.To shut down background workers launched this way, callplan(sequential).

Value

plan() returns a the previous plan invisibly if a new future backendis chosen, otherwise it returns the current one visibly.

The value of the expression evaluated (invisibly).

a future function.

Built-in evaluation strategies

Thefuture package provides the following built-in backends:

sequential:

Resolves futures sequentially in the currentR process, e.g.plan(sequential).

multisession:

Resolves futures asynchronously (in parallel) in separateR sessions running in the background on the same machine, e.g.plan(multisession) andplan(multisession, workers = 2).

multicore:

Resolves futures asynchronously (in parallel) in separateforkedR processes running in the background onthe same machine, e.g.plan(multicore) andplan(multicore, workers = 2).This backend is not supported on Windows.

cluster:

Resolves futures asynchronously (in parallel) in separateR sessions running typically on one or more machines, e.g.plan(cluster),plan(cluster, workers = 2), andplan(cluster, workers = c("n1", "n1", "n2", "server.remote.org")).

Other evaluation strategies available

In addition to the built-in ones, additional parallel backends areimplemented in future-backend packagesfuture.callr andfuture.mirai that leverage R packagecallr andmirai:

callr:

Similar tomultisession, this resolved futures in parallel inbackgroundR sessions on the local machine via thecallrpackage, e.g.plan(future.callr::callr) andplan(future.callr::callr, workers = 2). The difference is thateach future is processed in a fresh parallel R worker, which isautomatically shut down as soon as the future is resolved.This can help decrease the overall memory. Moreover, contrarytomultisession,callr does not rely on socket connections,which means it is not limited by the number of connections thatR can have open at any time.

mirai_multisession:

Similar tomultisession, this resolved futures in parallel inbackgroundR sessions on the local machine via themiraipackage, e.g.plan(future.mirai::mirai_multisession) andplan(future.mirai::mirai_multisession, workers = 2).

mirai_cluster:

Similar tocluster, this resolved futures in parallel viapre-configuredRmirai daemon processes, e.g.plan(future.mirai::mirai_cluster).

Another example is thefuture.batchtools package, which leveragesbatchtools package, to resolve futures via high-performance compute(HPC) job schedulers, e.g. LSF, Slurm, TORQUE/PBS, Grid Engine, andOpenLava;

batchtools_slurm:

The backend resolved futures via the Slurm scheduler, e.g.plan(future.batchtools::batchtools_slurm).

batchtools_torque:

The backend resolved futures via the TORQUE/PBS scheduler, e.g.plan(future.batchtools::batchtools_torque).

batchtools_sge:

The backend resolved futures via the Grid Engine (SGE, AGE) scheduler,e.g.plan(future.batchtools::batchtools_sge).

batchtools_lsf:

The backend resolved futures via the Load Sharing Facility (LSF)scheduler, e.g.plan(future.batchtools::batchtools_lsf).

batchtools_openlava:

The backend resolved futures via the OpenLava scheduler, e.g.plan(future.batchtools::batchtools_openlava).

For package developers

Please refrain from modifying the future backend inside your packages /functions, i.e. do not callplan() in your code. Instead, leavethe control on what backend to use to the end user. This idea is part ofthe core philosophy of the future framework—as a developer you can neverknow what future backends the user have access to. Moreover, by not makingany assumptions about what backends are available, your code will also workautomatically with any new backends developed after you wrote your code.

If you think it is necessary to modify the future backend within afunction, then make sure to undo the changes when exiting the function.This can be achieved by usingwith(plan(...), local = TRUE), e.g.

  my_fcn <- function(x) {    with(plan(multisession), local = TRUE)    y <- analyze(x)    summarize(y)  }

This is important because the end-user might have already set the futurestrategy elsewhere for other purposes and will most likely not known thatcalling your function will break their setup.Remember, your package and its functions might be used in a greatercontext where multiple packages and functions are involved and those mightalso rely on the future framework, so it is important to avoid stepping onothers' toes.

Using plan() in scripts and vignettes

When writing scripts or vignettes that use futures, try to place anycall toplan() as far up (i.e. as early on) in the code as possible.This will help users to quickly identify where the future plan is set upand allow them to modify it to their computational resources.Even better is to leave it to the user to set theplan() prior tosource():ing the script or running the vignette.If a ‘.future.R’ exists in the current directory and / or inthe user's home directory, it is sourced when thefuture package isloaded. Because of this, the ‘.future.R’ file provides aconvenient place for users to set theplan().This behavior can be controlled via anR option—seefuture options for more details.

See Also

Useplan() to set a future to become thenew default strategy.

Examples

a <- b <- c <- NA_real_# An sequential futureplan(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 evaluationplan(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 macOS) for unknown reasons.## The same code works in package tests.# A multisession future (specified via a string variable)plan("future::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## Explicitly specifying number of workers## (default is parallelly::availableCores())plan(multicore, workers = 2)message("Number of parallel workers: ", nbrOfWorkers())## Explicitly close multisession workers by switching planplan(sequential)# Evaluate a future using the 'multisession' planwith(plan(multisession, workers = 2), {  f <- future(Sys.getpid())  w_pid <- value(f)})print(c(main = Sys.getpid(), worker = w_pid))# Evaluate a future locally using the 'multisession' planlocal({  with(plan(multisession, workers = 2), local = TRUE)  f <- future(Sys.getpid())  w_pid <- value(f)  print(c(main = Sys.getpid(), worker = w_pid))})

Functions Moved to 'parallelly'

Description

The following function used to be part offuture but has sincebeen migrated toparallelly. The migration started withfuture 1.20.0 (November 2020). They were moved because theyare also useful outside of thefuture framework.

Details

If you are using any of these from thefuture package, pleaseswitch to use the ones from theparallelly package. Thank you!

• parallelly::as.cluster()

• parallelly::autoStopCluster() (no longer re-exported)

• parallelly::availableCores()

• parallelly::availableWorkers()

• parallelly::makeClusterMPI() (no longer re-exported)

• parallelly::makeClusterPSOCK()

• parallelly::makeNodePSOCK() (no longer re-exported)

• parallelly::supportsMulticore()

For backward-compatible reasons,some of these functions remainavailable as exact copies also from this package (as re-exports), e.g.

cl <- parallelly::makeClusterPSOCK(2)

can still be accessed as:

cl <- future::makeClusterPSOCK(2)

Note that it is the goal to remove all of the above from this package.

Writes and Reads 'immediateCondition' RDS Files

Description

Writes and Reads 'immediateCondition' RDS Files

Usage

readImmediateConditions(  path = immediateConditionsPath(rootPath = rootPath),  rootPath = tempdir(),  pattern = "[.]rds$",  include = getOption("future.relay.immediate", "immediateCondition"),  signal = FALSE,  remove = TRUE)saveImmediateCondition(  cond,  path = immediateConditionsPath(rootPath = rootPath),  rootPath = tempdir())

Arguments

Value

readImmediateConditions() returns an unnamedbase::list ofnamed lists with elementscondition andsignaled, wherethecondition elements holdimmediateCondition objects.

saveImmediateCondition() returns, invisibly, the pathname ofthe RDS written.

Request a core for multicore processing

Description

If no cores are available, the current processblocks until a core is available.

Usage

requestCore(  await,  workers = availableCores(constraints = "multicore"),  timeout,  delta,  alpha)

Arguments

Value

Invisible TRUE. If no cores are available afterextensive waiting, then a timeout error is thrown.

Reset a finished, failed, canceled, or interrupted future to a lazy future

Description

A future that has successfully completed,canceled, interrupted,or has failed due to an error, can be relaunched after resetting it.

Usage

reset(x, ...)

Arguments

Details

A lazy, vanillaFuture can be reused in another R session. Forinstance, if we do:

library(future)a <- 2f <- future(42 * a, lazy = TRUE)saveRDS(f, "myfuture.rds")

Then we can read and evaluate the future in another R session using:

library(future)f <- readRDS("myfuture.rds")v <- value(f)print(v)#> [1] 84

Value

reset() returns a lazy, vanillaFuture that can be relaunched.Resetting a running future results in aFutureError.

Examples

## Like mean(), but fails 90% of the timeshaky_mean <- function(x) {  if (as.double(Sys.time()) %% 1 < 0.90) stop("boom")  mean(x)}x <- rnorm(100)## Calculate the mean of 'x' with a risk of failing randomlyf <- future({ shaky_mean(x) })## Relaunch until successrepeat({  v <- tryCatch(value(f), error = identity)  if (!inherits(v, "error")) break  message("Resetting failed future, and retry in 0.1 seconds")  f <- reset(f)  Sys.sleep(0.1)})cat("mean:", v, "\n")

Free up active background workers

Description

Free up active background workers

Usage

resetWorkers(x, ...)

Arguments

Details

This function will resolve any active futures that is currentlybeing evaluated on background workers.

Examples

resetWorkers(plan())

Resolve one or more futures synchronously

Description

This function provides an efficient mechanism for waiting for multiplefutures in a container (e.g. list or environment) to be resolved while inthe meanwhile retrieving values of already resolved futures.

Usage

resolve(  x,  idxs = NULL,  recursive = 0,  result = FALSE,  stdout = FALSE,  signal = FALSE,  force = FALSE,  sleep = getOption("future.wait.interval", 0.01),  ...)

Arguments

Details

This function is resolves synchronously, i.e. it blocks untilx andany containing futures are resolved.

Value

Returnsx (regardless of subsetting or not).Ifsignal is TRUE and one of the futures produces an error, thenthat error is produced.

See Also

To resolve a futurevariable, first retrieve itsFuture object usingfutureOf(), e.g.resolve(futureOf(x)).

Check whether a future is resolved or not

Description

Check whether a future is resolved or not

Usage

## S3 method for class 'ClusterFuture'resolved(x, run = TRUE, timeout = NULL, ...)## S3 method for class 'MulticoreFuture'resolved(x, run = TRUE, timeout = NULL, ...)## S3 method for class 'Future'resolved(x, run = TRUE, ...)resolved(x, ...)## Default S3 method:resolved(x, ...)## S3 method for class 'list'resolved(x, ...)## S3 method for class 'environment'resolved(x, ...)

Arguments

Details

resolved(..., run = TRUE) attempts to launch a lazy future, if there isan available worker, otherwise not.

resolved() methods must always returnTRUE orFALSE values, mustalways launch lazy futures by default (run = TRUE), and must never blockindefinitely. This is because it should always be possible to poll futuresuntil they are resolved usingresolved(), e.g.while (!all(resolved(futures))) Sys.sleep(5).

Each future backend must implement aresolved() method. It should returneither TRUE or FALSE, or throw aFutureError (which indicate asignificant, often unrecoverable infrastructure problem, or an interrupt).

Value

A logical vector of the same length and dimensions asx.Each element is TRUE unless the corresponding element is anon-resolved future in case it is FALSE.It never signals an error.

The default method always returns TRUE.

Behavior of cluster and multisession futures

If all worker slots are occupied,resolved() forClusterFuture andMultisessionFuture will attempt to free one up by checking whetherone of the futures isresolved. If there is one, then its result iscollected in order to free up one worker slot.

resolved() forClusterFuture may receive immediate condition objects, ratherthan aFutureResult, when polling the worker for results. In such cases, thecondition object is collected and another poll it performed. Up to 100 immediateconditions may be collected this way perresolved() call, before consideringthe future non-resolved and FALSE being returned.

Behavior of multicore futures

resolved() forMulticoreFuture may receive immediate condition objects, rather than aFutureResult, when polling the worker for results. In such cases,all such conditionobjects are collected, before considering the future non-resolved and FALSE being returned.

Get the results of a resolved future

Description

Get the results of a resolved future

Usage

## S3 method for class 'Future'result(future, ...)

Arguments

Details

This function is only part of thebackend Future API.This function isnot part of the frontend Future API.

Value

TheFutureResult object.It may signal aFutureError, if there is a significant orchestrationerror. For example, if the parallel worker process terminated abruptly("crashed"), then aFutureInterruptError is signaled.

Run a future

Description

Run a future

Usage

## S3 method for class 'Future'run(future, ...)

Arguments

Details

This function can only be called once per future.Further calls will result in an informative error.If a future is not run when its value is queried,then it is run at that point.

Value

TheFuture object.

Robustly Saves an Object to RDS File Atomically

Description

Robustly Saves an Object to RDS File Atomically

Usage

save_rds(object, pathname, ...)

Arguments

Details

Usesbase::saveRDS internally but writes the object atomically by firstwriting to a temporary file which is then renamed.

Value

The pathname of the RDS written.

Create a sequential future whose value will be in the currentR session

Description

WARNING: This function must never be called.It may only be used withplan()

Usage

sequential(..., envir = parent.frame())

Arguments

Details

A sequential future is a future that is evaluated sequentially in thecurrentR session similarly to howR expressions are evaluated inR.The only difference toR itself is that globals are validatedby default just as for all other types of futures in this package.

This function is mustnot be called directly. Instead, thetypical usages are:

# Evaluate futures sequentially in the current R processplan(sequential)

Examples

## Use sequential futuresplan(sequential)## A global variablea <- 0## Create a sequential futuref <- future({  b <- 3  c <- 2  a * b * c})## Since 'a' is a global variable in future 'f' which## is eagerly resolved (default), this global has already## been resolved / incorporated, and any changes to 'a'## at this point will _not_ affect the value of 'f'.a <- 7print(a)v <- value(f)print(v)stopifnot(v == 0)

Outputs details on the currentR session

Description

Outputs details on the currentR session

Usage

sessionDetails(env = FALSE)

Arguments

Value

Invisibly a list of all details.

Signals Captured Conditions

Description

Captured conditions that meet theinclude andexcluderequirements are signaledin the order as they were captured.

Usage

signalConditions(  future,  include = "condition",  exclude = NULL,  resignal = TRUE,  ...)

Arguments

Value

Returns theFuture where conditioned that were signaledhave been flagged to have been signaled.

See Also

Conditions are signaled bysignalCondition().

Place a sticky-globals environment immediately after the global environment

Description

Place a sticky-globals environment immediately after the global environment

Usage

sticky_globals(erase = FALSE, name = "future:sticky_globals", pos = 2L)

Arguments

Value

(invisible; environment) The environment.

Get number of cores currently used

Description

Get number of children (and don't count the current process)used by the currentR session. The number of childrenis the total number of subprocesses launched by thisprocess that are still running and whose values have yetnot been collected.

Usage

usedCores()

Value

A non-negative integer.

The value of a future or the values of all elements in a container

Description

Gets the value of a future or the values of all elements (including futures)in a container such as a list, an environment, or a list environment.If one or more futures is unresolved, then this function blocks until allqueried futures are resolved.

Usage

value(...)## S3 method for class 'Future'value(future, stdout = TRUE, signal = TRUE, drop = FALSE, ...)## S3 method for class 'list'value(  x,  idxs = NULL,  recursive = 0,  reduce = NULL,  stdout = TRUE,  signal = TRUE,  cancel = TRUE,  interrupt = cancel,  inorder = TRUE,  drop = FALSE,  force = TRUE,  sleep = getOption("future.wait.interval", 0.01),  ...)## S3 method for class 'listenv'value(  x,  idxs = NULL,  recursive = 0,  reduce = NULL,  stdout = TRUE,  signal = TRUE,  cancel = TRUE,  interrupt = cancel,  inorder = TRUE,  drop = FALSE,  force = TRUE,  sleep = getOption("future.wait.interval", 0.01),  ...)## S3 method for class 'environment'value(x, ...)

Arguments

Value

value() of a Future object returns the value of the future, which canbe any type ofR object.

value() of a list, an environment, or a list environment returns anobject with the same number of elements and of the same class.Names and dimension attributes are preserved, if available.All future elements are replaced by their correspondingvalue() values.For all other elements, the existing object is kept as-is.

Ifsignal is TRUE and one of the futures produces an error, thenthat error is relayed. Any remaining, non-resolved futures inx arecanceled, prior to signaling such an error.If the future was interrupted, canceled, or the parallel worker terminatedabruptly ("crashed"), then aFutureInterruptError is signaled.

Examples

## ------------------------------------------------------## A single future## ------------------------------------------------------x <- sample(100, size = 50)f <- future(mean(x))v <- value(f)message("The average of 50 random numbers in [1,100] is: ", v)## ------------------------------------------------------## Ten futures## ------------------------------------------------------xs <- replicate(10, { list(sample(100, size = 50)) })fs <- lapply(xs, function(x) { future(mean(x)) })## The 10 values as a list (because 'fs' is a list)vs <- value(fs)message("The ten averages are:")str(vs)## The 10 values as a vector (by manually unlisting)vs <- value(fs)vs <- unlist(vs)message("The ten averages are: ", paste(vs, collapse = ", "))## The values as a vector (by reducing)vs <- value(fs, reduce = c)message("The ten averages are: ", paste(vs, collapse = ", "))## Calculate the sum of the averages (by reducing)total <- value(fs, reduce = `+`)message("The sum of the ten averages is: ", total)

Options used for futures

Description

Below are theR options and environment variables that are used by thefuture package and packages enhancing it.

WARNING: Note that the names and the default values of these options maychange in future versions of the package. Please use with care untilfurther notice.

Packages must not change future options

Just like for other R options, as a package developer you mustnot changeany of the below⁠future.*⁠ options. Only the end-user should set these.If you find yourself having to tweak one of the options, make sure toundo your changes immediately afterward. For example, if you want tobump up thefuture.globals.maxSize limit when creating a future,use something like the following inside your function:

oopts <- options(future.globals.maxSize = 1.0 * 1e9)  ## 1.0 GBon.exit(options(oopts))f <- future({ expr })  ## Launch a future with large objects

Options for controlling futures

future.plan:

(character string or future function) Default future backend used unless otherwise specified viaplan(). This will also be the future plan set when callingplan("default"). If not specified, this option may be set when thefuture package isloaded if command-line option--parallel=ncores (short⁠-p ncores⁠) is specified; ifncores > 1, then optionfuture.plan is set tomultisession otherwisesequential (in addition to optionmc.cores being set toncores, ifncores >= 1). (Default:sequential)

future.globals.maxSize:

(numeric) Maximum allowed total size (in bytes) of global variables identified. This is used to protect against exporting too large objects to parallel workers by mistake. Transferring large objects over a network, or over the internet, can be slow and therefore introduce a large bottleneck that increases the overall processing time. It can also result in large egress or ingress costs, which may exist on some systems. If set of+Inf, then the check for large globals is skipped. (Default:500 * 1024 ^ 2 = 500 MiB)

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

(character string) Controls whether the identified globals should be scanned for so calledreferences (e.g. external pointers and connections) or not. It is unlikely that anotherR process ("worker") can use a global that uses a internal reference of the masterR process—we call such objectsnon-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 masterR process (e.g.plan(sequential) andplan(multicore)).If"ignore", no scan is performed.(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. If0, only the future itself is resolved. If1, 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.onFutureCondition.keepFuture:

(logical) IfTRUE, aFutureCondition keeps a copy of theFuture object that triggered the condition. IfFALSE, it is dropped. (Default:TRUE)

future.wait.timeout:

(numeric) Maximum waiting time (in seconds) for a future to resolve or for a free worker to become available before a timeout error is generated. (Default:30 * 24 * 60 * 60 (= 30 days))

future.wait.interval:

(numeric) Initial interval (inseconds) between polls. This controls the polling frequency for findingan available worker when all workers are currently busy. It also controlsthe polling frequency ofresolve(). (Default:0.01 = 1 ms)

future.wait.alpha:

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

Options for built-in sanity checks

Ideally, the evaluation of a future should have no side effects. Toprotect against unexpected side effects, the future framework comeswith a set of built-in tools for checking against this.Below R options control these built-in checks and what should happenif they fail. You may modify them for troubleshooting purposes, butplease refrain from disabling these checks when there is an underlyingproblem that should be fixed.

Beta features: Please consider these checks to be "under construction".

future.connections.onMisuse:

(character string)A future must close any connections it opens and must not closeconnections it did not open itself.If such misuse is detected and this option is set to"error",then an informative error is produced. If it is set to"warning",a warning is produced. If"ignore", no check is performed.(Default:"warning")

future.defaultDevice.onMisuse:

(character string)A future must open graphics devices explicitly, if it creates newplots. It should not rely on the default graphics device thatis given by R option"default", because that rarely does whatis intended.If such misuse is detected and this option is set to"error",then an informative error is produced. If it is set to"warning",a warning is produced. If"ignore", no check is performed.(Default:"warning")

future.devices.onMisuse:

(character string)A future must close any graphics devices it opens and must not closedevices it did not open itself.If such misuse is detected and this option is set to"error",then an informative error is produced. If it is set to"warning",a warning is produced. If"ignore", no check is performed.(Default:"warning")

future.globalenv.onMisuse:

(character string)Assigning variables to the global environment for the purpose of usingthe variable at a later time makes no sense with futures, because thenext the future may be evaluated in different R process.To protect against mistakes, the future framework attempts to detectwhen variables are added to the global environment.If this is detected, and this option is set to"error", then aninformative error is produced. If"warning", then a warning isproduced. If"ignore", no check is performed.(Default:"ignore")

future.rng.onMisuse:

(character string)If random numbers are used in futures, then parallel RNG should bedeclared in order to get statistical sound RNGs. You can declarethis by specifying future argumentseed = TRUE. The defaults in thefuture framework assume thatno random number generation (RNG) istaken place in the future expression because L'Ecuyer-CMRG RNGs comewith an unnecessary overhead if not needed.To protect against mistakes of not declaring use of the RNG, thefuture framework detects when random numbers were used despite notdeclaring such use.If this is detected, and this options is set"error", then aninformative error is produced. If"warning", then a warning isproduced. If"ignore", no check is performed.(Default:"warning")

Options for debugging futures

future.debug:

(logical) IfTRUE, 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 thefuture package isattached. 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 variableR_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 toTRUE, 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 toFALSE.Importantly, this option isalways set toFALSE if thefuture package is loaded as part of a future expression being evaluated, e.g. in a background process. In other words, they are sourced in the mainR process but not in future processes. (Default:TRUE in mainR process andFALSE in future processes / during future evaluation)

future.cmdargs:

(character vector) OverridescommandArgs() when thefuture package isloaded.

Options for configuring low-level system behaviors

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

(logical) Enable or disablemulti-threading while usingforked parallel processing. IfFALSE, different multi-thread library settings are overridden such that they run in single-thread mode. Specifically, multi-threading will be disabled for OpenMP (which requires theRhpcBLASctl package) and forRcppParallel. IfTRUE, 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 usingplan(multicore) but also when using, for instance,mclapply() of theparallel package. (Default: not set)

future.output.windows.reencode:

(logical) Enable or disable re-encoding of UTF-8 symbols that were incorrectly encoded while captured. In R (< 4.2.0) and on older versions of MS Windows, R cannot capture UTF-8 symbols as-is when they are captured from the standard output. For examples, a UTF-8 check mark symbol ("\u2713") would be relayed as"<U+2713>" (a string with eight ASCII characters). Setting this option toTRUE will causevalue() to attempt to recover the intended UTF-8 symbols from⁠<U+nnnn>⁠ string components, if, and only if, the string was captured by a future resolved on MS Windows. (Default:TRUE)

Options for demos

future.demo.mandelbrot.region:

(integer) Either a named list ofmandelbrot() 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)

Deprecated or for internal prototyping

The following options exists only for troubleshooting purposes and must notbe used in production. If used, there is a risk that the results arenon-reproducible if processed elsewhere. To lower the risk of them beingused by mistake, they are marked as deprecated and will produce warningsif set.

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, seeglobalsOf(). (Default:"ordered")

future.globals.resolve:

(logical) IfTRUE, globals that areFuture objects (typically created asexplicit futures) will be resolved and have their values (usingvalue()) 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)

Environment variables that set R options

All of the aboveRfuture.* options can be set by correspondingenvironment variableR_FUTURE_*when thefuture package isloaded. This means that those environment variables must be set beforethefuture package is loaded in order to have an effect.For example, ifR_FUTURE_RNG_ONMISUSE="ignore", then optionfuture.rng.onMisuse is set to"ignore" (character string).Similarly, ifR_FUTURE_GLOBALS_MAXSIZE="50000000", then optionfuture.globals.maxSize is set to50000000 (numeric).

Options moved to the 'parallelly' package

Several functions have been moved to theparallelly package:

• parallelly::availableCores()

• parallelly::availableWorkers()

• parallelly::makeClusterMPI()

• parallelly::makeClusterPSOCK()

• parallelly::makeNodePSOCK()

• parallelly::supportsMulticore()

The options and environment variables controlling those have been adjustedaccordingly to have different prefixes.For example, optionfuture.fork.enable has been renamed toparallelly.fork.enable and the corresponding environment variableR_FUTURE_FORK_ENABLE has been renamed toR_PARALLELLY_FORK_ENABLE.For backward compatibility reasons, theparallelly package willsupport both versions for a long foreseeable time.See theparallelly::parallelly.options page for the settings.

See Also

To setR options or environment variables whenR starts (even before thefuture package is loaded), see theStartup help page. Thestartup package provides a friendly mechanism for configuratingR's startup process.

Examples

# Allow at most 5 MB globals per futuresoptions(future.globals.maxSize = 5e6)# Be strict; catch all RNG mistakesoptions(future.rng.onMisuse = "error")