In the ideal case, all it takes to start using futures in R is to replace select standard assignments (<-) in your R code with future assignments (%<-%) and make sure the right-hand side (RHS) expressions are within curly brackets ({ ... }). Also, if you assign these to lists (e.g. in a for loop), you need to use a list environment (listenv) instead of a plain list.
However, as show below, there are few cases where you might run into some hurdles, but, as also shown, they are often easy to overcome. These are often related to global variables.
If you identify other cases, please consider reporting them so they can be documented here and possibly even be fixed.
If a global variable is (only) part of a “self” assignment, such as x <- x + 1, then the global is not identified and therefore neither exported / frozen. This explains the error in the following example:
> library("future")
> plan(sequential)
> x <- 0
> y %<-% { x <- x + 1 } %lazy% TRUE
> rm(x)
> y
Error: object 'x' not found
The workaround is to guide R to find the missing global by explicitly listing it, e.g.
> library("future")
> plan(sequential)
> x <- 0
> y %<-% { x; x <- x + 1 } %lazy% TRUE
> rm(x)
> y
[1] 1
Comment: The goal is to in a future version of the package detect globals also in such self-assignment constructs.
When calling a function using do.call() make sure to specify the function as the object itself and not by name. This will help identify the function as a global object in the future expression. For instance, use
do.call(file_ext, list("foo.txt"))
instead of
do.call("file_ext", list("foo.txt"))
so that file_ext() is properly located and exported. Although you may not notice a difference when evaluating futures in the same R session, it may become a problem if you use a character string instead of a function object when futures are evaluated in external R sessions, such as on a cluster.
It may also become a problem with futures evaluated with lazy evaluation if the intended function is redefined after the future is resolved. For example,
> library("future")
> library("listenv")
> library("tools")
> plan(sequential)
> pathnames <- c("foo.txt", "bar.png", "yoo.md")
> res <- listenv()
> for (ii in seq_along(pathnames)) {
+ res[[ii]] %<-% do.call("file_ext", list(pathnames[ii])) %lazy% TRUE
+ }
> file_ext <- function(...) "haha!"
> unlist(res)
[1] "haha!" "haha!" "haha!"
It is not possible for a future to resolve another one unless it was created by the future trying to resolve it. For instance, the following gives an error:
> library("future")
> plan(multiprocess)
> f1 <- future({ Sys.getpid() })
> f2 <- future({ value(f1) })
> v1 <- value(f1)
[1] 7464
> v2 <- value(f2)
Error: Invalid usage of futures: A future whose value has not yet been collected
can only be queried by the R process (cdd013cb-e045-f4a5-3977-9f064c31f188; pid
1276 on MyMachine) that created it, not by any other R processes (5579f789-e7b6
-bace-c50d-6c7a23ddb5a3; pid 2352 on MyMachine): {; Sys.getpid(); }
This is because the main R process creates two futures, but then the second future tries to retrieve the value of the first one. This is an invalid request because the second future has no channel to communicate with the first future; it is only the process that created a future who can communicate with it(*).
Note that it is only unresolved futures that cannot be queried this way. Thus, the solution to the above problem is to make sure all futures are resolved before they are passed to other futures, e.g.
> f1 <- future({ Sys.getpid() })
> v1 <- value(f1)
> v1
[1] 7464
> f2 <- future({ value(f1) })
> v2 <- value(f2)
> v2
[1] 7464
This works because the value has already been collected and stored inside future f1 before future f2 is created. Since the value is already stored internally, value(f1) is readily available everywhere. Of course, instead of using value(f1) for the second future, it would be more readable and cleaner to simply use v1.
The above is typically not a problem when future assignments are used. For example:
> v1 %<-% { Sys.getpid() })
> v2 %<-% { v1 }
> v1
[1] 2352
> v2
[1] 2352
The reason that this approach works out of the box is because in the second future assignment v1 is identified as a global variable, which is retrieved. Up to this point, v1 is a promise (“delayed assignment” in R), but when it is retrieved as a global variable its value is resolved and v1 becomes a regular variable.
However, there are cases where future assignments can be passed via global variables without being resolved. This can happen if the future assignment is done to an element of an environment (including list environments). For instance,
> library("listenv")
> x <- listenv()
> x$a %<-% { Sys.getpid() }
> x$b %<-% { x$a }
> x$a
[1] 2352
> x$b
Error: Invalid usage of futures: A future whose value has not yet been collected
can only be queried by the R process (cdd013cb-e045-f4a5-3977-9f064c31f188; pid
1276 on localhost) that created it, not by any other R processes (2ce86ccd-5854
-7a05-1373-e1b20022e4d8; pid 7464 on localhost): {; Sys.getpid(); }
As previously, this can be avoided by making sure x$a is resolved first, which can be one in various ways, e.g. dummy <- x$a, resolve(x$a) and force(x$a).
Footnote: (*) Although sequential futures could be passed on to other futures part of the same R process and be resolved there because they share the same evaluation process, by definition of the Future API it is invalid to do so regardless of future type. This conservative approach is taken in order to make future expressions behave consistently regardless of the type of future used.
Sometimes other packages have functions or operators with the same name as the future package, and if those packages are attached after the future package, their objects will mask the ones of the future package. For instance, the igraph package also defines a %<-% operator which clashes with the one in future if used at the prompt or in a script (it is not a problem inside package because there we explicitly import objects in a known order). Here is what we might get:
> library("future")
> library("igraph")
Attaching package: 'igraph'
The following objects are masked from 'package:future':
%<-%, %->%
The following objects are masked from 'package:stats':
decompose, spectrum
The following object is masked from 'package:base':
union
> y %<-% { 42 }
Error in get(".igraph.from", parent.frame()) :
object '.igraph.from' not found
Here we get an error because %<-% is from igraph and not the future assignment operator as we wanted. This can be confirmed as:
> environment(`%<-%`)
<environment: namespace:igraph>
To avoid this problem, attach the two packages in opposite order such that future comes last and thereby overrides igraph, i.e.
> library("igraph")
> library("future")
Attaching package: 'future'
The following objects are masked from 'package:igraph':
%<-%, %->%
> y %<-% { 42 }
> y
[1] 42
An alternative is to detach the future package and re-attach it, which will achieve the same thing:
> detach("package:future")
> library("future")
Yet another alternative is to explicitly override the object by importing it to the global environment, e.g.
> `%<-%` <- future::`%<-%`
> y %<-% { 42 }
> y
[1] 42
In this case, it does not matter in what order the packages are attached because we will always use the copy of future::`%<-%`.
The future assignment operator %<-% is a binary infix operator, which means it has higher precedence than most other binary operators but also higher than some of the unary operators in R. For instance, this explains why we get the following error:
> x %<-% 2 * runif(1)
Error in x %<-% 2 * runif(1) : non-numeric argument to binary operator
What effectively is happening here is that because of the higher priority of %<-%, we first create a future x %<-% 2 and then we try to multiply the future (not its value) with the value of runif(1) - which makes no sense. In order to properly assign the future variable, we need to put the future expression within curly brackets;
> x %<-% { 2 * runif(1) }
> x
[1] 1.030209
Parentheses will also do. For details on precedence on operators in R, see Section 'Infix and prefix operators' in the 'R Language Definition' document.
The code inspection run by R CMD check will not recognize the future assignment operator %<-% as an assignment operator, which is not surprising because %<-% is technically an infix operator. This means that if you for instance use the following code in your package:
foo <- function() {
b <- 3.14
a %<-% { b + 1 }
a
}
then R CMD check will produce a NOTE saying:
* checking R code for possible problems ... NOTE
foo: no visible binding for global variable 'a'
Undefined global functions or variables:
a
In order to avoid this, we can add a dummy assignment of the missing global at the top of the function, i.e.
foo <- function() {
a <- NULL ## To please R CMD check
b <- 3.14
a %<-% { b + 1 }
a
}
Copyright Henrik Bengtsson, 2015-2017