Struct Progress 

pub struct Progress {
    phase: Mutex<Option<Phase>>,
    position: AtomicU64,
}

A named unit of long-running work, reported while it runs.

The publisher names a phase, optionally counts items through it, and ends it. A reader takes whatever phase is current rather than waiting for one to finish, so a phase that counts nothing still reports how long it has been running. Only the position is lock-free, which is what lets a scan count every row.

Fields

phase: Mutex<Option<Phase>>

The phase in flight, absent before the first begins and after the last ends.

position: AtomicU64

Items the phase in flight has finished.

The reset happens under the phase lock, so a report never pairs one phase’s name with another’s count. The increment takes no lock, so a report may trail the true count by a few items.

Implementations

impl Progress

pub fn begin(&self, step: &'static str)

Names the phase now in flight.

Any pass and any count the previous phase left are cleared, so a step that counts nothing cannot inherit a number from the step before it. A name reaches a service manager that delimits its own protocol by newline, so it must not contain one.

impl Progress

pub fn enter(&self, pass: &'static str)

Names a narrower part of the phase in flight.

The count resets with the pass, because the items a pass walks are its own. A call arriving before any phase began is ignored.

impl Progress

pub fn expect_total(&self, total: u64)

Records how many items the phase in flight expects to finish.

Only a step that can count its work exactly says so, since a report shows the position against this total as if it were reached. Every other step reports a bare position rather than a proportion of an estimate.

impl Progress

pub fn advance(&self)

Counts one more item finished by the phase in flight.

The increment takes no lock, so a scan can afford to call it per row. A phase change resets the count, so no report carries one phase’s position into another.

impl Progress

pub fn end(&self)

Ends the phase in flight, leaving nothing to report.

A reader between the last phase and the next sees no phase at all, rather than a finished one whose elapsed time keeps climbing.

impl Progress

pub fn report(&self) -> Option<SmallString<[u8; 128]>>

Formats the phase in flight, or nothing when there is none.

The name, the position and the elapsed time are read under one lock, so they describe the same phase. A step that named an expected total reports its position against that total; every other one reports a bare position, or only its elapsed time when it counts nothing.

impl Progress

fn lock(&self) -> MutexGuard<'_, Option<Phase>>

Takes the phase lock, adopting a poisoned one.

A poisoned lock means a publisher panicked mid-update, which leaves the phase merely stale. Refusing to report at all would be the worse failure.

Trait Implementations

impl Default for Progress

fn default() -> Self

Returns the “default value” for a type.