Struct ProgressRun 

pub struct ProgressRun<'a> { /* private fields */ }

Tracks one progress-producing operation and reports lifecycle events.

ProgressRun 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::{
    NoOpProgressReporter,
    ProgressCounters,
    ProgressRun,
};

let reporter = NoOpProgressReporter;
let mut progress = ProgressRun::new(&reporter, Duration::from_secs(5));

progress.report_started(ProgressCounters::new(Some(2)));

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);
progress.report_finished(finished);

Implementations

impl<'a> ProgressRun<'a>

pub fn new( reporter: &'a dyn ProgressReporter, report_interval: Duration, ) -> Self

Creates a progress run starting at the current instant.

Parameters

• reporter - Reporter receiving progress events.
• report_interval - Minimum delay between due-based running events.

Returns

A progress run whose elapsed time is measured from now.

pub fn from_start( reporter: &'a dyn ProgressReporter, report_interval: Duration, started_at: Instant, ) -> Self

Creates a progress run from an explicit start instant.

Parameters

• reporter - Reporter receiving progress events.
• report_interval - Minimum delay between due-based running events.
• started_at - Monotonic instant representing operation start.

Returns

A progress run using started_at for elapsed-time calculations.

pub fn with_stage(self, stage: ProgressStage) -> Self

Returns a copy configured with stage metadata.

Parameters

• stage - Stage metadata attached to subsequently reported events.

Returns

This progress run with stage recorded.

pub fn without_stage(self) -> Self

Returns a copy with stage metadata removed.

Returns

This progress run without stage metadata.

pub fn report_started(&self, counters: ProgressCounters)

Reports a started lifecycle event.

Parameters

• counters - Initial counters for the operation.

Panics

Propagates panics from the configured reporter.

pub fn report_running(&self, counters: ProgressCounters)

Reports a running lifecycle event immediately.

Parameters

• counters - Current counters for the operation.

Panics

Propagates panics from the configured reporter.

pub fn report_running_if_due(&mut self, counters: ProgressCounters) -> bool

Reports a running lifecycle event if the configured interval has passed.

Parameters

• counters - Current counters for the operation.

Returns

true when a running event was emitted, or false when the next running-event deadline has not been reached.

Panics

Propagates panics from the configured reporter when an event is due.

pub fn report_finished(&self, counters: ProgressCounters)

Reports a finished lifecycle event.

Parameters

• counters - Final counters for a successfully completed operation.

Panics

Propagates panics from the configured reporter.

pub fn report_failed(&self, counters: ProgressCounters)

Reports a failed lifecycle event.

Parameters

• counters - Final or current counters for a failed operation.

Panics

Propagates panics from the configured reporter.

pub fn report_canceled(&self, counters: ProgressCounters)

Reports a canceled lifecycle event.

Parameters

• counters - Final or current counters for a canceled operation.

Panics

Propagates panics from the configured reporter.

pub fn report(&self, phase: ProgressPhase, counters: ProgressCounters)

Reports a lifecycle event with the run’s current elapsed duration.

Parameters

• phase - Lifecycle phase to report.
• counters - Counters carried by the event.

Panics

Propagates panics from the configured reporter.

pub fn report_with_elapsed( &self, phase: ProgressPhase, counters: ProgressCounters, elapsed: Duration, )

Reports a lifecycle event with an explicit elapsed duration.

Parameters

• phase - Lifecycle phase to report.
• counters - Counters carried by the event.
• elapsed - Elapsed duration carried by the event.

Panics

Propagates panics from the configured reporter.

pub fn elapsed(&self) -> Duration

Returns the elapsed duration since this run started.

Returns

The monotonic elapsed duration for this progress run.

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.

pub const fn report_interval(&self) -> Duration

Returns the configured running-event interval.

Returns

The minimum delay between due-based running events.

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.