progress_begin: Begin a progress node

In rtemis.core: Core Utilities for the 'rtemis' Ecosystem

Begin a progress node

Description

Creates a progress handle, pushes it on the active-progress stack (nesting under the current innermost handle, if any), emits a status = "start" sink event when a message sink is set (see set_msg_sink()), and renders the console status line otherwise.

Usage

progress_begin(
  total,
  label = "Progress",
  kind = "progress",
  id = NULL,
  parent_id = NULL,
  verbosity = NULL,
  package = NULL,
  output_type = NULL
)

Arguments

total	Integer: Total number of steps, or NA for indeterminate progress. Must be non-negative.
label	Character: Display label for this progress node.
kind	Character: Node kind forwarded in the sink envelope (e.g. "tune", "grid_cell").
id	Character or NULL: Node id for the sink envelope. Auto-generated ("pb1", "pb2", ...) when NULL; pass an execution-graph node id to correlate progress with other node events.
parent_id	Character or NULL: Parent id reported in the sink envelope when this handle is the outermost one on the stack. Lets a caller graft its progress nodes onto an enclosing execution graph (e.g. rtemis passes the node its loop is running inside), so a consumer reading both streams reconstructs one tree. Ignored when the handle nests inside another handle, whose id is then the parent.
verbosity	Integer or NULL: Overrides get_verbosity() when supplied. Gates only the console renderer, never sink events.
package	Character or NULL: Package name for verbosity override lookup (e.g. "rtemis").
output_type	Character or NULL: "ansi", "html", or "plain"; resolved via get_output_type() when NULL ("ansi" in interactive sessions, "plain" otherwise). Only "ansi" animates.

Details

The console renderer writes a single status line rewritten in place, with a color-pulsing spinner and a breadcrumb of all active levels, e.g. ⁠Outer resamples 2/5 > Tuning 7/30 ETA 0:41⁠. Each level shows the step currently in flight (1-based), so a loop counts 1/n through n/n; the ETA is computed from completed steps. Non-"ansi" output gets one begin line and one completion line instead (no line rewriting). Two options control rendering:

• rtemis.progress_throttle: Minimum seconds between redraws and between sink "update" events (default 0.1). Begin/end events always fire; set to 0 to emit every tick.

• rtemis.progress_spinner: Spinner design - one of "dots" (braille dots, default), "dot" (static dot, color-only animation), or "blocks" (quadrant blocks). All designs share the palette color pulse (light_orange to red).

Sink events fire regardless of verbosity; verbosity gates only the console renderer.

Known limitation: output written directly to stdout by code running inside a progress loop (cat(), print(), verbose third-party routines) is not intercepted and will collide with the status line. Output through msg() and the other rtemis writers clears the line automatically, and progress_lapply() additionally clears it for any message()/warning() condition raised by user code. For raw stdout writes, call progress_clear() first or silence the routine (capture.output(), verbose = 0).

Value

An rtemis_progress handle (environment), invisibly. Pass it to progress_update() and progress_end().

Author(s)

EDG

See Also

Other progress: progress_clear(), progress_end(), progress_lapply(), progress_update()

Examples

h <- progress_begin(3L, label = "Fitting", output_type = "plain")
progress_update(h)
progress_end(h)

rtemis.core documentation built on Sept. 20, 2026, 9:06 a.m.