Struct Phase 

pub struct Phase { /* private fields */ }

The owner of one phase: its plan, its counter, and its outcome.

Give workers cloned Reporters, not the owner. Join workers and flush their batches before finish. Dropping an unfinished owner records Outcome::Abandoned. Each attempt uses a new phase, so a stale reporter from an earlier attempt can never change a new one.

Phases are owned and 'static: move children into spawned threads or tasks, or wrap any phase in a PulseTree to hand it to a library as &dyn Pulse.

Implementations

impl Phase

pub fn new(name: impl Into<String>, total: Total) -> Self

Start a job: a pending root leaf that counts items.

pub fn reporter(&self) -> Reporter

A cheap, cloneable counter for this phase’s workers.

Taking one ends planning: the phase can no longer split. A branch’s reporter ignores reports, so work is never counted twice.

pub fn observer(&self) -> Observer

Observe this subtree from any thread.

pub fn id(&self) -> NodeId

This phase’s identity within its job.

pub fn start(&mut self) -> Result<(), PlanError>

Mark the phase running before its first report, for work that starts long before it can count anything. A report starts a leaf on its own.

pub fn set_units(&mut self, units: impl Into<String>) -> Result<(), PlanError>

Name the counted unit, before planning or counting begins.

pub fn set_execution(&mut self, execution: Execution) -> Result<(), PlanError>

Declare how this phase’s work is scheduled, before planning or counting.

pub fn set_total(&mut self, total: Total) -> Result<(), PlanError>

Revise a leaf’s total while it runs.

The most recent revisions are kept in Snapshot::total_revisions. A fraction can go down after a revision; smoothing is the display’s job.

pub fn split<const N: usize>( &mut self, execution: Execution, parts: [PhaseSpec<'_>; N], ) -> Result<[Phase; N], PlanError>

Split an unused leaf into weighted children, returned as an array.

use how_far_along::{Execution, Phase, PhaseSpec, Total};
let mut job = Phase::new("encode", Total::Unknown);
let [before, middle, after] = job.split(Execution::Sequence, [
    PhaseSpec::new("prepare", 35, Total::Exact(1)),
    PhaseSpec::new("parallel", 30, Total::Unknown),
    PhaseSpec::new("write", 35, Total::Exact(1)),
])?;

pub fn split_vec( &mut self, execution: Execution, parts: &[PhaseSpec<'_>], ) -> Result<Vec<Phase>, PlanError>

Split an unused leaf into a runtime-sized list of children.

A split is final: a running phase cannot gain siblings later. Keep discovery in an Unknown-total leaf until the full list is known.

pub fn finish(&mut self) -> Result<(), PlanError>

Record success after every worker joins and every child finishes. Failed child attempts may be retained under a recovered successful parent.

pub fn finish_with(&mut self, outcome: Outcome) -> Result<(), PlanError>

Record a terminal outcome. The subtree’s snapshot stops changing.

Every child must have finished first. Their outcomes need not match the parent’s: the library decides whether recovery succeeded. A failed call changes nothing, so the owner can fix the cause and finish again. Cancelled records how the work ended; it does not request a stop.

Trait Implementations

impl Complete for Phase

fn complete_as(self, outcome: Outcome)

Record an explicitly chosen outcome, resolving unfinished observations. Join workers before calling this. Started but uncompleted children are abandoned; untouched children are skipped on success, not run on error.

fn complete<T, E>(self, result: Result<T, E>) -> Result<T, E>

where E: AsStopReason,

Classify the error with AsStopReason, record completion, and return the original result.

fn complete_classified<T, E>( self, result: Result<T, E>, is_stop: impl FnOnce(&E) -> bool, ) -> Result<T, E>

Complete with an explicit classifier, for a foreign error type that Rust’s orphan rules keep from implementing AsStopReason.

fn complete_with<T, E>( self, body: impl FnOnce(&mut Self) -> Result<T, E>, ) -> Result<T, E>

where E: AsStopReason,

Run a multi-step body with this owner, then complete the owner with the body’s result and return that result unchanged.

fn complete_with_classified<T, E>( self, is_stop: impl FnOnce(&E) -> bool, body: impl FnOnce(&mut Self) -> Result<T, E>, ) -> Result<T, E>

complete_with with an explicit classifier, for a foreign error type that cannot implement AsStopReason, such as an error wrapped with its source location.

impl Drop for Phase

fn drop(&mut self)

Executes the destructor for this type.

fn pin_drop(self: Pin<&mut Self>)

🔬This is a nightly-only experimental API. (pin_ergonomics)

Execute the destructor for this type, but different to Drop::drop, it requires self to be pinned.