Struct Stages 

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

Sequential work returning the library’s ordinary Result<T, E>.

Start with Stages::define: bind its reservations to variables, use Stages::begin to obtain each active handle, and call your operation with &stage. For repeated work over a runtime-sized list, Stages::new and Stages::begin_next provide the same handle and result handoff.

Implement AsStopReason for your error to recognize cancellation. From<StopReason> supports ? at checks; no planning-error conversion is required. For explicitly fallible planning use crate::TryStages.

Pass the final result to complete (or ResultExt::finish_phase) to resolve untouched stages. Use Stages::begin for direct function calls and hand each result to crate::ResultExt::finish_phase before applying ?. Drop alone records abandonment. Recovery belongs within the operation that owns a stage, using separate child owners for individual attempts.

Implementations

impl<'a> Stages<'a>

pub fn new(parent: &'a dyn Pulse, parts: &[PhaseSpec<'_>]) -> Self

Declare a runtime-sized sequence for Stages::begin_next or Stages::run.

For a fixed set of distinct operations, Stages::define also gives you reservations to bind to variables. Rejected observations retain cancellation through fallback children and cannot fail the work.

pub fn define<const N: usize>( parent: &'a dyn Pulse, parts: [PhaseSpec<'_>; N], ) -> (Self, [StageKey; N])

Declare a sequence and bind its reservations to variables.

Destructure the returned array, then pass each key to Stages::begin in declaration order. Keys belong to this particular plan, even when another plan has identical specifications. Moving the plan is allowed. Dropping a key does not abandon its pending stage: the plan retains completion authority until the stage begins or the plan completes.

Labels are for observers only; beginning a stage never compares strings. One shared identity allocation belongs to each nonempty definition.

pub fn begin(&mut self, key: StageKey) -> Stage<'_, 'a>

Begin the next stage using its reservation from Stages::define.

Hand the operation’s result to crate::ResultExt::finish_phase before applying ?. Failed or cancelled handoffs immediately mark remaining stages Outcome::NotRun. Complete the plan with its final result to resolve untouched optional work.

A key from another plan, out of order, or already used records PlanError::StageMismatch and returns a cancellation-only stage without consuming the next declaration. After failure or exhaustion, work also retains cancellation and the protocol issue is recorded.

Only one active stage can borrow the plan. Join workers before handing over that stage’s result. Dropping it unfinished records abandonment and prevents the remaining sequence from earning progress.

pub fn begin_next(&mut self) -> Stage<'_, 'a>

Begin the next stage in a runtime-sized sequence.

Use with Stages::new when a loop repeats the same operation over a slice. The handle and result handoff are the same as Stages::begin, but no key is checked. Exhaustion records PlanError::NoMoreStages and returns a cancellation-only stage.

pub fn run<T, E>( &mut self, work: impl FnOnce(&dyn Pulse) -> Result<T, E>, ) -> Result<T, E>

where E: AsStopReason,

Run the next stage, preserving the original result and error identity. After a stage error, later declared stages become NotRun. Calling again is diagnosed and runs against a cancellation-only view of the parent.

pub fn run_classified<T, E>( &mut self, is_stop: impl FnOnce(&E) -> bool, work: impl FnOnce(&dyn Pulse) -> Result<T, E>, ) -> Result<T, E>

Run with an explicit classifier for foreign error wrappers or a local classification policy, returning the work’s original Result unchanged.

pub fn skip(&mut self)

Explicitly mark the next phase unnecessary, making that decision visible now.

Trait Implementations

impl Complete for Stages<'_>

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.