Struct DiagnosticPulse 

pub struct DiagnosticPulse { /* private fields */ }

Measures a library’s checkpoints without changing its signature.

Wrap the PulseTree you would pass to the library, pass &measured instead, and finish the wrapper when the library returns:

use how_far_along::{Outcome, Phase, PulseTree, Total, Unstoppable};
use how_far_really::diagnostics::{DiagnosticPulse, Options};
use how_far_really::profile::{Profiler, StdClock};

let profiler = Profiler::new(StdClock::new(), 256);
let tree = PulseTree::new(Phase::new("encode", Total::Unknown), Unstoppable);
let measured = DiagnosticPulse::new(tree, &profiler);
let observer = measured.observer();
// let result = my_library::encode(&input, &measured);
measured.finish(Outcome::Succeeded)?;
let trace = profiler.snapshot().with_progress(observer.snapshot());
for finding in trace.diagnose(&Options::default()) {
    eprintln!("{finding}");
}

Every phase the library plans gets its own span, tied to its node in the tree. A phase’s span starts at its first check or report; a stage of a sequential split starts when the previous stage finished, and the first stage when the plan was made. So time spent before a stage’s first checkpoint is measured, and a stage that never checks at all still gets a span. Workers that share one phase share its span; give each worker its own Span when one worker’s long silence matters.

A phase that splits hands its time to its children: its own span ends at the split, and a sequential stage then records a SpanKind::Wait span while it coordinates them. A stage is thereby timed from entry to exit, and its children’s work never counts as its own missing checkpoints.

Pulse::share returns an instrumented owned view, so checks made inside code that owns its stop policy, such as a codec context, count toward the stage that handed it out. may_stop and may_report are always true, so libraries that skip calls on no-op pulses still make the calls measured. Creating one turns on Profiler::set_report_timing.

Implementations

impl DiagnosticPulse

pub fn new(tree: PulseTree, profiler: &Profiler) -> Self

Measure everything a library does through tree.

pub fn observer(&self) -> Observer

A read-only view of the measured tree.

pub fn finish(self, outcome: Outcome) -> Result<(), PlanError>

Record the operation’s outcome in the tree, and close the root’s span.

Trait Implementations

impl Complete for DiagnosticPulse

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 DiagnosticPulse

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

Formats the value using the given formatter.

impl Pulse for DiagnosticPulse

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 DiagnosticPulse

fn advance(&self, completed: u64)

Add completed finished units.

fn may_report(&self) -> bool

Whether reports have any effect.

impl Stop for DiagnosticPulse

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.