Crate qubit_progress

Expand description

Immutable, lifecycle-safe progress reporting.

A Progress operation owns its metric state, timing and reporter. Callers configure stable metadata with Metric and update dynamic counts through cloneable MetricHandle values. Every emitted Event is complete.

§Benchmark interpretation

Run cargo bench --bench progress_bench -- --noplot to compare complete event delivery, scheduling paths, and concurrent MetricHandle updates with a mutex-protected counter baseline. The contention benchmarks use Criterion’s batched iteration so setup allocation is excluded from the measured update path; worker thread creation and joining remain part of the workload. Throughput is reported in elements per second for 2,048 updates per worker across 1, 2, 4, 8, 16, 32, and 64 workers.

These measurements are workload- and hardware-dependent. The CAS-based metric path is not assumed to beat a mutex at every worker count; measure on target hardware before changing the synchronization strategy or adding backoff, yielding, or sharded counters.

§Examples

use qubit_progress::{Metric, Progress, TextReporter};

let reporter = std::sync::Arc::new(TextReporter::new(Vec::new()));
let progress = Progress::builder_arc(reporter)
    .metric(Metric::new("tasks", "Tasks").total(1))
    .start()?;
let tasks = progress.metric("tasks").expect("configured metric must exist");
tasks.start(1)?;
tasks.succeed(1)?;
progress.finish()?;

Re-exports§

pub use reporter::NoopReporter;
pub use reporter::Reporter;
pub use reporter::TextReporter;

Modules§

reporter: Reporter abstraction and built-in sinks.

Structs§

AutoReporter: Handle controlling one scoped automatic reporter.
AutoReporterStatus: Cloneable status exposed while an automatic reporter is active.
DeliveryError: Failure while delivering one complete Event to a reporter.
Event: Complete immutable snapshot delivered to one reporter call.
Metric: Stable metadata for one metric in a progress operation.
MetricDelta: One atomic batch of additive metric lifecycle changes.
MetricHandle: Cloneable capability for one live metric owned by a progress operation.
MetricSnapshot: Immutable complete state for one metric in an emitted event.
OperationAttributes: String key-value attributes shared by every event in one operation.
Progress: One started progress operation.
ProgressBuilder: Configures one Progress operation before it starts.
ProgressNotifier: Notification handle that coalesces state changes without claiming delivery.
ReporterError: Reporter failure that preserves its original error chain.
Stage: Human-readable sub-stage attached to subsequently emitted events.
TerminalError: Terminal emission failure paired with elapsed operation time.
WorkerPanic: An opaque panic payload captured from an automatic reporter worker.

Enums§

AutoReporterError: Failure returned by crate::AutoReporter::stop.
CompletionError: Metric state that prevents checked successful completion.
ConfigurationError: Invalid fixed metadata supplied to a progress operation.
EmissionError: Failure while emitting a Running or terminal event.
FinishError: Failure from checked finish after the operation has been consumed.
MetricError: Failure while reading or mutating one stateful metric.
OperationLifecycle: Lifecycle state visible to metric transition errors.
Phase: Lifecycle phase of one immutable progress event.
RecoverableFinishError: Failure from checked finish while preserving a reusable progress operation.
StartError: Failure before a usable progress operation can be returned.