Struct Stage 

pub struct Stage<'s, 'p> { /* private fields */ }

One active sequential stage, borrowing its plan until result handoff.

Pass &stage as the operation’s Pulse, then use crate::ResultExt::finish_phase or Complete::complete before ?. Completion consumes the handle and updates its plan. Dropping it without completion records Outcome::Abandoned and resolves pending work as Outcome::NotRun. Shared views have no completion rights.

A second stage cannot begin while the first is live:

use how_far::{prelude::*, NoPulse, PhaseSpec, Stages, Total};
let (mut stages, [a, b]) = Stages::define(&NoPulse, [
    PhaseSpec::new("a", 1, Total::Unknown),
    PhaseSpec::new("b", 1, Total::Unknown),
]);
let first = stages.begin(a);
let second = stages.begin(b);
first.complete(Ok::<_, how_far::StopReason>(())).unwrap();

Implementations

impl Stage<'_, '_>

pub fn fork<const N: usize>(&self, parts: [PhaseSpec<'_>; N]) -> [Child<'_>; N]

Start independently owned branches within this stage.

This declares Execution::ForkJoin and starts each branch; it does not schedule work. Move the handles into scoped threads, Rayon work, or borrowed async futures. Each branch can use different data and return a different type, or declare a nested Stages sequence.

Hand each result to its branch, join all workers, then hand the combined result to this stage. A failed branch does not automatically cancel its siblings. Every returned branch is active: dropping one unfinished records Outcome::Abandoned, not optional skipped work. Rejected plans retain cancellation in every branch and record an issue.

The parent cannot be completed while a branch still borrows it:

use how_far::{prelude::*, NoPulse, PhaseSpec, Stages, Total, Outcome};
let (mut stages, [work]) = Stages::define(&NoPulse, [
    PhaseSpec::new("work", 1, Total::Unknown),
]);
let work = stages.begin(work);
let [branch] = work.fork([PhaseSpec::new("branch", 1, Total::Unknown)]);
work.complete_as(Outcome::Succeeded);
branch.complete_as(Outcome::Succeeded);

Trait Implementations

impl Complete for Stage<'_, '_>

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 Debug for Stage<'_, '_>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Drop for Stage<'_, '_>

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.

impl Pulse for Stage<'_, '_>

fn record_issue(&self, error: PlanError)

Record a reporting-protocol problem for optional diagnostics. This never changes cancellation or the operation’s return value. Ordinary sinks may ignore it; diagnostic wrappers retain bounded evidence.

fn split( &self, execution: Execution, parts: &[PhaseSpec<'_>], ) -> Result<Vec<Child<'_>>, PlanError>

Split this phase into weighted children, in declared order.

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

Mark this phase running, without counting or ending planning. Implementations without lifecycle observations may ignore this.

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

Revise a leaf’s denominator without changing completed units or weights. Unsupported implementations return an error instead of losing the update.

fn share(&self) -> Result<SharedPulse, PlanError>

Share all pulse capabilities with owned work, but never completion rights.

impl Report for Stage<'_, '_>

fn advance(&self, completed: u64)

Add completed finished units.

fn may_report(&self) -> bool

Whether reports have any effect.

impl Stop for Stage<'_, '_>

fn check(&self) -> Result<(), StopReason>

Check if the operation should stop.

fn may_stop(&self) -> bool

Returns true if this stop can ever signal a stop.

fn should_stop(&self) -> bool

Returns true if the operation should stop.