diff --git a/DESCRIPTION b/DESCRIPTION index b512c39..16652e8 100644 --- a/DESCRIPTION +++ b/DESCRIPTION @@ -1,5 +1,5 @@ Package: doFuture -Version: 1.0.0-9001 +Version: 1.0.0-9002 Title: Use Foreach to Parallelize via the Future Framework Depends: foreach (>= 1.5.0), diff --git a/R/doFuture-package.R b/R/doFuture-package.R index da9c4bf..f9724c2 100644 --- a/R/doFuture-package.R +++ b/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 diff --git a/README.md b/README.md index af6154c..e59b823 100644 --- a/README.md +++ b/README.md @@ -1,5 +1,3 @@ - -
CRAN check status R CMD check status Coverage Status
@@ -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). - diff --git a/man/doFuture.Rd b/man/doFuture.Rd index 1aad172..65ddaec 100644 --- a/man/doFuture.Rd +++ b/man/doFuture.Rd @@ -14,11 +14,34 @@ such that \code{foreach()} parallelizes via \emph{any} future backend. There are two alternative ways to use this package: \enumerate{ -\item \code{y <- foreach(...) \%dopar\% { ... }} with \code{registerDoFuture()} \item \code{y <- foreach(...) \%dofuture\% { ... }} +\item \code{y <- foreach(...) \%dopar\% { ... }} with \code{registerDoFuture()} } -The \emph{first alternative} is based on the traditional \strong{foreach} +The \emph{first alternative} (recommended), which uses \code{\link{\%dofuture\%}}, avoids +having to use \code{registerDoFuture()}. The \code{\link{\%dofuture\%}} operator provides +a more consistent behavior than \verb{\%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 \strong{\href{https://cran.r-project.org/package=future.apply}{future.apply}} and \strong{\href{https://cran.r-project.org/package=furrr}{furrr}}. +An example is: + +\if{html}{\out{
}}\preformatted{library(doFuture) +plan(multisession) + +y <- foreach(x = 1:4, y = 1:10) \%dofuture\% \{ + z <- x + y + slow_sqrt(z) +\} +}\if{html}{\out{
}} + +This alternative is the recommended way to let \code{foreach()} parallelize +via the future framework if you start out from scratch. + +See \code{\link{\%dofuture\%}} for more details and examples on this approach. + +The \emph{second alternative} is based on the traditional \strong{foreach} approach where one registers a foreach adapter to be used by \verb{\%dopar\%}. A popular adapter is \code{doParallel::registerDoParallel()}, which parallelizes on the local machine using the \strong{parallel} package. @@ -48,28 +71,5 @@ and any package that rely on it, to parallelize via the future framework. See \code{\link[=registerDoFuture]{registerDoFuture()}} for more details and examples on this approach. - -The \emph{second alternative}, which uses \code{\link{\%dofuture\%}}, avoids having to use -\code{registerDoFuture()}. The \code{\link{\%dofuture\%}} operator provides a more -consistent behavior than \verb{\%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 \strong{\href{https://cran.r-project.org/package=future.apply}{future.apply}} and \strong{\href{https://cran.r-project.org/package=furrr}{furrr}}. -An example is: - -\if{html}{\out{
}}\preformatted{library(doFuture) -plan(multisession) - -y <- foreach(x = 1:4, y = 1:10) \%dofuture\% \{ - z <- x + y - slow_sqrt(z) -\} -}\if{html}{\out{
}} - -This alternative is the recommended way to let \code{foreach()} parallelize -via the future framework if you start out from scratch. - -See \code{\link{\%dofuture\%}} for more details and examples on this approach. } diff --git a/vignettes/doFuture-1-overview.md.rsp b/vignettes/doFuture-1-overview.md.rsp index 60ce710..e4a5a35 100644 --- a/vignettes/doFuture-1-overview.md.rsp +++ b/vignettes/doFuture-1-overview.md.rsp @@ -47,20 +47,49 @@ in parallel. The **[doFuture]** package provides two alternatives for using futures with **foreach**: - 1. `registerDoFuture()` + `y <- foreach(...) %dopar% { ... }`. + 1. `y <- foreach(...) %dofuture% { ... }` + + 2. `registerDoFuture()` + `y <- foreach(...) %dopar% { ... }`. - 2. `y <- foreach(...) %dofuture% { ... }` -### Alternative 1: `registerDoFuture()` + `%dopar%` +### 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 2: `registerDoFuture()` + `%dopar%` -The _first 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. -This package provides `registerDoFuture()`, which parallelizes using -the **future** package, meaning any future-compliant parallel backend -can be used. +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. This package provides `registerDoFuture()`, which +parallelizes using the **future** package, meaning any +future-compliant parallel backend can be used. An example is: @@ -89,33 +118,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