Global objects (short globals) are objects (e.g. variables and
functions) that are needed in order for the future expression to be
evaluated while not being local objects that are defined by the future
expression. For example, in
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.
Furthermore, 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.
Although rarely needed, a combination of automatic identification and manual
specification of globals is supported via attributes add (to add
false negatives) and ignore (to ignore false positives) on value
TRUE. For example, with
globals = structure(TRUE, ignore = "b", add = "a") any globals
automatically identified except b will be used in addition to
global a.
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)