futureverse /progressr

三 R package: An Inclusive, Unifying API for Progress Updates

★ 299⑂ 11👁 5⑃ 8● 180▤ 0
RApache-2.0Created 2019-04-12progressr.futureverse.org
+0
日增长
299
stars
11
forks
5
watchers
8
prs
180
issues
0
releases

README

progressr: An Inclusive, Unifying API for Progress Updates 



The [progressr] package provides a minimal API for reporting
progress updates in R.  The design is to
separate the representation of progress updates from how they are
presented.  What type of progress to signal is controlled by the
developer.  How these progress updates are rendered is controlled by
the end user.  For instance, some users may prefer visual feedback
such as a horizontal progress bar in the terminal, whereas others may
prefer auditory feedback.  The [progressr] framework is designed
to work out-of-the-box also for parallel and distributed processing,
especially with the [futureverse] ecosystem.

Design motto:

 The developer is responsible for providing progress updates but it's
 only the end user who decides if, when, and how progress should be
 presented. No exceptions will be allowed.


 Two Minimal APIs - One For Developers and One For End-Users




Developer's API



1. Set up a progressor with a certain number of steps:


p <- progressor(nsteps)
p <- progressor(along = x)



2. Signal progress:



p()                one-step progress
p(amount = 0)      "still alive"
p("loading ...")   pass on a message





    


End-user's API



1a. Subscribe to progress updates from everywhere:



handlers(global = TRUE)

y <- slow_sum_p(1:5)
y <- slow_sum_p(6:10)



1b. Subscribe to a specific expression:



with_progress({
  y <- slow_sum_p(1:5)
  y <- slow_sum_p(6:10)
})



2. Configure how progress is presented:



handlers("cli")
handlers("progress")
handlers("txtprogressbar", "beepr")
handlers(handler_pbcol(enable_after = 3.0))
handlers(handler_progress(complete = ""))






 A simple example

Assume that we have a function slow_sum_p() for adding up the values
in a vector.  It is so slow, that we like to provide progress updates
to whoever might be interested in it.  With the progressr package,
this can be done as:

r
slow_sum_p  [1] 55
 

the default is that there will be _no_ progress updates. To get
progress updates, we need to request them to be "handled", which we do
by:

r
progressr::handlers(global = TRUE)


After this, progress will be reported:

r
y    |====================                               |  40%
y    |========================================           |  80%


To disable reporting again, do:

r
handlers(global = FALSE)



 Customizing how progress is reported

By default, [progressr] presents progress via the built-in
utils::txtProgressBar(). It presents itself as a rudimentary
ASCII-based horizontal progress bar in the R terminal. See
help("handler_txtprogressbar") for how to customize the look of
"txtprogressbar", e.g. colorization and Unicode.  There are many other
ways to report on progress, including visually, auditory, and via
notification systems. You can also use a mix of these, e.g.

r
handlers(c("cli", "beepr", "ntfy"))


See the 'Customizing How Progress is Reported' vignette for examples.


 Addi

Top issues

Snapshot: 2026-11-16T09:23:14Z · Data license Apache-2.0 · JSON