Merge branch 'release/1.0.1'

.github/workflows/R-CMD-check.yaml

@@ -22,14 +22,14 @@ jobs:
           - {os: macOS-latest,   r: 'devel'    }
           - {os: macOS-latest,   r: 'release'  }
           - {os: macOS-latest,   r: 'oldrel'   }
-#          - {os: ubuntu-20.04,   r: 'devel'    }
-          - {os: ubuntu-20.04,   r: 'release'  }
-          - {os: ubuntu-20.04,   r: 'oldrel'   }
-          - {os: ubuntu-20.04,   r: 'oldrel-1' }
-          - {os: ubuntu-20.04,   r: 'oldrel-2' }
-          - {os: ubuntu-20.04,   r: '3.4'      }
-          - {os: ubuntu-20.04,   r: 'release'  , plan: multicore,    label: 'w/ multicore'    }
-          - {os: ubuntu-20.04,   r: 'release'  , plan: multisession, label: 'w/ multisession' }
+#          - {os: ubuntu-latest,  r: 'devel'    }
+          - {os: ubuntu-latest,  r: 'release'  }
+          - {os: ubuntu-latest,  r: 'oldrel'   }
+          - {os: ubuntu-latest,  r: 'oldrel-1' }
+          - {os: ubuntu-latest,  r: 'oldrel-2' }
+          - {os: ubuntu-latest,  r: '3.6'      }
+          - {os: ubuntu-latest,  r: 'release'  , plan: multicore,    label: 'w/ multicore'    }
+          - {os: ubuntu-latest,  r: 'release'  , plan: multisession, label: 'w/ multisession' }
 
     env:
       GITHUB_PAT: ${{ secrets.GITHUB_TOKEN }}
@@ -51,7 +51,7 @@ jobs:
       R_FUTURE_GLOBALS_ONREFERENCE: "warning"
 
     steps:
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@v4
 
       - uses: r-lib/actions/setup-pandoc@v2
 

.github/workflows/covr.yaml

@@ -8,7 +8,7 @@ jobs:
 
     timeout-minutes: 15
 
-    runs-on: ubuntu-20.04
+    runs-on: ubuntu-latest
 
     name: covr
 
@@ -17,7 +17,7 @@ jobs:
 
     env:
       GITHUB_PAT: ${{ secrets.GITHUB_TOKEN }}
-      RSPM: https://packagemanager.rstudio.com/cran/__linux__/focal/latest
+      RSPM: https://packagemanager.rstudio.com/cran/__linux__/jammy/latest
       R_REMOTES_NO_ERRORS_FROM_WARNINGS: true
       ## R CMD check
       _R_CHECK_LENGTH_1_CONDITION_: true
@@ -26,7 +26,7 @@ jobs:
       _R_CHECK_CRAN_INCOMING_: false
 
     steps:
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@v4
 
       - uses: r-lib/actions/setup-pandoc@v2
 

.github/workflows/doFuture.tests.extra.yaml

@@ -8,7 +8,7 @@ jobs:
 
     timeout-minutes: 30
 
-    runs-on: ubuntu-20.04
+    runs-on: ubuntu-latest
 
     name: ${{ matrix.config.r }} (${{ matrix.config.strategies }})
 
@@ -24,7 +24,7 @@ jobs:
 
     env:
       GITHUB_PAT: ${{ secrets.GITHUB_TOKEN }}
-      RSPM: https://packagemanager.rstudio.com/cran/__linux__/focal/latest
+      RSPM: https://packagemanager.rstudio.com/cran/__linux__/jammy/latest
       R_REMOTES_NO_ERRORS_FROM_WARNINGS: true
       ## R CMD check
       _R_CHECK_LENGTH_1_CONDITION_: true
@@ -38,7 +38,7 @@ jobs:
       _R_CHECK_FUTURE_STRATEGIES_: ${{ matrix.config.strategies }}
 
     steps:
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@v4
 
       - uses: r-lib/actions/setup-pandoc@v2
 

DESCRIPTION

@@ -1,5 +1,5 @@
 Package: doFuture
-Version: 1.0.0
+Version: 1.0.1
 Title: Use Foreach to Parallelize via the Future Framework
 Depends:
     foreach (>= 1.5.0),
@@ -16,9 +16,11 @@ Suggests:
     R.rsp
 VignetteBuilder:
     R.rsp
-Authors@R: c(person("Henrik", "Bengtsson", role=c("aut", "cre", "cph"),
-                                          email = "[email protected]"))
-Description: The 'future' package provides a unifying parallelization framework for R that supports many parallel and distributed backends. The 'foreach' package provides a powerful API for iterating over an R expression in parallel. The 'doFuture' package brings the best of the two together. There are two alternative ways to use this package. The first is the traditional 'foreach' approach by registering the 'foreach' adapter 'registerDoFuture()' and so that 'y <- foreach(...) %dopar% { ... }' runs in parallelizes with the 'future' framework. The other alternative is to use 'y <- foreach(...) %dofuture% { ... }', which does not require using 'registerDoFuture()' and has many advantages over '%dopar%'.
+Authors@R: c(person("Henrik", "Bengtsson",
+                    role = c("aut", "cre", "cph"),
+                    email = "[email protected]",
+                    comment = c(ORCID = "0000-0002-7579-5165")))
+Description: The 'future' package provides a unifying parallelization framework for R that supports many parallel and distributed backends. The 'foreach' package provides a powerful API for iterating over an R expression in parallel. The 'doFuture' package brings the best of the two together. There are two alternative ways to use this package. The recommended approach is to use 'y <- foreach(...) %dofuture% { ... }', which does not require using 'registerDoFuture()' and has many advantages over '%dopar%'. The alternative is the traditional 'foreach' approach by registering the 'foreach' adapter 'registerDoFuture()' and so that 'y <- foreach(...) %dopar% { ... }' runs in parallelizes with the 'future' framework.
 License: LGPL (>= 2.1)
 LazyLoad: TRUE
 URL: https://doFuture.futureverse.org, https://github.com/HenrikBengtsson/doFuture

NEWS.md

@@ -1,4 +1,12 @@
-# Version 1.0.0 [2023-03-23]
+# Version 1.0.1 (2023-12-19)
+
+## Bug Fixes
+
+ * Using `.options.future = list(conditions = NULL)` would be ignored
+   as if it would never had been specified.
+
+
+# Version 1.0.0 (2023-03-23)
 
 ## New Features
 

R/doFuture-package.R

@@ -7,10 +7,35 @@
 #' @section Usage:
 #' There are two alternative ways to use this package:
 #'
-#' 1. `y <- foreach(...) %dopar% { ... }` with `registerDoFuture()`
-#' 2. `y <- foreach(...) %dofuture% { ... }`
+#' 1. `y <- foreach(...) %dofuture% { ... }`
+#' 2. `y <- foreach(...) %dopar% { ... }` with `registerDoFuture()`
 #'
-#' The _first alternative_ is based on the traditional **foreach**
+#' The _first alternative_ (recommended), which uses [`%dofuture%`], avoids
+#' having to use `registerDoFuture()`.  The [`%dofuture%`] operator provides
+#' a more consistent behavior than `%dopar%`, e.g. there is a unique set of
+#' foreach arguments instead of one per possible adapter.  Identification
+#' of globals, random number generation (RNG), and error handling is
+#' handled by the future ecosystem, just like with other map-reduce
+#' solutions such as **[future.apply]** and **[furrr]**.
+#' An example is:
+#'
+#' ```r
+#' library(doFuture)
+#' plan(multisession)
+#'
+#' y <- foreach(x = 1:4, y = 1:10) %dofuture% {
+#'   z <- x + y
+#'   slow_sqrt(z)
+#' }
+#' ```
+#'
+#' This alternative is the recommended way to let `foreach()` parallelize
+#' via the future framework if you start out from scratch.
+#'
+#' See [`%dofuture%`] for more details and examples on this approach.
+#'
+#'
+#' The _second alternative_ is based on the traditional **foreach**
 #' approach where one registers a foreach adapter to be used by `%dopar%`.
 #' A popular adapter is `doParallel::registerDoParallel()`, which
 #' parallelizes on the local machine using the **parallel** package.
@@ -42,29 +67,6 @@
 #'
 #' See [registerDoFuture()] for more details and examples on this approach.
 #'
-#' The _second alternative_, which uses [`%dofuture%`], avoids having to use
-#' `registerDoFuture()`.  The [`%dofuture%`] operator provides a more
-#' consistent behavior than `%dopar%`, e.g. there is a unique set of
-#' foreach arguments instead of one per possible adapter.  Identification
-#' of globals, random number generation (RNG), and error handling is
-#' handled by the future ecosystem, just like with other map-reduce
-#' solutions such as **[future.apply]** and **[furrr]**.
-#' An example is:
-#'
-#' ```r
-#' library(doFuture)
-#' plan(multisession)
-#'
-#' y <- foreach(x = 1:4, y = 1:10) %dofuture% {
-#'   z <- x + y
-#'   slow_sqrt(z)
-#' }
-#' ```
-#'
-#' This alternative is the recommended way to let `foreach()` parallelize
-#' via the future framework if you start out from scratch.
-#'
-#' See [`%dofuture%`] for more details and examples on this approach.
 #'
 #' [future.apply]: https://cran.r-project.org/package=future.apply
 #' [furrr]: https://cran.r-project.org/package=furrr

R/doFuture.R

@@ -187,8 +187,11 @@ function(obj, expr, envir, data) {   #nolint
   stdout <- options[["stdout"]]
   if (is.null(stdout)) stdout <- eval(formals(Future)$stdout)
 
-  conditions <- options[["conditions"]]
-  if (is.null(conditions)) conditions <- eval(formals(Future)$conditions)
+  if ("conditions" %in% names(options)) {
+    conditions <- options[["conditions"]]
+  } else {
+    conditions <- eval(formals(future)$conditions)
+  }
 
   ## Drop captured standard output and conditions as soon as they have
   ## been relayed?

R/dofuture_OP.R

@@ -139,6 +139,27 @@
 #' For further details and instructions, see
 #' [future.apply::future_lapply()].
 #'
+#' @section Reporting on progress:
+#' How to report on progress is a frequently asked question, especially
+#' in long-running tasks and parallel processing.  The **foreach**
+#' framework does _not_ have a built-in mechanism for progress
+#' reporting(*).
+#'
+#' When using **doFuture**, and the Futureverse in general, for
+#' processing, the **progressr** package can be used to signal progress
+#' updates in a near-live fashion.  There is special argument related to
+#' `foreach()` or **doFuture** to achieve this. Instead, one calls a
+#' a, so called, "progressor" function within each iteration.  See
+#' the [**progressr**](https://cran.r-project.org/package=progressr)
+#' package and its `vignette(package = "progressr")` for examples.
+#'
+#' (*) The legacy **doSNOW** package uses a special `foreach()` argument
+#' `.options.doSNOW$progress` that can be used to make a progress update
+#' each time results from a parallel workers is returned. This approach
+#' is limited by how chunking works, requires the developer to set that
+#' argument, and the code becomes incompatible with foreach adaptors
+#' registered by other **doNnn** packages.
+#'
 #'
 #' @example incl/dofuture_OP.R
 #'
@@ -203,7 +224,7 @@ doFuture2 <- function(obj, expr, envir, data) {   #nolint
   ## Support %globals%, %packages%, %seed%, ...
   opts <- getOption("future.disposable", NULL)
   for (name in names(opts)) {
-    options[[name]] <- opts[[name]]
+    options[name] <- opts[name]
   }
   options(future.disposable = NULL)
 
@@ -254,9 +275,10 @@ doFuture2 <- function(obj, expr, envir, data) {   #nolint
   if (is.null(stdout)) {
     stdout <- eval(formals(future)$stdout)
   }
-
-  conditions <- options[["conditions"]]
-  if (is.null(conditions)) {
+
+  if ("conditions" %in% names(options)) {
+    conditions <- options[["conditions"]]
+  } else {
     conditions <- eval(formals(future)$conditions)
   }
 

R/registerDoFuture.R

@@ -157,6 +157,27 @@
 #' also rely on the foreach framework, so it is important to avoid stepping on 
 #' others' toes._
 #'
+#' @section Reporting on progress:
+#' How to report on progress is a frequently asked question, especially
+#' in long-running tasks and parallel processing.  The **foreach**
+#' framework does _not_ have a built-in mechanism for progress
+#' reporting(*).
+#'
+#' When using **doFuture**, and the Futureverse in general, for
+#' processing, the **progressr** package can be used to signal progress
+#' updates in a near-live fashion.  There is special argument related to
+#' `foreach()` or **doFuture** to achieve this. Instead, one calls a
+#' a, so called, "progressor" function within each iteration.  See
+#' the [**progressr**](https://cran.r-project.org/package=progressr)
+#' package and its `vignette(package = "progressr")` for examples.
+#'
+#' (*) The legacy **doSNOW** package uses a special `foreach()` argument
+#' `.options.doSNOW$progress` that can be used to make a progress update
+#' each time results from a parallel workers is returned. This approach
+#' is limited by how chunking works, requires the developer to set that
+#' argument, and the code becomes incompatible with foreach adaptors
+#' registered by other **doNnn** packages.
+#'
 #' @return 
 #' `registerDoFuture()` returns, invisibly, the previously registered 
 #' foreach `%dopar%` backend.

README.md

@@ -1,5 +1,3 @@
-
-
 <div id="badges"><!-- pkgdown markup -->
 <a href="https://CRAN.R-project.org/web/checks/check_results_doFuture.html"><img border="0" src="https://www.r-pkg.org/badges/version/doFuture" alt="CRAN check status"/></a> <a href="https://github.com/HenrikBengtsson/doFuture/actions?query=workflow%3AR-CMD-check"><img border="0" src="https://github.com/HenrikBengtsson/doFuture/actions/workflows/R-CMD-check.yaml/badge.svg?branch=develop" alt="R CMD check status"/></a>     <a href="https://app.codecov.io/gh/HenrikBengtsson/doFuture"><img border="0" src="https://codecov.io/gh/HenrikBengtsson/doFuture/branch/develop/graph/badge.svg" alt="Coverage Status"/></a> 
 </div>
@@ -31,14 +29,42 @@ in parallel.
 The **[doFuture]** package provides two alternatives for using futures
 with **foreach**:
 
+ 1. `y <- foreach(...) %dofuture% { ... }`
+
  1. `registerDoFuture()` + `y <- foreach(...) %dopar% { ... }`.
 
- 2. `y <- foreach(...) %dofuture% { ... }`
+
+### Alternative 1: `%dofuture%`
+
+The _first alternative_ (recommended), which uses `%dofuture%`, avoids
+having to use `registerDoFuture()`.  The `%dofuture%` operator
+provides a more consistent behavior than `%dopar%`, e.g. there is a
+unique set of foreach arguments instead of one per possible adapter.
+Identification of globals, random number generation (RNG), and error
+handling is handled by the future ecosystem, just like with other
+map-reduce solutions such as **[future.apply]** and **[furrr]**.  An
+example is:
+
+```r
+library(doFuture)
+plan(multisession)
+
+y <- foreach(x = 1:4, y = 1:10) %dofuture% {
+  z <- x + y
+  slow_sqrt(z)
+}
+```
+
+This alternative is the recommended way to let `foreach()` parallelize
+via the future framework, especially if you start out from scratch.
+
+See `help("%dofuture%", package = "doFuture")` for more details and
+examples on this approach.
 
 
-### Alternative 1: `registerDoFuture()` + `%dopar%`
+### Alternative 2: `registerDoFuture()` + `%dopar%`
 
-The _first alternative_ is based on the traditional **foreach**
+The _second alternative_ is based on the traditional **foreach**
 approach where one registers a foreach adapter to be used by `%dopar%`.
 A popular adapter is `doParallel::registerDoParallel()`, which
 parallelizes on the local machine using the **parallel** package.
@@ -73,33 +99,6 @@ See `help("registerDoFuture", package = "doFuture")` for more details
 and examples on this approach.
 
 
-### Alternative 2: `%dofuture%`
-
-The _second alternative_, which uses `%dofuture%`, avoids having to use
-`registerDoFuture()`.  The `%dofuture%` operator provides a more
-consistent behavior than `%dopar%`, e.g. there is a unique set of
-foreach arguments instead of one per possible adapter.  Identification
-of globals, random number generation (RNG), and error handling is
-handled by the future ecosystem, just like with other map-reduce
-solutions such as **[future.apply]** and **[furrr]**.
-An example is:
-
-```r
-library(doFuture)
-plan(multisession)
-
-y <- foreach(x = 1:4, y = 1:10) %dofuture% {
-  z <- x + y
-  slow_sqrt(z)
-}
-```
-
-This alternative is the recommended way to let `foreach()` parallelize
-via the future framework if you start out from scratch.
-
-See `help("%dofuture%", package = "doFuture")` for more details and
-examples on this approach.
-
 
 [doFuture]: https://doFuture.futureverse.org
 [future]: https://future.futureverse.org
@@ -135,4 +134,3 @@ This will install the package from source.
 ## Contributing
 
 To contribute to this package, please see [CONTRIBUTING.md](CONTRIBUTING.md).
-