POC: Signal progress via progressr

DESCRIPTION

@@ -20,6 +20,7 @@ Depends:
     R (>= 4.1.0)
 Imports:
     globals (>= 0.18.0),
+    progressr (>= 0.18.0),
     purrr (>= 1.2.1),
     rlang (>= 1.1.7),
     vctrs (>= 0.7.0)
@@ -31,7 +32,6 @@ Suggests:
     parallelly (>= 1.46.1),
     testthat (>= 3.3.2),
     tidyselect
-Config/Needs/website:progressr
 Config/testthat/edition: 3
 Encoding: UTF-8
 Roxygen: list(markdown = TRUE)

R/future-map.R

@@ -45,15 +45,35 @@
 #' @param .options The `future` specific options to use with the workers. This
 #'   must be the result from a call to [furrr_options()].
 #'
-#' @param .progress A single logical. Should a progress bar be displayed?
-#'   Only works with multisession, multicore, and multiprocess futures. Note
-#'   that if a multicore/multisession future falls back to sequential, then
-#'   a progress bar will not be displayed.
-#'
-#'   __Warning:__ The `.progress` argument will be deprecated and removed
-#'   in a future version of furrr in favor of using the more robust
-#'   [progressr](https://CRAN.R-project.org/package=progressr)
-#'   package.
+#' @param .progress `r lifecycle::badge("experimental")`
+#'
+#'   Either `TRUE` or `FALSE`.
+#'
+#'   TODO!(write this): See `vignette("progress")` for examples.
+#'
+#'   If `TRUE`, a `progressr::progressor()` is automatically created
+#'   with as many steps as there are elements to iterate over. After each
+#'   call to `.f`, progression is _signaled_ back to the main process.
+#'
+#'   Note that `.progress = TRUE` is not enough to make progress notifications
+#'   _appear_. You must also either wrap the furrr expression in
+#'   [progressr::with_progress()] or set [`progressr::handlers(global =
+#'   TRUE)`][progressr::handlers()] at the top of your script (this enables
+#'   _all_ progress notifications, which is recommended for interative work).
+#'
+#'   To customize the progress notification, set an alternative progressr
+#'   handler, such as
+#'   [`progressr::handlers(progressr::handler_cli())`][progressr::handler_cli()]
+#'   or
+#'   [`progressr::handlers(progressr::handler_rstudio())`][progressr::handler_rstudio()].
+#'
+#'   Note that progress notifications are not free, as they require
+#'   communicating a small amount of data back to the main worker after each
+#'   call to `.f`. It is recommended to only use them with long running tasks.
+#'
+#'   All core `plan()` types are supported, including `sequential`, `cluster`,
+#'   `multisession`, and `multicore`. Additionally, `future.callr::callr` and
+#'   `future.mirai::mirai_multisession` are also known to be supported.
 #'
 #' @param .ptype If `NULL`, the default, the output type is the common type of
 #'   the elements of the result. Otherwise, supply a "prototype" giving the

R/globals.R

@@ -3,24 +3,49 @@ get_globals_and_packages <- function(
   packages,
   fn,
   dots,
+  progressor,
   env_globals
 ) {
   objectSize <- import_future("objectSize")
 
+  # Needs to be `FutureGlobals` for `future:::c.FutureGlobals` to kick in
+  globals_out <- list()
+  globals_out <- future::as.FutureGlobals(globals_out)
+  globals_out <- future::resolve(globals_out)
+  globals_out <- set_total_size(globals_out, objectSize(globals_out))
+
+  packages_out <- character()
+
   # Always need purrr on the worker
-  packages_out <- "purrr"
+  packages_out <- c(packages_out, "purrr")
 
   # Always get `.f`
   globals_fn <- list(...furrr_fn = fn)
   globals_fn <- future::as.FutureGlobals(globals_fn)
   globals_fn <- future::resolve(globals_fn)
   globals_fn <- set_total_size(globals_fn, objectSize(globals_fn))
+  globals_out <- c(globals_out, globals_fn)
 
   # Always get `...`.
   globals_dots <- list(...furrr_dots = dots)
   globals_dots <- future::as.FutureGlobals(globals_dots)
   globals_dots <- future::resolve(globals_dots)
   globals_dots <- set_total_size(globals_dots, objectSize(globals_dots))
+  globals_out <- c(globals_out, globals_dots)
+
+  # Always get `progressor` if supplied
+  if (!is.null(progressor)) {
+    globals_progressor <- list(...furrr_progressor = progressor)
+    globals_progressor <- future::as.FutureGlobals(globals_progressor)
+    globals_progressor <- future::resolve(globals_progressor)
+    globals_progressor <- set_total_size(
+      globals_progressor,
+      objectSize(globals_progressor)
+    )
+    globals_out <- c(globals_out, globals_progressor)
+
+    packages_out <- c(packages_out, "progressr")
+  }
 
   # Always get chunk specific placeholders
   globals_extra <- list(
@@ -31,12 +56,7 @@ get_globals_and_packages <- function(
   globals_extra <- future::as.FutureGlobals(globals_extra)
   globals_extra <- future::resolve(globals_extra)
   globals_extra <- set_total_size(globals_extra, objectSize(globals_extra))
-
-  globals_out <- c(
-    globals_fn,
-    globals_dots,
-    globals_extra
-  )
+  globals_out <- c(globals_out, globals_extra)
 
   # Collect all globals recursively
   # Search in the parent frame of the `future_*()` call for globals