Merge branch 'release/1.1.1'

Author: HenrikBengtsson

DESCRIPTION

@@ -1,5 +1,5 @@
 Package: doFuture
-Version: 1.1.0
+Version: 1.1.1
 Title: Use Foreach to Parallelize via the Future Framework
 Depends:
     foreach (>= 1.5.0),

NEWS.md

@@ -1,3 +1,14 @@
+# Version 1.1.1 (2025-06-06)
+
+## Bug Fixes
+
+ * `foreach(...) %dofuture% { ... }` would signal errors, despite
+   using `.errorhandling = "pass"` or `.errorhandling = "remove"`.
+   This was originally by design, because "all errors should be
+   errors", but I have since reconsidered and concluded it was a
+   design mistake. Now `.errorhandling` works also with `%dofuture%`.
+ 
+
 # Version 1.1.0 (2025-05-19)
 
 ## New Features
@@ -15,7 +26,9 @@
    error through R's message condition mechanism.
 
  * Add support for `with(registerDoFuture(), { ... })` to temporarily
-   use the doFuture adapter.
+   use the doFuture adapter. Can also be used as
+   `with(registerDoFuture(), local = TRUE)` to temporarily register it
+   within a function.
 
  * Add `registerDoFuture(flavor = "%dofuture%")`, which makes the
    `%dopar%` infix operator behave as if `%dofuture%` would have been

R/001.import_future_functions.R

@@ -1,6 +1,10 @@
 ## To be imported from 'future', if available
 .debug <- NULL
 
+make_rng_seeds <- import_future("make_rng_seeds")
+next_random_seed <- import_future("next_random_seed")
+set_random_seed <- import_future("set_random_seed")
+
 ## Import private functions from 'future'
 import_future_functions <- function() {
   .debug <<- import_future(".debug", mode = "environment", default = new.env(parent = emptyenv()))

R/condition-handlers.R

@@ -1,7 +1,7 @@
 #' @importFrom future FutureInterruptError
-onDoFutureInterrupt <- function(int, op_name = "%dofuture%", debug = FALSE) {
+onInterrupt <- function(int, op_name, debug = FALSE) {
   if (debug) {
-    mdebug_push("onDoFutureInterrupt() ...")
+    mdebug_push("onInterrupt() ...")
     mdebug(sprintf("Received <%s>", class(int)[1]))
     on.exit(mdebug_pop())
   }
@@ -12,16 +12,16 @@ onDoFutureInterrupt <- function(int, op_name = "%dofuture%", debug = FALSE) {
   msg <- sprintf("'%s' interrupted at %s, while running on %s (pid %s)", op_name, format(when, format = "%FT%T"), sQuote(host), pid)
 
   ## By signaling the interrupt as an error, the next handler, which should
-  ## be onDoFutureError(), will take care of canceling outstanding futures
+  ## be onError(), will take care of canceling outstanding futures
   stop(FutureInterruptError(msg))
-} ## onDoFutureInterrupt()
+}
 
 
 
 #' @importFrom future cancel resolve value
-onDoFutureError <- function(ex, futures, debug = FALSE) {
+onError <- function(ex, futures, debug = FALSE) {
   if (debug) {
-    mdebug_push("onDoFutureError() ...")
+    mdebug_push("onError() ...")
     mdebug(sprintf("Received <%s>", class(ex)[1]))
     on.exit(mdebug_pop())
   }
@@ -40,4 +40,4 @@ onDoFutureError <- function(ex, futures, debug = FALSE) {
   if (debug) mdebug(sprintf("Signaling: <%s>", class(ex)[1]))
 
   stop(ex)
-} ## onDoFutureError()
+}

R/doFuture.R

@@ -378,9 +378,9 @@ function(obj, expr, envir, data) {   #nolint
 
     fs
   }, interrupt = function(int) {
-    onDoFutureInterrupt(int, op_name = "%dopar%", debug = debug)
+    onInterrupt(int, op_name = "%dopar%", debug = debug)
   }, error = function(e) {
-    onDoFutureError(e, futures = fs, debug = debug)
+    onError(e, futures = fs, debug = debug)
   }) ## tryCatch()
   rm(list = c("chunks", "globals", "packages", "labels"))
   stop_if_not(length(fs) == nchunks)
@@ -430,7 +430,7 @@ function(obj, expr, envir, data) {   #nolint
         f <- fs[[idx]]
         label <- f$label
         if (is.null(label)) label <- "<none>"
-        message <- sprintf("UNRELIABLE VALUE: One of the foreach() iterations (%s) unexpectedly generated random numbers without declaring so. There is a risk that those random numbers are not statistically sound and the overall results might be invalid. To fix this, use '%%dorng%%' from the 'doRNG' package instead of '%%dopar%%'. This ensures that proper, parallel-safe random numbers are produced via the L'Ecuyer-CMRG method. To disable this check, set option 'doFuture.rng.onMisuse' to \"ignore\".", sQuote(label))
+        message <- sprintf("UNRELIABLE VALUE: One of the foreach() iterations (%s) unexpectedly generated random numbers without declaring so. There is a risk that those random numbers are not statistically sound and the overall results might be invalid. To fix this, use '%%dorng%%' from the 'doRNG' package instead of '%%dopar%%'. This ensures that proper, parallel-safe random numbers are produced. To disable this check, set option 'doFuture.rng.onMisuse' to \"ignore\".", sQuote(label))
         cond$message <- message
         if (inherits(cond, "warning")) {
           warning(cond)
@@ -448,9 +448,9 @@ function(obj, expr, envir, data) {   #nolint
       resolve(fs, result = TRUE, stdout = TRUE, signal = TRUE)
     }
   }, interrupt = function(int) {
-    onDoFutureInterrupt(int, op_name = "%dopar%", debug = debug)
+    onInterrupt(int, op_name = "%dopar%", debug = debug)
   }, error = function(e) {
-    onDoFutureError(e, futures = fs, debug = debug)
+    onError(e, futures = fs, debug = debug)
   }) ## tryCatch()
 
   ## Gather values

R/doFuture2.R

@@ -70,19 +70,24 @@ doFuture2 <- function(obj, expr, envir, data) {   #nolint
     options[name] <- opts[name]
   }
   options(future.disposable = NULL)
-  
-  errors <- options[["errors"]]
-  if (is.null(errors)) {
-    errors <- "future"
-  } else if (is.character(errors)) {
-    if (length(errors) != 1L) {
-      stop(sprintf("Element 'errors' of '.options.future' should be of length one': [n = %d] %s", length(errors), paste(sQuote(errors), collapse = ", ")))
-    }
-    if (! errors %in% c("future", "foreach")) {
-      stop(sprintf("Unknown value of '.options.future' element 'errors': %s", sQuote(errors)))
-    }
+
+  error_handling <- obj$errorHandling
+  if (!identical(error_handling, "stop")) {
+    errors <- "foreach"
   } else {
-    stop("Unknown type of '.options.future' element 'errors': ", mode(errors))
+    errors <- options[["errors"]]
+    if (is.null(errors)) {
+      errors <- "future"
+    } else if (is.character(errors)) {
+      if (length(errors) != 1L) {
+        stop(sprintf("Element 'errors' of '.options.future' should be of length one': [n = %d] %s", length(errors), paste(sQuote(errors), collapse = ", ")))
+      }
+      if (! errors %in% c("future", "foreach")) {
+        stop(sprintf("Unknown value of '.options.future' element 'errors': %s", sQuote(errors)))
+      }
+    } else {
+      stop("Unknown type of '.options.future' element 'errors': ", mode(errors))
+    }
   }
 
 
@@ -172,7 +177,6 @@ doFuture2 <- function(obj, expr, envir, data) {   #nolint
   if (is.null(seed)) seed <- eval(formals(future)$seed)
   if (debug) mdebugf("seed = %s", deparse(seed))
 
-  make_rng_seeds <- import_future("make_rng_seeds")
   seeds <- make_rng_seeds(nX, seed = seed)
 
   ## Future expression (with or without setting the RNG state) and
@@ -184,8 +188,6 @@ doFuture2 <- function(obj, expr, envir, data) {   #nolint
       mdebug("RNG seeds:")
       mstr(seeds)
     }
-    next_random_seed <- import_future("next_random_seed")
-    set_random_seed <- import_future("set_random_seed")
     ## If RNG seeds are used (given or generated), make sure to reset
     ## the RNG state afterward
     oseed <- next_random_seed()    
@@ -452,9 +454,9 @@ doFuture2 <- function(obj, expr, envir, data) {   #nolint
 
     fs
   }, interrupt = function(int) {
-    onDoFutureInterrupt(int, debug = debug)
+    onInterrupt(int, op_name = "%dofuture%", debug = debug)
   }, error = function(e) {
-    onDoFutureError(e, futures = fs, debug = debug)
+    onError(e, futures = fs, debug = debug)
   }) ## tryCatch()
   rm(list = c("globals", "packages", "labels", "seeds"))
   stop_if_not(length(fs) == nchunks)
@@ -519,7 +521,7 @@ doFuture2 <- function(obj, expr, envir, data) {   #nolint
           iterations <- seq_to_human(chunk)
           iterations <- sprintf("At least one of iterations %s", iterations)
         }
-        message <- sprintf("UNRELIABLE VALUE: %s of the foreach() %%dofuture%% { ... }, part of chunk #%d (%s), unexpectedly generated random numbers without declaring so. There is a risk that those random numbers are not statistically sound and the overall results might be invalid. To fix this, specify foreach() argument '.options.future = list(seed = TRUE)'. This ensures that proper, parallel-safe random numbers are produced via the L'Ecuyer-CMRG method. To disable this check, set option 'doFuture.rng.onMisuse' to \"ignore\".", iterations, idx, sQuote(label))
+        message <- sprintf("UNRELIABLE VALUE: %s of the foreach() %%dofuture%% { ... }, part of chunk #%d (%s), unexpectedly generated random numbers without declaring so. There is a risk that those random numbers are not statistically sound and the overall results might be invalid. To fix this, specify foreach() argument '.options.future = list(seed = TRUE)'. This ensures that proper, parallel-safe random numbers are produced. To disable this check, set option 'doFuture.rng.onMisuse' to \"ignore\".", iterations, idx, sQuote(label))
         cond$message <- message
         if (inherits(cond, "warning")) {
           warning(cond)
@@ -534,9 +536,9 @@ doFuture2 <- function(obj, expr, envir, data) {   #nolint
     }
     values
   }, interrupt = function(int) {
-    onDoFutureInterrupt(int, debug = debug)
+    onInterrupt(int, op_name = "%dofuture%", debug = debug)
   }, error = function(e) {
-    onDoFutureError(e, futures = fs, debug = debug)
+    onError(e, futures = fs, debug = debug)
   }) ## tryCatch()
   rm(list = "chunks")
   stop_if_not(length(values) == nchunks)
@@ -633,7 +635,6 @@ elements in 'X' (= %d). There were in total %d chunks and %d elements (%s)",
       ## ... or as traditionally with %dopar%, which throws an error
       ## or return the combined results
       ## NOTE: This is adopted from foreach:::doSEQ()
-      error_handling <- obj$errorHandling
       if (debug) {
         mdebugf("processing errors (handler = %s)", sQuote(error_handling))
       }

R/dofuture_OP.R

@@ -14,12 +14,16 @@
 #' When using `%dofuture%`:
 #'
 #' * there is no need to use `registerDoFuture()`
+#'
 #' * there is no need to use `%dorng%` of the **doRNG** package
 #'   (but you need to specify `.options.future = list(seed = TRUE)`
 #'    whenever using random numbers in the `expr` expression)
+#'
 #' * global variables and packages are identified automatically by
 #'   the \pkg{future} framework
-#' * errors are relayed as-is (with `%dopar%` they captured and modified)
+#'
+#' * errors are relayed as-is with the default `.errorhandling = "stop"`,
+#'   whereas with `%dopar%` they are captured and modified.
 #'
 #'
 #' @section Global variables and packages:
@@ -59,12 +63,12 @@
 #' workers, and scheduling ("chunking") strategy.
 #' 
 #' RNG reproducibility is achieved by pregenerating the random seeds for all
-#' iterations by using L'Ecuyer-CMRG RNG streams.  In each
+#' iterations by parallel RNG streams.  In each
 #' iteration, these seeds are set before evaluating the foreach expression.
 #' _Note, for large number of iterations this may introduce a large overhead._
 #'
 #' If `seed = TRUE`, then \code{\link[base:Random]{.Random.seed}}
-#' is used if it holds a L'Ecuyer-CMRG RNG seed, otherwise one is created
+#' is used if it holds a parallel RNG seed, otherwise one is created
 #' randomly.
 #'
 #' If `seed = FALSE`, it is expected that none of the foreach iterations
@@ -75,9 +79,9 @@
 #' whether random numbers were generated or not.
 #'
 #' As input, `seed` may also take a fixed initial seed (integer),
-#' either as a full L'Ecuyer-CMRG RNG seed (vector of 1+6 integers), or
-#' as a seed generating such a full L'Ecuyer-CMRG seed. This seed will
-#' be used to generated one L'Ecuyer-CMRG RNG stream for each iteration.
+#' either as a full parallel RNG seed (vector of 1+6 integers), or
+#' as a seed generating such a full seed. This seed will
+#' be used to generated one parallel RNG stream for each iteration.
 #'
 #' An alternative to specifying the `seed` option via `.options.future`,
 #' is to use the \code{\link[future:%seed%]{%seed%}} operator.  See

R/registerDoFuture.R

@@ -1,5 +1,6 @@
 #' Use the Foreach `%dopar%` Adapter with Futures
 #'
+#' @description
 #' The `registerDoFuture()` function makes the
 #' \code{\link[foreach:\%dopar\%]{\%dopar\%}} operator of the
 #' \pkg{foreach} package to process foreach iterations via any of
@@ -10,9 +11,12 @@
 #' and packages making using the \pkg{foreach} framework._
 #' Neither the developer nor the end user has to change any code.
 #'
+#' _**Recommendation**: If you have the option, use [`%dofuture%`] instead
+#' of `%dopar%`, for all the benefits explained in its help page._
+#'
 #' @param flavor Control how the adapter should behave.
 #' If `"%dopar%"`, it behaves as a classical foreach adapter.
-#' If `"%dofuture%"`, it behaves as if `%dofuture%` would have
+#' If `"%dofuture%"`, it behaves as if [`%dofuture%`] would have
 #' been used instead of `%dopar%`.
 #' 
 #' @section Parallel backends:
@@ -63,12 +67,13 @@
 #' all packages automatically (via static code inspection).  This is done
 #' exactly the same way regardless of future backend.
 #' This automatic identification of globals and packages is illustrated
-#' by the below example, which does _not_ specify
+#' by the below example, which does _not_ have specify
 #' `.export = c("my_stat")`.  This works because the future framework
 #' detects that function `my_stat()` is needed and makes sure it is
 #' exported.  If you would use, say, `cl <- parallel::makeCluster(2)`
 #' and `doParallel::registerDoParallel(cl)`, you would get a run-time
-#' error on \code{Error in \{ : task 1 failed - \"could not find function "my_stat" ...}.
+#' error on \code{Error in \{ : task 1 failed - \"could not find function
+#' "my_stat" ...}.
 #'
 #' Having said this, note that, in order for your "foreach" code to work
 #' everywhere and with other types of foreach adapters as well, you may
@@ -146,12 +151,11 @@
 #'
 #' However, if you think it necessary to register the \pkg{doFuture} backend
 #' in a function, please make sure to undo your changes when exiting the
-#' function. This can be done using:
+#' function. This can be achieve by:
 #'
 #' \preformatted{
-#'   oldDoPar <- registerDoFuture()
-#'   on.exit(with(oldDoPar, foreach::setDoPar(fun=fun, data=data, info=info)), add = TRUE)
-#'   [...]
+#'   with(registerDoFuture(), local = TRUE)
+#'   ...
 #' }
 #'
 #' This is important, because the end-user might have already registered a

R/withDoRNG.R

@@ -49,8 +49,8 @@
 #' risk that those random numbers are not statistically sound and the overall
 #' results might be invalid. To fix this, use '%dorng%' from the 'doRNG'
 #' package instead of '%dopar%'. This ensures that proper, parallel-safe
-#' random numbers are produced via the L'Ecuyer-CMRG method. To disable this
-#' check, set option 'doFuture.rng.onMisuse' to "ignore".
+#' random numbers are produced. To disable this check, set option
+#' 'doFuture.rng.onMisuse' to "ignore".
 #' >
 #' ```
 #'

incl/with.R

@@ -2,11 +2,20 @@ with(registerDoFuture(), {
   y <- foreach(x = 1:3) %dopar% { x^2 }
 })
 
-
 a_fcn_in_a_pkg <- function(xs) {
   foreach(x = xs) %dopar% { x^2 }
 }
 
 with(registerDoFuture(flavor = "%dofuture%"), {
   y <- a_fcn_in_a_pkg(1:3)
 })
+
+
+my_fcn <- function(xs) {
+  ## Use registerDoFuture() for this function only and then
+  ## revert back to the previously set foreach adapter
+  with(registerDoFuture(), local = TRUE)
+  
+  foreach(x = xs) %dopar% { x^2 }
+}
+