Struct Paced 

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

Counts completed work locally and reaches its pulse once every every units: it reports the units counted so far, then checks for cancellation.

Reaching a live tree costs a few nanoseconds per checkpoint; a step that does not reach it is a subtraction and a branch. Choose every so that the work between checkpoints takes at least a microsecond, and no longer than the cancellation latency you need. A pulse that can neither stop nor report, such as NoPulse, is never reached, and in a loop its steps compile to nothing.

Make one per worker, from the &dyn Pulse the work was given:

use how_far::{Pulse, StopReason};

fn defilter(rows: &mut [Vec<u8>], pulse: &dyn Pulse) -> Result<(), StopReason> {
    let mut pace = pulse.paced(64 * 1024);
    for row in rows {
        for i in 4..row.len() {
            row[i] = row[i].wrapping_add(row[i - 4]);
        }
        pace.step(row.len() as u64)?;
    }
    pace.finish()
}

defilter(&mut vec![vec![0; 64]; 3], &how_far::NoPulse)?;

Units not yet reported are reported when the Paced is dropped, including after an early return, so finished work is always counted. Flush before splitting the pulse it reports to: a phase that split ignores reports. Accidentally discarding a new guard is diagnosed; retaining one still requires an explicit finish call to check the final partial batch.

#![deny(unused_must_use)]
use how_far::{NoPulse, Paced};
Paced::new(&NoPulse, 64);

Implementations

impl<'a> Paced<'a>

pub fn new(pulse: &'a dyn Pulse, every: u64) -> Self

Reach pulse once every every units (at least 1).

pub fn step(&mut self, completed: u64) -> Result<(), StopReason>

Count completed finished units. Once every units are pending, report them and check for cancellation.

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

Check for cancellation now, whatever is pending.

pub fn finish(self) -> Result<(), StopReason>

Flush the final batch and check cancellation before returning success. Drop only flushes counts and cannot propagate cancellation.

pub fn flush(&mut self)

Report every pending unit now.

Trait Implementations

impl Debug for Paced<'_>

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

Formats the value using the given formatter.

impl Drop for Paced<'_>

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.