Trait Pulse 

pub trait Pulse: Stop + Report {
    // Required method
    fn split(
        &self,
        execution: Execution,
        parts: &[PhaseSpec<'_>],
    ) -> Result<Vec<Child<'_>>, PlanError>;

    // Provided methods
    fn record_issue(&self, _error: PlanError) { ... }
    fn start(&self) -> Result<(), PlanError> { ... }
    fn set_total(&self, _total: Total) -> Result<(), PlanError> { ... }
    fn share(&self) -> Result<SharedPulse, PlanError> { ... }
}

Cancellation, completed work, and nested phase planning, in one value.

A library accepts &dyn Pulse and uses it three ways:

• check() asks whether to stop. It is the cheapest call, unless the caller made it run code of its own, as a checkpoint callback does; check once per row, block or tile, not per byte.
• advance(n) counts finished units; ProgressExt::step counts and then checks.
• split declares weighted children. The library owns the returned Child handles and finishes each one. It never finishes the pulse it was given; that pulse belongs to its caller.

Splitting and counting are exclusive: a phase either counts its own units (a leaf) or delegates to children (a branch). Plan before the first report.

Wrappers that add measurement or forwarding implement this trait, so it is open. Methods added in later compatible releases will have default bodies.

Implementing

A tracker or checkpoint callback adapter from how-far-along usually suffices. Implementations must keep these rules:

• check and advance may run on many threads at once, and advance must not block. may_stop and may_report return false only when that can never change.
• split starts with PhaseSpec::validate_split. It fails with PlanError::AlreadyInUse if this phase already counted work or split, and otherwise returns one Child::new per part, in order, each checking and counting like any pulse. Children from Child::inert cannot be stopped or observed, so they suit only parts nobody watches.
• share returns an owned view that checks the same stop, counts into the same phase and plans its children, or fails with PlanError::NotShareable; it never silently drops cancellation.
• ChildPulse::finish fails with PlanError::UnfinishedChildren while a descendant is unfinished. Completed failed attempts may belong to a successful parent. A dropped unfinished child records Abandoned.

Required Methods

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

Split this phase into weighted children, in declared order.

Returns exactly one Child per part. The caller owns them: pass &child to code that does the child’s work, then finish the child once that work has joined. Fails if the parts are invalid, if this phase already counted work or split, or if the pulse cannot plan children.

Provided Methods

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.

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.

The SharedPulse is 'static, cloneable and thread-safe, and works wherever a Stop or Report is expected: give it to a codec context that stores impl Stop + 'static, a spawned thread, or an async task. Join such work before finishing the original owner. Unsupported ownership is explicit; this method never silently replaces cancellation with a no-op.

Implementations

impl<'a> dyn Pulse + 'a

pub fn paced(&self, every: u64) -> Paced<'_>

Checkpoints that reach this pulse once every every units; see Paced.

impl dyn Pulse + '_

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

Best-effort planning. If the sink rejects the plan, returns one untracked child per part, all retaining this pulse’s stop/checkpoint policy.

Dyn Compatibility

This trait is dyn compatible.

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

Implementations on Foreign Types

impl<P: Pulse + ?Sized> Pulse for &P

fn record_issue(&self, error: PlanError)

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

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

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

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

impl<P: Pulse + ?Sized> Pulse for &mut P

fn record_issue(&self, error: PlanError)

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

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

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

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

impl<P: Pulse + ?Sized> Pulse for Arc<P>

fn record_issue(&self, error: PlanError)

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

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

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

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

impl<P: Pulse + ?Sized> Pulse for Box<P>

fn record_issue(&self, error: PlanError)

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

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

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

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

Implementors

impl Pulse for Child<'_>

impl Pulse for Inert

impl Pulse for SharedPulse

impl Pulse for Stage<'_, '_>

impl Pulse for StopOnly<'_>

impl Pulse for WithStop<'_>