Struct Progress

Source

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));

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§

Source §

impl<'a> Progress<'a>

Source

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.

Source

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.

Source

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.

Source

pub fn without_stage(self) -> Self

Returns a copy with stage metadata removed.

§Returns

This progress run without stage metadata.

Source

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.

Source

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.

Source

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.

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.