Document best-practice use of '...' in anonymous functions [#761]

Author: HenrikBengtsson

DESCRIPTION

@@ -1,5 +1,5 @@
 Package: future
-Version: 1.34.0-9114
+Version: 1.34.0-9115
 Title: Unified Parallel and Distributed Processing in R for Everyone
 Imports:
     digest,

vignettes/future-4-issues.md.rsp

@@ -249,6 +249,103 @@ or equivalently
 Note, do _not_ use `library()` or `loadNamespace()` to resolve these problems. It is always better to use the above `packages` approach.
 
 
+## '...' used in an incorrect context
+
+In R, we can use the `...` construct is used to refer to zero or more
+arguments. For example, we can use as in:
+
+```r
+my_mean <- function(x, ...) mean(x, ...)
+
+y <- my_mean(1:10, trim = 0.1, na.rm = FALSE)
+```
+
+This makes sure that the `trim` and the `na.rm` arguments are pass
+down to the `mean()` function.
+
+We can also use it to pass arguments in map-reduce calls to anonymous
+functions as in:
+
+```r
+X <- rnorm(10)
+y <- lapply(X, FUN = function(x, ...) {
+  round(x, ...)
+}, digits = 3)
+```
+
+Note how `digits = 3` is pass to the anonymous function via its `...`
+argument, which is then passed on to `round()`, effectively calling
+`round(X[[1]], digits = 3)`, `round(X[[2]], digits = 3)`, and so on.
+
+If we take this one step further, we might see things like:
+
+```r
+my_fcn <- function(X, ...) {  ## outer '...'
+  y <- lapply(X, FUN = function(x, ...) { ## inner '...'
+    round(x, ...) ## inner '...'
+  }, ...) ## outer '...'
+  y
+}
+
+X <- rnorm(10)
+y <- my_fcn(X, digits = 3)
+```
+
+In this case, we have two levels of `...` arguments; one for
+`my_fcn()` and one for the anonymous function.  Note how the `...`
+arguments for `my_fcn()` are passed down to the anonymous function by
+specifying `...` as an final argument to `lapply()`.
+
+The above is the ideal and proper way to pass down `...`. However, it
+is not uncommon to see that the `...` is used as a global variable in
+anonymous functions. For example, you might find:
+
+```r
+my_fcn <- function(X, ...) {  ## outer '...'
+  y <- lapply(X, FUN = function(x) {
+    round(x, ...) ## outer '...' as global variables
+  })
+  y
+}
+```
+
+This will also work, because `...` becomes a global variable in the
+environment of the anonymous function. Although we know that relying
+on global variables is a bad idea, this one often slips through.
+
+If we attempt to do the same with the future framework, or other
+parallel frameworks, it might not work. For example, using:
+
+```r
+my_fcn <- function(X, ...) {
+  y <- future_lapply(X, FUN = function(x) {
+    round(x, ...)
+  })
+  y
+}
+```
+
+might result in an error on:
+
+```
+Error: '...' used in an incorrect context
+```
+
+Even you do not get this error, it is always a good idea to make sure
+`...` is passed as an argument all the way down to where it is used,
+e.g.
+
+```r
+my_fcn <- function(X, ...) {
+  y <- future.apply::future_lapply(X, FUN = function(x, ...) {
+    round(x, ...)
+  }, ...)
+  y
+}
+```
+
+
+
 ## Non-exportable objects
 
 Certain types of objects are tied to a given R session and cannot be passed along to another R process (a "worker").  An example of a non-exportable object is is XML objects of the **[xml2]** package.  If we attempt to use those in parallel processing, we may get a error when the future is evaluated (or just invalid results depending on how they are used), e.g.