Clarify that packages must not change any of the future.* options [#…

…708]

DESCRIPTION

@@ -1,5 +1,5 @@
 Package: future
-Version: 1.33.1-9006
+Version: 1.33.1-9007
 Title: Unified Parallel and Distributed Processing in R for Everyone
 Imports:
     digest,

NEWS.md

@@ -14,6 +14,10 @@
    preserves the "AsIs" class attribute on the `workers` argument so
    that it is propagated to `parallelly::makeClusterWorkers()`.
 
+## Documentation
+
+ * Clarify that packages must not change any of the `future.*` options.
+
 
 # Version 1.33.1 [2023-12-21]
 

R/options.R

@@ -7,6 +7,21 @@
 #'  change in future versions of the package.  Please use with care until
 #'  further notice._
 #'
+#' @section Packages must not change future options:
+#'
+#' Just like for other R options, as a package developer you must _not_ change
+#' any 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 to
+#' undo your changes immediately afterward.  For example, if you want to
+#' bump up the `future.globals.maxSize` limit when creating a future,
+#' use something like the following inside your function:
+#'
+#' ```r
+#' oopts <- options(future.globals.maxSize = 1.0 * 1e9)  ## 1.0 GB
+#' on.exit(options(oopts))
+#' f <- future({ expr })  ## Launch a future with large objects
+#' ```
+#'
 #' @section Settings moved to the 'parallelly' package:
 #' Several functions have been moved to the \pkg{parallelly} package:
 #'

vignettes/future-7-for-package-developers.md.rsp

@@ -127,6 +127,23 @@ my_fcn <- function(x) {
 and let the user control whether or not they want to parallelize via `plan()`, e.g. `plan(multisession)` and `plan(sequential)`.
 
 
+## Avoid changing the future options
+
+Just like for other R options, you must not change any of the R
+`future.*` options.  Only the end-user should set these.
+
+If you find yourself having to tweak one of the options, make sure to
+undo your changes immediately afterward.  For example, if you want to
+bump up the `future.globals.maxSize` limit when creating a future,
+use something like the following inside your function:
+
+```r
+oopts <- options(future.globals.maxSize = 1.0 * 1e9)  ## 1.0 GB
+on.exit(options(oopts))
+f <- future({ expr })  ## Launch a future with large objects
+```
+
+
 ## Writing examples
 
 If your example sets the future strategy at the beginning, make sure to reset the future strategy to `plan(sequential)` at the end of the example.  The reason for this is that when switching plan, the previous one will be cleaned up.  This is particularly important for multisession and cluster futures where `plan(sequential)` will shut down the underlying PSOCK clusters.