File: with_progress.Rd

package info (click to toggle)
r-cran-progressr 0.15.1-1
  • links: PTS, VCS
  • area: main
  • in suites: forky, sid, trixie
  • size: 2,132 kB
  • sloc: sh: 13; makefile: 7
file content (160 lines) | stat: -rw-r--r-- 5,135 bytes parent folder | download
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/with_progress.R, R/without_progress.R
\name{with_progress}
\alias{with_progress}
\alias{without_progress}
\title{Report on Progress while Evaluating an R Expression}
\usage{
with_progress(
  expr,
  handlers = progressr::handlers(),
  cleanup = TRUE,
  delay_terminal = NULL,
  delay_stdout = NULL,
  delay_conditions = NULL,
  interrupts = getOption("progressr.interrupts", TRUE),
  interval = NULL,
  enable = NULL
)

without_progress(expr)
}
\arguments{
\item{expr}{An \R expression to evaluate.}

\item{handlers}{A progression handler or a list of them.
If NULL or an empty list, progress updates are ignored.}

\item{cleanup}{If TRUE, all progression handlers will be shutdown
at the end regardless of the progression is complete or not.}

\item{delay_terminal}{If TRUE, output and conditions that may end up in
the terminal will delayed.}

\item{delay_stdout}{If TRUE, standard output is captured and relayed
at the end just before any captured conditions are relayed.}

\item{delay_conditions}{A character vector specifying \link[base:conditions]{base::condition}
classes to be captured and relayed at the end after any captured
standard output is relayed.}

\item{interrupts}{Controls whether interrupts should be detected or not.
If TRUE and a interrupt is signaled, progress handlers are asked to
report on the current amount progress when the evaluation was terminated
by the interrupt, e.g. when a user pressed Ctrl-C in an interactive session,
or a batch process was interrupted because it ran out of time.
Note that it's optional for a progress handler to support this and only
some do.}

\item{interval}{(numeric) The minimum time (in seconds) between
successive progression updates from handlers.}

\item{enable}{(logical) If FALSE, then progress is not reported.  The
default is to report progress in interactive mode but not batch mode.
See below for more details.}
}
\value{
Returns the value of the expression.
}
\description{
Report on Progress while Evaluating an R Expression
}
\details{
If you are writing a Shiny app, use the \code{\link[=withProgressShiny]{withProgressShiny()}} function
instead of this one.

If the global progression handler is enabled, it is temporarily disabled
while evaluating the \code{expr} expression.

\strong{IMPORTANT: This function is meant for end users only.  It should not
be used by R packages, which only task is to \emph{signal} progress updates,
not to decide if, when, and how progress should be reported.}

\code{without_progress()} evaluates an expression while ignoring all
progress updates.
}
\section{Progression handler functions}{

Formally, progression handlers are calling handlers that are called
when a \link{progression} condition is signaled.  These handlers are functions
that takes one argument which is the \link{progression} condition.
}

\section{Progress updates in batch mode}{

When running R from the command line, R runs in a non-interactive mode
(\code{interactive()} returns \code{FALSE}).  The default behavior of
\code{with_progress()} is to \emph{not} report on progress in non-interactive mode.
To have progress being reported on also then, set R options
\option{progressr.enable} or environment variable \env{R_PROGRESSR_ENABLE}
to \code{TRUE}.  Alternatively, one can set argument \code{enable=TRUE} when calling
\code{with_progress()}.  For example,

\if{html}{\out{<div class="sourceCode sh">}}\preformatted{$ Rscript -e "library(progressr)" -e "with_progress(slow_sum(1:5))"
}\if{html}{\out{</div>}}

will \emph{not} report on progress, whereas:

\if{html}{\out{<div class="sourceCode sh">}}\preformatted{$ export R_PROGRESSR_ENABLE=TRUE
$ Rscript -e "library(progressr)" -e "with_progress(slow_sum(1:5))"
}\if{html}{\out{</div>}}

will.
}

\examples{
## The slow_sum() example function
slow_sum <- progressr::slow_sum
print(slow_sum)

x <- 1:10

## Without progress updates
y <- slow_sum(x)


## Progress reported via txtProgressBar (default)
handlers("txtprogressbar")  ## default
with_progress({
  y <- slow_sum(x)
})

## Progress reported via tcltk::tkProgressBar
if (capabilities("tcltk") && requireNamespace("tcltk", quietly = TRUE)) {
  handlers("tkprogressbar")
  with_progress({
    y <- slow_sum(x)
  })
}

## Progress reported via progress::progress_bar)
if (requireNamespace("progress", quietly = TRUE)) {
  handlers("progress")
  with_progress({
    y <- slow_sum(x)
  })
}

## Progress reported via txtProgressBar and beepr::beep
if (requireNamespace("beepr", quietly = TRUE)) {
  handlers("beepr", "txtprogressbar")
  with_progress({
    y <- slow_sum(x)
  })
}

## Progress reported via customized utils::txtProgressBar and beepr::beep,
## if available.
handlers(handler_txtprogressbar(style = 3L))
if (requireNamespace("beepr", quietly = TRUE)) {
  handlers("beepr", append = TRUE)
}

with_progress({
  y <- slow_sum(1:30)
})
}
\seealso{
For Shiny apps, use \code{\link[=withProgressShiny]{withProgressShiny()}} instead of this function.
Internally, this function is built around \code{\link[base:conditions]{base::withCallingHandlers()}}.
}