pub struct Progress<'a> { /* private fields */ }Expand description
Tracks one logical progress-producing operation and reports events.
A Progress instance is scoped to one logical operation. It owns no domain
state; callers keep their own counters and convert them into
ProgressCounter values when reporting. The run manages elapsed time,
periodic running-event throttling, optional stage metadata, a metric schema,
and forwarding immutable events to one reporter.
§Examples
use std::time::Duration;
use qubit_progress::{
Progress,
ProgressMetric,
ProgressSchema,
WriterProgressReporter,
};
let schema = ProgressSchema::new(vec![ProgressMetric::new("entries", "Entries")]);
let reporter = WriterProgressReporter::from_writer(std::io::stdout());
let mut progress = Progress::new(&reporter, Duration::from_secs(5), schema);
let started = progress.report_started(|event| event.counter("entries", |c| c.total(2)));
assert!(started.elapsed().is_zero());
let _reported = progress.report_running_if_due(|event| {
event.counter("entries", |counter| counter.total(2).completed(1).active(1))
});
let finished = progress.report_finished(|event| {
event.counter("entries", |counter| counter.total(2).completed(2).succeeded(2))
});
assert!(finished.elapsed() >= started.elapsed());Implementations§
Source§impl<'a> Progress<'a>
impl<'a> Progress<'a>
Sourcepub fn new(
reporter: &'a dyn ProgressReporter,
report_interval: Duration,
schema: ProgressSchema,
) -> Self
pub fn new( reporter: &'a dyn ProgressReporter, report_interval: Duration, schema: ProgressSchema, ) -> Self
Sourcepub fn single_metric(
reporter: &'a dyn ProgressReporter,
report_interval: Duration,
metric_id: &str,
metric_name: &str,
) -> Self
pub fn single_metric( reporter: &'a dyn ProgressReporter, report_interval: Duration, metric_id: &str, metric_name: &str, ) -> Self
Creates a single-metric progress run starting at the current instant.
§Parameters
reporter- Reporter receiving progress events.report_interval- Minimum delay between due-based running events.metric_id- Stable metric identifier.metric_name- Human-readable metric name.
§Returns
A progress run with a schema containing one metric.
Sourcepub fn with_stage(self, stage: ProgressStage) -> Self
pub fn with_stage(self, stage: ProgressStage) -> Self
Sourcepub fn without_stage(self) -> Self
pub fn without_stage(self) -> Self
Sourcepub fn event_builder(&self) -> ProgressEventBuilder
pub fn event_builder(&self) -> ProgressEventBuilder
Creates an event builder preconfigured with this run’s schema, stage, and elapsed time.
§Returns
A progress event builder for this run.
Sourcepub fn report_started<F>(&self, configure: F) -> ProgressEvent
pub fn report_started<F>(&self, configure: F) -> ProgressEvent
Sourcepub fn report_running<F>(&mut self, configure: F) -> ProgressEvent
pub fn report_running<F>(&mut self, configure: F) -> ProgressEvent
Sourcepub fn report_running_if_due<F>(
&mut self,
configure: F,
) -> Option<ProgressEvent>
pub fn report_running_if_due<F>( &mut self, configure: F, ) -> Option<ProgressEvent>
Reports a running lifecycle event if the configured interval has passed.
§Parameters
configure- Closure that adds counters or stage overrides when an event is due.
§Returns
Some(event) when a running event was emitted, or None when the next
running-event deadline has not been reached.
This method does not call configure unless an event is due. It returns
immediately when not due, and when due it synchronously calls the
configured reporter. Any blocking behavior therefore comes from the
reporter implementation.
§Panics
Propagates panics from the configured reporter when an event is due.
Sourcepub fn report_finished<F>(&self, configure: F) -> ProgressEvent
pub fn report_finished<F>(&self, configure: F) -> ProgressEvent
Sourcepub fn report_failed<F>(&self, configure: F) -> ProgressEvent
pub fn report_failed<F>(&self, configure: F) -> ProgressEvent
Sourcepub fn report_canceled<F>(&self, configure: F) -> ProgressEvent
pub fn report_canceled<F>(&self, configure: F) -> ProgressEvent
Sourcepub fn spawn_running_reporter<'scope, 'env, F>(
&self,
scope: &'scope Scope<'scope, 'env>,
snapshot: F,
) -> RunningProgressGuard<'scope>
pub fn spawn_running_reporter<'scope, 'env, F>( &self, scope: &'scope Scope<'scope, 'env>, snapshot: F, ) -> RunningProgressGuard<'scope>
Spawns a scoped background reporter for periodic running events.
The background reporter shares this progress run’s reporter, schema,
start time, interval, and stage metadata. Worker threads should update
their own domain state first, then call
RunningProgressPointHandle::report
on the handle returned by the guard. The guard must be stopped and
joined before the thread scope exits.
§Parameters
scope- Thread scope that owns the background reporter thread.snapshot- Closure that builds fresh counters from caller-owned domain state whenever a running event may be due.
§Returns
A guard that owns the reporter thread and can create worker-side point handles.
§Panics
Panics raised by the reporter thread are propagated by
RunningProgressGuard::stop_and_join.
Sourcepub const fn schema(&self) -> &ProgressSchema
pub const fn schema(&self) -> &ProgressSchema
Returns the metric schema for this progress run.
§Returns
The schema cloned into every event emitted by this run.
Sourcepub fn elapsed(&self) -> Duration
pub fn elapsed(&self) -> Duration
Returns the elapsed duration since this run started.
§Returns
The monotonic elapsed duration for this progress run.
Sourcepub const fn started_at(&self) -> Instant
pub const fn started_at(&self) -> Instant
Returns the start instant for this run.
§Returns
The monotonic instant used as this run’s start time.
Sourcepub const fn report_interval(&self) -> Duration
pub const fn report_interval(&self) -> Duration
Returns the configured running-event interval.
§Returns
The minimum delay between due-based running events.
Sourcepub const fn stage(&self) -> Option<&ProgressStage>
pub const fn stage(&self) -> Option<&ProgressStage>
Returns the optional stage metadata attached to events.
§Returns
Some(stage) when stage metadata is configured, otherwise None.