Struct prodash::tree::Item

pub struct Item { /* private fields */ }

A Tree represents an element of the progress tree.

It can be used to set progress and send messages.

let tree = prodash::tree::Root::new();
let mut progress = tree.add_child("task 1");

progress.init(Some(10), Some("elements".into()));
for p in 0..10 {
    progress.set(p);
}
progress.done("great success");
let mut  sub_progress = progress.add_child_with_id("sub-task 1", *b"TSK2");
sub_progress.init(None, None);
sub_progress.set(5);
sub_progress.fail("couldn't finish");

Implementations

impl Item

pub fn init(&self, max: Option<usize>, unit: Option<Unit>)

Initialize the Item for receiving progress information.

If max is Some(…), it will be treated as upper bound. When progress is set(…) it should not exceed the given maximum. If max is None, the progress is unbounded. Use this if the amount of work cannot accurately be determined.

If unit is Some(…), it is used for display purposes only. It should be using the plural.

If this method is never called, this Item will serve as organizational unit, useful to add more structure to the progress tree.

Note that this method can be called multiple times, changing the bounded-ness and unit at will.

pub fn set_name(&self, name: impl Into<String>)

Set the name of this task’s progress to the given name.

pub fn name(&self) -> Option<String>

Get the name of this task’s progress

pub fn id(&self) -> Id

Get the stable identifier of this instance.

pub fn step(&self) -> Option<Step>

Returns the current step, as controlled by inc*(…) calls

pub fn max(&self) -> Option<Step>

Returns the maximum about of items we expect, as provided with the init(…) call

pub fn set_max(&self, max: Option<Step>) -> Option<Step>

Set the maximum value to max and return the old maximum value.

pub fn unit(&self) -> Option<Unit>

Returns the (cloned) unit associated with this Progress

pub fn set(&self, step: Step)

Set the current progress to the given step.

Note: that this call has no effect unless init(…) was called before.

pub fn inc_by(&self, step: Step)

Increment the current progress by the given step.

Note: that this call has no effect unless init(…) was called before.

pub fn inc(&self)

Increment the current progress by one.

Note: that this call has no effect unless init(…) was called before.

pub fn blocked(&self, reason: &'static str, eta: Option<SystemTime>)

Call to indicate that progress cannot be indicated, and that the task cannot be interrupted. Use this, as opposed to halted(…), if a non-interruptable call is about to be made without support for any progress indication.

If eta is Some(…), it specifies the time at which this task is expected to make progress again.

The halted-state is undone next time tree::Item::running(…) is called.

pub fn halted(&self, reason: &'static str, eta: Option<SystemTime>)

Call to indicate that progress cannot be indicated, even though the task can be interrupted. Use this, as opposed to blocked(…), if an interruptable call is about to be made without support for any progress indication.

If eta is Some(…), it specifies the time at which this task is expected to make progress again.

The halted-state is undone next time tree::Item::running(…) is called.

pub fn running(&self)

Call to indicate that progress is back in running state, which should be called after the reason for calling blocked() or halted() has passed.

pub fn add_child(&mut self, name: impl Into<String>) -> Item

Adds a new child Tree, whose parent is this instance, with the given name.

Important: The depth of the hierarchy is limited to tree::Key::max_level. Exceeding the level will be ignored, and new tasks will be added to this instance’s level instead.

pub fn add_child_with_id(&mut self, name: impl Into<String>, id: Id) -> Item

Adds a new child Tree, whose parent is this instance, with the given name and id.

Important: The depth of the hierarchy is limited to tree::Key::max_level. Exceeding the level will be ignored, and new tasks will be added to this instance’s level instead.

pub fn message(&self, level: MessageLevel, message: impl Into<String>)

Create a message of the given level and store it with the progress tree.

Use this to provide additional,human-readable information about the progress made, including indicating success or failure.

pub fn done(&mut self, message: impl Into<String>)

Create a message indicating the task is done

pub fn fail(&mut self, message: impl Into<String>)

Create a message indicating the task failed

pub fn info(&mut self, message: impl Into<String>)

Create a message providing additional information about the progress thus far.

Trait Implementations

impl Count for Item

fn set(&self, step: usize)

Set the current progress to the given step. The cost of this call is negligible, making manual throttling not necessary.

fn step(&self) -> usize

Returns the current step, as controlled by inc*(…) calls

fn inc_by(&self, step: usize)

Increment the current progress to the given step. The cost of this call is negligible, making manual throttling not necessary.

fn counter(&self) -> StepShared

Return an atomic counter for direct access to the underlying state.

fn inc(&self)

Increment the current progress to the given 1. The cost of this call is negligible, making manual throttling not necessary.

impl Debug for Item

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

Formats the value using the given formatter.

impl Drop for Item

fn drop(&mut self)

Executes the destructor for this type.

impl NestedProgress for Item

type SubProgress = Item

The type of progress returned by [add_child()][Progress::add_child()].

fn add_child(&mut self, name: impl Into<String>) -> Self

Adds a new child, whose parent is this instance, with the given name.

fn add_child_with_id(&mut self, name: impl Into<String>, id: Id) -> Self

Adds a new child, whose parent is this instance, with the given name and id.

impl Progress for Item

fn init(&mut self, max: Option<Step>, unit: Option<Unit>)

Initialize the Item for receiving progress information.

fn unit(&self) -> Option<Unit>

Returns the (cloned) unit associated with this Progress

fn max(&self) -> Option<usize>

Returns the maximum about of items we expect, as provided with the init(…) call

fn set_max(&mut self, max: Option<Step>) -> Option<Step>

Set the maximum value to max and return the old maximum value.

fn set_name(&mut self, name: String)

Set the name of the instance, altering the value given when crating it with add_child(…) The progress is allowed to discard it.

fn name(&self) -> Option<String>

Get the name of the instance as given when creating it with add_child(…) The progress is allowed to not be named, thus there is no guarantee that a previously set names ‘sticks’.

fn id(&self) -> Id

Get a stable identifier for the progress instance. Note that it could be unknown.

fn message(&self, level: MessageLevel, message: String)

Create a message of the given level and store it with the progress tree.

fn info(&self, message: String)

Create a message providing additional information about the progress thus far.

fn done(&self, message: String)

Create a message indicating the task is done successfully

fn fail(&self, message: String)

Create a message indicating the task failed

fn show_throughput(&self, start: Instant)

A shorthand to print throughput information

fn show_throughput_with( &self, start: Instant, step: Step, unit: Unit, level: MessageLevel )

A shorthand to print throughput information, with the given step and unit, and message level.