Crate howudoin

Expand description

A progress reporting and consuming abstraction.

howudoin intends to make producing and consuming progress reports simple and ergonomic.

// initialise a consumer loop
howudoin::init(howudoin::consumers::Noop::default());

let rpt = howudoin::new().label("Progress").set_len(10);

for _ in 0..10 {
    rpt.inc(); // increment the progress
    // check for cancellation
    if rpt.cancelled() {
        break;
    }
}

rpt.finish(); // finalise progress

// fetch the tree of progress
let progress = howudoin::fetch();

Features:

Lightweight
Unobtrusive interface
Nestable reports
Automatic timers
Message accumulation
Cancellation

§Progress Reporting

Producing a progress report can be done anywhere in code without any references.

// creates a new report
let rpt = howudoin::new();
// creates a report below `rpt`
let child = howudoin::new_with_parent(rpt.id());
// creates a report at the root
let rpt2 = howudoin::new_root();

// progress reporting
let rpt = rpt
    .label("Label") // set a label/name
    .set_len(1000); // progress is bounded

rpt.desc("processing"); // progress message
for i in 1_u32..=1000 {
    rpt.inc();      // increment progress position
    rpt.set_pos(i); // set progress position
}

rpt.finish(); // finished a report
rpt.close();  // close a report from display

§Progress Display

Progress display is abstracted from the producer. A display mechanism implements the Consume trait, and is sent to the consumer loop with init. There exist a few predefined consumers in the consumers module, which are feature gated. Consumers are generally defined for mechanisms that are invoked.

// initialise a term-line consumer
howudoin::init(howudoin::consumers::TermLine::default());

§Progress Consumption

Progress reports can also be requested from the consumer loop. This pattern is used when a progress update is requested from elsewhere (for example, a REST API).

// initialise a no-op consumer
howudoin::init(howudoin::consumers::Noop::default());

// fetch the progress tree
let progress = howudoin::fetch();

§Opt-in

Progress reports are only sent to a consumer if the consumer loop has been initialised. In situations where the loop has not been initialised, progress reporting is a very cheap void operation. This means producers can be neatly separated from consumers.

Modules§

consumers: Predefined implementors of Consume.
flat_tree: A common abstraction of a ‘flat’ tree which tracks the nodes with an ordered map and the set of root nodes.
report: The public structures of progress reports.

Structs§

Controller: The progress consumer loop controller.
Tx: The progress reporter transmitter.

Traits§

Consume: A report consumer.

Functions§

cancel: Flag for cancellation.
cancelled: Check the cancellation flag.
disable: Disable the progress reporting consumer loop, terminating the sender side.
fetch: Fetch the progress report tree.
init: Initialise the progress consumer loop.
new: Generate a new progress reporter.
new_root: Generate a new progress reporter at the root level.
new_with_parent: Generate a new progress reporter under a parent.
reset: Reset the progress consumer loop.

Type Aliases§

Id: A report identifier.

Crate howudoinCopy item path