pub struct Progress<'a> { /* private fields */ }Expand description
Tracks one progress-producing operation and reports lifecycle events.
Progress owns no operation-specific counters. Callers keep their own
domain state and pass freshly built ProgressCounters when reporting.
The run only manages elapsed time, periodic running-event throttling,
optional stage metadata, and forwarding immutable events to a reporter.
§Examples
use std::time::Duration;
use qubit_progress::{
ProgressCounters,
Progress,
WriterProgressReporter,
};
let reporter = WriterProgressReporter::from_writer(std::io::stdout());
let mut progress = Progress::new(&reporter, Duration::from_secs(5));
let started = progress.report_started(ProgressCounters::new(Some(2)));
assert!(started.elapsed().is_zero());
let running = ProgressCounters::new(Some(2))
.with_completed_count(1)
.with_active_count(1);
let _reported = progress.report_running_if_due(running);
let finished = ProgressCounters::new(Some(2))
.with_completed_count(2)
.with_succeeded_count(2);
let finished_event = progress.report_finished(finished);
assert!(finished_event.elapsed() >= started.elapsed());Implementations§
Source§impl<'a> Progress<'a>
impl<'a> Progress<'a>
Sourcepub fn new(
reporter: &'a dyn ProgressReporter,
report_interval: Duration,
) -> Self
pub fn new( reporter: &'a dyn ProgressReporter, report_interval: Duration, ) -> Self
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 report_started(&self, counters: ProgressCounters) -> ProgressEvent
pub fn report_started(&self, counters: ProgressCounters) -> ProgressEvent
Sourcepub fn report_running(&mut self, counters: ProgressCounters) -> ProgressEvent
pub fn report_running(&mut self, counters: ProgressCounters) -> ProgressEvent
Sourcepub fn report_running_if_due(
&mut self,
counters: ProgressCounters,
) -> Option<ProgressEvent>
pub fn report_running_if_due( &mut self, counters: ProgressCounters, ) -> Option<ProgressEvent>
Reports a running lifecycle event if the configured interval has passed.
§Parameters
counters- Current counters for the operation.
§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 block waiting for the next deadline. 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(&self, counters: ProgressCounters) -> ProgressEvent
pub fn report_finished(&self, counters: ProgressCounters) -> ProgressEvent
Sourcepub fn report_failed(&self, counters: ProgressCounters) -> ProgressEvent
pub fn report_failed(&self, counters: ProgressCounters) -> ProgressEvent
Sourcepub fn report_canceled(&self, counters: ProgressCounters) -> ProgressEvent
pub fn report_canceled(&self, counters: ProgressCounters) -> 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, 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 background reporter thread and can create worker-side point handles.
§Panics
Panics raised by the reporter thread are propagated by
RunningProgressGuard::stop_and_join.
§Examples
use std::{
sync::{
Arc,
atomic::{
AtomicUsize,
Ordering,
},
},
thread,
time::Duration,
};
use qubit_progress::{
NoOpProgressReporter,
Progress,
ProgressCounters,
};
let reporter = NoOpProgressReporter;
let completed = Arc::new(AtomicUsize::new(0));
let progress = Progress::new(&reporter, Duration::ZERO);
thread::scope(|scope| {
let loop_completed = Arc::clone(&completed);
let running = progress.spawn_running_reporter(scope, move || {
ProgressCounters::new(Some(3))
.with_completed_count(loop_completed.load(Ordering::Acquire))
});
let point = running.point_handle();
let mut handles = Vec::new();
for _ in 0..3 {
let c = Arc::clone(&completed);
let p = point.clone();
handles.push(scope.spawn(move || {
c.fetch_add(1, Ordering::AcqRel);
assert!(p.report());
}));
}
for h in handles {
h.join().unwrap();
}
running.stop_and_join();
});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.