Struct StopOnly 

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

Cancellation without progress: a pulse made from any Stop.

For an application that holds a cancellation token, such as a Stopper or a deadline, and calls a library that takes &dyn Pulse. Every phase the library plans checks the same stop; reports go nowhere, and plans are only validated. An owned stop can be shared with spawned work; a borrowed one serves scoped work and refuses to be shared.

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

// A library that knows nothing about the caller's token.
fn encode(rows: u64, pulse: &dyn Pulse) -> Result<(), StopReason> {
    Stages::new(pulse, &[PhaseSpec::new("rows", 1, Total::Exact(rows))])
        .complete_with(|stages| stages.run(|stage| {
            for _ in 0..rows {
                stage.step(1)?;
            }
            Ok(())
        }))
}

struct Cancelled;
impl Stop for Cancelled {
    fn check(&self) -> Result<(), StopReason> {
        Err(StopReason::Cancelled)
    }
}
assert_eq!(encode(8, &StopOnly::new(Cancelled)), Err(StopReason::Cancelled));
assert_eq!(encode(8, &StopOnly::borrowed(&how_far::Unstoppable)), Ok(()));

Implementations

impl StopOnly<'static>

pub fn new(stop: impl Stop + 'static) -> Self

Own stop; the pulse and its shared views can outlive the caller.

impl<'a> StopOnly<'a>

pub fn borrowed(stop: &'a dyn Stop) -> Self

Borrow stop, without allocating. Pulse::share then fails with PlanError::NotShareable, since the view could outlive the borrow.

Trait Implementations

impl Debug for StopOnly<'_>

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

Formats the value using the given formatter.

impl Pulse for StopOnly<'_>

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

Nobody observes the total, so a revision is accepted and discarded.

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

Split this phase into weighted children, in declared order.

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

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

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 start(&self) -> Result<(), PlanError>

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

impl Report for StopOnly<'_>

fn advance(&self, _: u64)

Add completed finished units.

fn may_report(&self) -> bool

Whether reports have any effect.

impl Stop for StopOnly<'_>

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.