diff --git a/DESCRIPTION b/DESCRIPTION index 947441a..77ab2cc 100644 --- a/DESCRIPTION +++ b/DESCRIPTION @@ -1,5 +1,5 @@ Package: progressr -Version: 0.14.0-9000 +Version: 0.14.0-9001 Title: An Inclusive, Unifying API for Progress Updates Description: A minimal, unifying API for scripts and packages to report progress updates from anywhere including when using parallel processing. The package is designed such that the developer can to focus on what progress should be reported on without having to worry about how to present it. The end user has full control of how, where, and when to render these progress updates, e.g. in the terminal using utils::txtProgressBar(), cli::cli_progress_bar(), in a graphical user interface using utils::winProgressBar(), tcltk::tkProgressBar() or shiny::withProgress(), via the speakers using beepr::beep(), or on a file system via the size of a file. Anyone can add additional, customized, progression handlers. The 'progressr' package uses R's condition framework for signaling progress updated. Because of this, progress can be reported from almost anywhere in R, e.g. from classical for and while loops, from map-reduce API:s like the lapply() family of functions, 'purrr', 'plyr', and 'foreach'. It will also work with parallel processing via the 'future' framework, e.g. future.apply::future_lapply(), furrr::future_map(), and 'foreach' with 'doFuture'. The package is compatible with Shiny applications. Authors@R: c(person("Henrik", "Bengtsson", diff --git a/README.md b/README.md index a301d86..e652358 100644 --- a/README.md +++ b/README.md @@ -617,8 +617,35 @@ my_fcn(1:5) ### foreach() with doFuture Here is an example that uses `foreach()` of the **[foreach]** package -to parallelize on the local machine (via **[doFuture]**) while at the -same time signaling progression updates: +together with `%dofuture%` of the **[doFuture]** package to +parallelize while reporting on progress. This example parallelizes on +the local machine, it works alsof for remote machines: + +```r +library(doFuture) ## %dofuture% +plan(multisession) + +library(progressr) +handlers(global = TRUE) +handlers("progress", "beepr") + +my_fcn <- function(xs) { + p <- progressor(along = xs) + foreach(x = xs) %dofuture% { + Sys.sleep(6.0-x) + p(sprintf("x=%g", x)) + sqrt(x) + } +} + +my_fcn(1:5) +# / [================>-----------------------------] 40% x=2 +``` + + +For existing code using the traditional `%dopar%` operators of the +**[foreach]** package, we can register the **[doFuture]** adaptor and +use the same **progressr** as above to progress updates; ```r library(doFuture) diff --git a/incl/OVERVIEW.md b/incl/OVERVIEW.md index 8fea0a0..250fc60 100644 --- a/incl/OVERVIEW.md +++ b/incl/OVERVIEW.md @@ -609,8 +609,35 @@ my_fcn(1:5) ### foreach() with doFuture Here is an example that uses `foreach()` of the **[foreach]** package -to parallelize on the local machine (via **[doFuture]**) while at the -same time signaling progression updates: +together with `%dofuture%` of the **[doFuture]** package to +parallelize while reporting on progress. This example parallelizes on +the local machine, it works alsof for remote machines: + +```r +library(doFuture) ## %dofuture% +plan(multisession) + +library(progressr) +handlers(global = TRUE) +handlers("progress", "beepr") + +my_fcn <- function(xs) { + p <- progressor(along = xs) + foreach(x = xs) %dofuture% { + Sys.sleep(6.0-x) + p(sprintf("x=%g", x)) + sqrt(x) + } +} + +my_fcn(1:5) +# / [================>-----------------------------] 40% x=2 +``` + + +For existing code using the traditional `%dopar%` operators of the +**[foreach]** package, we can register the **[doFuture]** adaptor and +use the same **progressr** as above to progress updates; ```r library(doFuture) diff --git a/vignettes/progressr-intro.md b/vignettes/progressr-intro.md index 9ebd04d..8fa9cb8 100644 --- a/vignettes/progressr-intro.md +++ b/vignettes/progressr-intro.md @@ -620,8 +620,35 @@ my_fcn(1:5) ### foreach() with doFuture Here is an example that uses `foreach()` of the **[foreach]** package -to parallelize on the local machine (via **[doFuture]**) while at the -same time signaling progression updates: +together with `%dofuture%` of the **[doFuture]** package to +parallelize while reporting on progress. This example parallelizes on +the local machine, it works alsof for remote machines: + +```r +library(doFuture) ## %dofuture% +plan(multisession) + +library(progressr) +handlers(global = TRUE) +handlers("progress", "beepr") + +my_fcn <- function(xs) { + p <- progressor(along = xs) + foreach(x = xs) %dofuture% { + Sys.sleep(6.0-x) + p(sprintf("x=%g", x)) + sqrt(x) + } +} + +my_fcn(1:5) +# / [================>-----------------------------] 40% x=2 +``` + + +For existing code using the traditional `%dopar%` operators of the +**[foreach]** package, we can register the **[doFuture]** adaptor and +use the same **progressr** as above to progress updates; ```r library(doFuture)