plan() such that it is evaluated in parallel on,
for instance, the current machine, on a remote machine, or via a
job queue on a compute cluster.
Importantly, R code using futures remains the same regardless
on these settings.
future(expr, envir = parent.frame(), substitute = TRUE, evaluator = plan(), ...)
futureAssign(x, value, envir = parent.frame(), assign.env = envir, substitute = TRUE)
x %<-% value
futureCall(FUN, args = NULL, envir = parent.frame(), globals = TRUE, evaluator = plan(), ...)expr is
substitute():ed, otherwise not.FUN.future() and futureCall().f <- future(expr) creates a Future f that evaluates expression expr, the value of the future is retrieved using v <- value(f).f <- futureCall(FUN, args) creates a Future f that calls function FUN with arguments args, where the value of the future is retrieved using v <- value(f).futureAssign("v", expr) and v %<-% expr (a future assignment) create a Future that evaluates expression expr and binds its value (as a promise) to a variable v. The value of the future is automatically retrieved when the assigned variable (promise) is queried.
The future itself is returned invisibly, e.g.
f <- futureAssign("v", expr) and f <- (v %<-% expr).
Alternatively, the future of a future variable v can be retrieved
without blocking using f <- futureOf(v).
Both the future and the variable (promise) are assigned to environment
assign.env where the name of the future is .future_.
a <- 42
f <- future({ b <- 2; a * b })
variable a is a global of future assignment f whereas
b 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 that
they are available whenever and wherever the future is resolved. The default behavior (globals = TRUE) of all evaluator functions,
is that globals are automatically identified and gathered.
More precisely, globals are identified via code inspection of the
future expression expr and their values are retrieved with
environment envir as the starting point (basically via
get(global, envir=envir, inherits=TRUE)).
In most cases, such automatic collection of globals is sufficient
and less tedious and error prone than if they are manually specified. However, for full control, it is also possible to explicitly specify
exactly which the globals are by providing their names as a character
vector.
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 values
using 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 from
automatically identifying the globals and gathering their values.
Futhermore, if we know that the future expression does not make use
of any global variables, we can disable the automatic search for
globals 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 future
package will make sure that those packages are attached when the future
is resolved. Because there is no need for such globals to be frozen
or exported, the future package will not export them, which reduces
the amount of transferred objects.
For example, in
x <- rnorm(1000)
f <- future({ median(x) })
variable x and median() are globals, but only x
is exported whereas median(), which is part of the stats
package, is not exported. Instead it is made sure that the stats
package 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. When using future assignments, globals can be specified analogously
using the %globals% operator, e.g.
x <- rnorm(1000)
y %<-% { median(x) } %globals% list(x = x, median = stats::median)
v <- value(f).
Querying the value of a non-resolved future will block the call
until the future is resolved.
It is possible to check whether a future is resolved or not
without blocking by using resolved(f).For a future created via a future assignment, the value is bound to
a promise, which when queried will internally call value()
on the future and which will then be resolved into a regular variable
bound to that value. For example, with future assignment
v %<-% expr, the first time variable v is queried
the call blocks if (and only if) the future is not yet resolved. As soon
as it is resolved, and any succeeding queries, querying v will
immediately give the value.
The future assignment construct v %<-% expr is not a formal
assignment per se, but a binary infix operator on objects v
and expr. However, by using non-standard evaluation, this
constructs can emulate an assignment operator similar to
v <- expr. Due to R's precedence rules of operators,
future expressions that contain multiple statements need to be
explicitly bracketed, e.g. v %<-% { a <- 2; a^2 }.
plan() function.
## Cluster 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.
## Evaluate futures in parallel
plan(multiprocess)
## Data
x <- rnorm(100)
y <- 2*x + 0.2 + rnorm(100)
w <- 1 + x^2
## (1) Regular assignments (evaluated sequentially)
fitA <- lm(y ~ x, weights = w) ## with offset
fitB <- lm(y ~ x - 1, weights = w) ## without offset
fitC <- {
w <- 1 + abs(x) ## Different weights
lm(y ~ x, weights = w)
}
print(fitA)
print(fitB)
print(fitC)
## (2) Future assignments (evaluated in parallel)
fitA %<-% lm(y ~ x, weights = w) ## with offset
fitB %<-% lm(y ~ x - 1, weights = w) ## without offset
fitC %<-% {
w <- 1 + abs(x)
lm(y ~ x, weights = w)
}
print(fitA)
print(fitB)
print(fitC)
## (3) Explicitly create futures (evaluated in parallel)
## and retrieve their values
fA <- 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)
## (4) Explit future assignments (evaluated in parallel)
futureAssign("fitA", lm(y ~ x, weights = w))
futureAssign("fitB", lm(y ~ x - 1, weights = w))
futureAssign("fitC", {
w <- 1 + abs(x)
lm(y ~ x, weights = w)
})
print(fitA)
print(fitB)
print(fitC)
Run the code above in your browser using DataLab