Trait Complete 

pub trait Complete: Sized {
    // Required method
    fn complete_as(self, outcome: Outcome);

    // Provided methods
    fn complete<T, E>(self, result: Result<T, E>) -> Result<T, E>
       where E: AsStopReason { ... }
    fn complete_classified<T, E>(
        self,
        result: Result<T, E>,
        is_stop: impl FnOnce(&E) -> bool,
    ) -> Result<T, E> { ... }
    fn complete_with<T, E>(
        self,
        body: impl FnOnce(&mut Self) -> Result<T, E>,
    ) -> Result<T, E>
       where E: AsStopReason { ... }
    fn complete_with_classified<T, E>(
        self,
        is_stop: impl FnOnce(&E) -> bool,
        body: impl FnOnce(&mut Self) -> Result<T, E>,
    ) -> Result<T, E> { ... }
}

An owner that can record a result without changing the operation’s result. Reporting problems are diagnostic evidence, never replacement work errors.

Required Methods

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.

Provided Methods

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.

Forgetting AsStopReason for a library’s error is reported as that trait being unimplemented, not as a type mismatch elsewhere:

use how_far::{prelude::*, PhaseSpec, Stages, StopReason, Total};

enum Error {
    Stopped(StopReason),
}
impl From<StopReason> for Error {
    fn from(reason: StopReason) -> Self {
        Self::Stopped(reason)
    }
}
fn encode(pulse: &dyn Pulse) -> Result<(), Error> {
    Stages::new(pulse, &[PhaseSpec::new("work", 1, Total::Unknown)])
        .complete_with(|stages| stages.run(|stage| Ok(stage.check()?)))
}

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.

An early ? inside body still reaches the handoff, which a ? placed before a separate complete call would bypass. A panic in body drops the owner, recording abandonment as usual.

use how_far::{prelude::*, PhaseSpec, Stages, StopReason, Total};

fn convert(pulse: &dyn Pulse) -> Result<u64, StopReason> {
    Stages::new(pulse, &[
        PhaseSpec::new("decode", 1, Total::Exact(1)),
        PhaseSpec::new("sharpen", 1, Total::Exact(1)),
    ])
    .complete_with(|stages| {
        let pixels = stages.run(|stage| stage.step(1).map(|()| 7))?;
        // An untouched "sharpen" stage is resolved as Skipped.
        Ok(pixels)
    })
}
assert_eq!(convert(&how_far::NoPulse), Ok(7));

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.

Dyn Compatibility

This trait is not dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety".

Implementors

impl Complete for Child<'_>

impl Complete for Phases<'_>

impl Complete for Stage<'_, '_>

impl Complete for Stages<'_>