with_pbar.Rd

% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/progress.R
\name{with_pbar}
\alias{with_pbar}
\title{Track progress while evaluating an R expression}
\usage{
with_pbar(
  expr,
  handlers = progressr::handlers(),
  cleanup = TRUE,
  delay_terminal = NULL,
  delay_stdout = NULL,
  delay_conditions = NULL,
  interrupts = getOption("progressr.interrupts", TRUE),
  interval = NULL,
  enable = NULL
)
}
\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{
the result of the evaluated code
}
\description{
Track progress while evaluating an R expression. This is a wrapper around
\code{\link[progressr:with_progress]{progressr::with_progress()}}. \pkg{progressr} is useful because it handles
progress reporting in parallel contexts. However, it is worth noting that
Giotto does not adhere to \pkg{progressr}'s guideline that \code{with_progress()}
should not be used within packages.
The default behavior of displaying progress is more convenient for end
users of packages with many functions. This implementation may shift over
time.
}
\examples{
a <- function(x = 10) {
    with_pbar({
        pb <- pbar(x)
        for (i in seq_len(x)) {
            Sys.sleep(0.1)
            pb()
        }
    })
}

a()
}
\seealso{
\code{\link[=pbar]{pbar()}}
}