Prodash

https://docs.rs/prodash/31.0.0/prodash/
Admin
Prodash is a Rust dashboard for displaying the progress of concurrent applications with hierarchical...
Tokens:82,296
Snippets:971
Trust Score:9.1
Update:5 months ago
Show doc for...
Tokens:
Raw
### AtomicUsize fetch_min Example

Source: https://docs.rs/prodash/31.0.0/prodash/progress/type.AtomicStep.html

Demonstrates fetch_min for atomically setting an AtomicUsize to the minimum of its current value and a given value. Returns the previous value.

```rust
use std::sync::atomic::{AtomicUsize, Ordering};

let foo = AtomicUsize::new(23);
assert_eq!(foo.fetch_min(42, Ordering::Relaxed), 23);
assert_eq!(foo.load(Ordering::Relaxed), 23);
assert_eq!(foo.fetch_min(22, Ordering::Relaxed), 23);
assert_eq!(foo.load(Ordering::Relaxed), 22);
```

```rust
use std::sync::atomic::{AtomicUsize, Ordering};

let foo = AtomicUsize::new(23);
let bar = 12;
let min_foo = foo.fetch_min(bar, Ordering::SeqCst).min(bar);
assert_eq!(min_foo, 12);
```

--------------------------------

### Initialize Formatter

Source: https://docs.rs/prodash/31.0.0/prodash/unit/human/struct.Formatter.html

Creates a new Formatter instance with default settings. Use this as the starting point for all formatting operations.

```rust
pub struct Formatter { /* private fields */ }
```

--------------------------------

### Minimal TUI Example

Source: https://docs.rs/prodash/31.0.0/prodash/render/tui/index.html

Demonstrates how to set up and run a basic TUI progress bar. Requires futures and prodash crates. The TUI runs indefinitely and needs to be manually aborted.

```rust
use futures::task::{LocalSpawnExt, SpawnExt};
use prodash::render::tui::ticker;
use prodash::Root;
// obtain a progress tree
let root = prodash::tree::Root::new();
// Configure the gui, provide it with a handle to the ever-changing tree
let render_fut = prodash::render::tui::render(
    std::io::stdout(),
    root.downgrade(),
    prodash::render::tui::Options {
        title: "minimal example".into(),
        ..Default::default()
    }
)?;
// As it runs forever, we want a way to stop it.
let (render_fut, abort_handle) = futures::future::abortable(render_fut);
let pool = futures::executor::LocalPool::new();
// Spawn the gui into the background…
let gui = pool.spawner().spawn_with_handle(async { render_fut.await.ok(); () })?;
// …and run tasks which provide progress
pool.spawner().spawn_local({
    use futures::StreamExt;
    let mut progress = root.add_child("task");
    async move {
        progress.init(None, None);
        let mut count = 0;
        let  mut ticks = ticker(std::time::Duration::from_millis(100));
        while let Some(_) = ticks.next().await {
            progress.set(count);
            count += 1;
        }
    }
})?;
// …when we are done, tell the GUI to stop
abort_handle.abort();
//…and wait until it is done
futures::executor::block_on(gui);
```

--------------------------------

### Show Throughput

Source: https://docs.rs/prodash/31.0.0/prodash/trait.Progress.html

A shorthand method to print throughput information based on a start time.

```rust
fn show_throughput(&self, start: Instant) { ... }

```

--------------------------------

### AtomicUsize fetch_max Example

Source: https://docs.rs/prodash/31.0.0/prodash/progress/type.AtomicStep.html

Shows how to use fetch_max to atomically set an AtomicUsize to the maximum of its current value and a given value. Returns the previous value.

```rust
use std::sync::atomic::{AtomicUsize, Ordering};

let foo = AtomicUsize::new(23);
assert_eq!(foo.fetch_max(42, Ordering::SeqCst), 23);
assert_eq!(foo.load(Ordering::SeqCst), 42);
```

```rust
use std::sync::atomic::{AtomicUsize, Ordering};

let foo = AtomicUsize::new(23);
let bar = 42;
let max_foo = foo.fetch_max(bar, Ordering::SeqCst).max(bar);
assert!(max_foo == 42);
```

--------------------------------

### Atomic usize fetch_add Example

Source: https://docs.rs/prodash/31.0.0/prodash/progress/type.AtomicStep.html

Shows how to atomically add a value to an `AtomicUsize` and retrieve the previous value. This operation wraps around on overflow.

```rust
use std::sync::atomic::{AtomicUsize, Ordering};

let foo = AtomicUsize::new(0);
assert_eq!(foo.fetch_add(10, Ordering::SeqCst), 0);
assert_eq!(foo.load(Ordering::SeqCst), 10);
```

--------------------------------

### AtomicUsize fetch_and Example

Source: https://docs.rs/prodash/31.0.0/prodash/progress/type.AtomicStep.html

Demonstrates the `fetch_and` operation on an AtomicUsize. This method performs a bitwise AND with the current value and returns the previous value. Ensure the platform supports atomic operations on usize.

```rust
use std::sync::atomic::{AtomicUsize, Ordering};

let foo = AtomicUsize::new(0b101101);
assert_eq!(foo.fetch_and(0b110011, Ordering::SeqCst), 0b101101);
assert_eq!(foo.load(Ordering::SeqCst), 0b100001);
```

--------------------------------

### AtomicUsize Update Example

Source: https://docs.rs/prodash/31.0.0/prodash/progress/type.AtomicStep.html

Demonstrates the atomic update operation on AtomicUsize, showing how to atomically modify the value based on a closure. Requires the `atomic_try_update` feature.

```rust
#![feature(atomic_try_update)]
use std::sync::atomic::{AtomicUsize, Ordering};

let x = AtomicUsize::new(7);
assert_eq!(x.update(Ordering::SeqCst, Ordering::SeqCst, |x| x + 1), 7);
assert_eq!(x.update(Ordering::SeqCst, Ordering::SeqCst, |x| x + 1), 8);
assert_eq!(x.load(Ordering::SeqCst), 9);
```

--------------------------------

### AtomicUsize fetch_xor Example

Source: https://docs.rs/prodash/31.0.0/prodash/progress/type.AtomicStep.html

Demonstrates the `fetch_xor` operation for AtomicUsize. It applies a bitwise XOR and returns the previous value. Note that this method requires platform support for atomic usize operations.

```rust
use std::sync::atomic::{AtomicUsize, Ordering};

let foo = AtomicUsize::new(0b101101);
assert_eq!(foo.fetch_xor(0b110011, Ordering::SeqCst), 0b101101);
assert_eq!(foo.load(Ordering::SeqCst), 0b011110);
```

--------------------------------

### Show Throughput

Source: https://docs.rs/prodash/31.0.0/prodash/progress/struct.Log.html

A convenience function to print throughput information based on a start time.

```rust
fn show_throughput(&self, start: Instant)
```

--------------------------------

### fn show_throughput

Source: https://docs.rs/prodash/31.0.0/prodash/trait.Progress.html

A shorthand method to print throughput information based on a start time.

```APIDOC
## fn show_throughput

### Description
A shorthand to print throughput information

### Parameters
- **start** (Instant) - Description: The starting point in time for calculating throughput.
```

--------------------------------

### AtomicUsize fetch_or Example

Source: https://docs.rs/prodash/31.0.0/prodash/progress/type.AtomicStep.html

Shows how to use `fetch_or` with AtomicUsize. This performs a bitwise OR operation, updating the value and returning the original value. Availability depends on platform support for usize atomics.

```rust
use std::sync::atomic::{AtomicUsize, Ordering};

let foo = AtomicUsize::new(0b101101);
assert_eq!(foo.fetch_or(0b110011, Ordering::SeqCst), 0b101101);
assert_eq!(foo.load(Ordering::SeqCst), 0b111111);
```

--------------------------------

### AtomicUsize fetch_nand Example

Source: https://docs.rs/prodash/31.0.0/prodash/progress/type.AtomicStep.html

Illustrates the `fetch_nand` operation for AtomicUsize. It performs a bitwise NAND operation and returns the previous value. This method is platform-dependent on usize atomics.

```rust
use std::sync::atomic::{AtomicUsize, Ordering};

let foo = AtomicUsize::new(0x13);
assert_eq!(foo.fetch_nand(0x31, Ordering::SeqCst), 0x13);
assert_eq!(foo.load(Ordering::SeqCst), !(0x13 & 0x31));
```

--------------------------------

### Atomic usize fetch_sub Example

Source: https://docs.rs/prodash/31.0.0/prodash/progress/type.AtomicStep.html

Demonstrates atomically subtracting a value from an `AtomicUsize` and retrieving the previous value. This operation also wraps around on overflow.

```rust
use std::sync::atomic::{AtomicUsize, Ordering};

let foo = AtomicUsize::new(20);
assert_eq!(foo.fetch_sub(10, Ordering::SeqCst), 20);
assert_eq!(foo.load(Ordering::SeqCst), 10);
```

--------------------------------

### Atomic usize compare_exchange Example

Source: https://docs.rs/prodash/31.0.0/prodash/progress/type.AtomicStep.html

Demonstrates the usage of `compare_exchange` to atomically update a `usize` value. It shows both a successful exchange and a failed exchange due to the value not matching the expected current value.

```rust
use std::sync::atomic::{AtomicUsize, Ordering};

let some_var = AtomicUsize::new(5);

assert_eq!(some_var.compare_exchange(5, 10,
                                     Ordering::Acquire,
                                     Ordering::Relaxed),
           Ok(5));
assert_eq!(some_var.load(Ordering::Relaxed), 10);

assert_eq!(some_var.compare_exchange(6, 12,
                                     Ordering::SeqCst,
                                     Ordering::Acquire),
           Err(10));
assert_eq!(some_var.load(Ordering::Relaxed), 10);
```

--------------------------------

### Default Options for Line Renderer

Source: https://docs.rs/prodash/31.0.0/prodash/render/line/struct.Options.html

Provides the default configuration for the line renderer. Use this as a starting point for customization.

```rust
impl Default for Options {
    fn default() -> Self {
        // ... implementation details ...
    }
}

```

--------------------------------

### AtomicUsize as_ptr Example

Source: https://docs.rs/prodash/31.0.0/prodash/progress/type.AtomicStep.html

Illustrates obtaining a mutable pointer to the underlying integer of an AtomicUsize. This is primarily for FFI use and requires an unsafe block.

```rust
use std::sync::atomic::AtomicUsize;

extern "C" {
    fn my_atomic_op(arg: *mut usize);
}

let atomic = AtomicUsize::new(1);

// SAFETY: Safe as long as `my_atomic_op` is atomic.
unsafe {
    my_atomic_op(atomic.as_ptr());
}
```

--------------------------------

### Item::id

Source: https://docs.rs/prodash/31.0.0/prodash/tree/struct.Item.html

Gets the stable identifier of this Item instance.

```APIDOC
## Item::id

### Description
Get the stable identifier of this instance.

### Method
`id(&self) -> Id`
```

--------------------------------

### Auto-Configure Line Renderer Options

Source: https://docs.rs/prodash/31.0.0/prodash/render/line/struct.Options.html

Automatically configures fields like output_is_terminal, colored, terminal_dimensions, and hide_cursor based on the provided output stream kind. This simplifies setup for common terminal environments.

```rust
pub fn auto_configure(self, output: StreamKind) -> Self
```

--------------------------------

### Item::name

Source: https://docs.rs/prodash/31.0.0/prodash/tree/struct.Item.html

Gets the name of this task's progress.

```APIDOC
## Item::name

### Description
Get the name of this task’s progress

### Method
`name(&self) -> Option<String>`
```

--------------------------------

### Formatter Initialization and Configuration

Source: https://docs.rs/prodash/31.0.0/prodash/unit/human/struct.Formatter.html

Demonstrates how to initialize a Formatter and configure its various settings for custom formatting.

```APIDOC
## Formatter Methods

### `new()`

Initializes a new `Formatter` with default values.

### `with_decimals(decimals: usize)`

Sets the decimals value for formatting the string.

### `with_separator(separator: &str)`

Sets the separator value for formatting the string.

### `with_scales(scales: Scales)`

Sets the scales value.

### `with_units(units: &str)`

Sets the units value.

### `with_suffix(suffix: &str)`

Sets the expected suffix value.

### `with_micro_sign(enable: bool)`

Enable using the micro sign `µ` in formatted output when fractional suffix is `u`.
```

--------------------------------

### Get Progress Unit

Source: https://docs.rs/prodash/31.0.0/prodash/trait.Progress.html

Returns the unit associated with this progress instance, if any.

```rust
fn unit(&self) -> Option<Unit> { ... }

```

--------------------------------

### Atomic usize compare_exchange_weak Loop Example

Source: https://docs.rs/prodash/31.0.0/prodash/progress/type.AtomicStep.html

Illustrates using `compare_exchange_weak` within a loop to perform a read-modify-write operation. This is necessary because `compare_exchange_weak` can fail spuriously even if the value matches.

```rust
use std::sync::atomic::{AtomicUsize, Ordering};

let val = AtomicUsize::new(4);

let mut old = val.load(Ordering::Relaxed);
loop {
    let new = old * 2;
    match val.compare_exchange_weak(old, new, Ordering::SeqCst, Ordering::Relaxed) {
        Ok(_) => break,
        Err(x) => old = x,
    }
}
```

--------------------------------

### Get Log Unit

Source: https://docs.rs/prodash/31.0.0/prodash/progress/struct.Log.html

Returns the unit associated with this progress instance, if any.

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

--------------------------------

### AtomicUsize::from_mut

Source: https://docs.rs/prodash/31.0.0/prodash/progress/type.AtomicStep.html

Gets atomic access to a mutable `usize`. This is a nightly-only experimental API.

```APIDOC
## pub fn from_mut(v: &mut usize) -> &mut AtomicUsize

### Description
Get atomic access to a `&mut usize`.

**Note:** This function is only available on targets where `AtomicUsize` has the same alignment as `usize`.

### Examples
```rust
#![feature(atomic_from_mut)]
use std::sync::atomic::{AtomicUsize, Ordering};

let mut some_int = 123;
let a = AtomicUsize::from_mut(&mut some_int);
a.store(100, Ordering::Relaxed);
assert_eq!(some_int, 100);
```
```

--------------------------------

### create Function

Source: https://docs.rs/prodash/31.0.0/prodash/tree/root/struct.Options.html

Creates a new `Root` instance using the configuration provided by the Options struct.

```APIDOC
## impl Options

### pub fn create(self) -> Root
Create a new `Root` instance from the configuration within.
```

--------------------------------

### fn id

Source: https://docs.rs/prodash/31.0.0/prodash/trait.Progress.html

Gets a stable identifier for the progress instance. This identifier may be unknown.

```APIDOC
## fn id

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

### Returns
- Id - A stable identifier for the progress instance.
```

--------------------------------

### Get Progress Maximum

Source: https://docs.rs/prodash/31.0.0/prodash/trait.Progress.html

Returns the maximum value for this progress instance, as provided during initialization.

```rust
fn max(&self) -> Option<Step> { ... }

```

--------------------------------

### Get Current Step

Source: https://docs.rs/prodash/31.0.0/prodash/trait.Count.html

Returns the current progress step as determined by increment calls.

```rust
fn step(&self) -> Step
```

--------------------------------

### Create prodash::tree::root::Options Instance

Source: https://docs.rs/prodash/31.0.0/prodash/tree/root/struct.Options.html

Demonstrates creating new tree::Root instances using default options or with a specified message buffer capacity.

```rust
let tree = prodash::tree::root::Options::default().create();
let tree2 = prodash::tree::root::Options { message_buffer_capacity: 100, ..Default::default() }.create();
```

--------------------------------

### AtomicUsize::from_mut_slice

Source: https://docs.rs/prodash/31.0.0/prodash/progress/type.AtomicStep.html

Gets atomic access to a mutable slice of `usize`. This is a nightly-only experimental API.

```APIDOC
## pub fn from_mut_slice(v: &mut [usize]) -> &mut [AtomicUsize]

### Description
Get atomic access to a `&mut [usize]` slice.

**Note:** This function is only available on targets where `AtomicUsize` has the same alignment as `usize`.

### Examples
```rust
#![feature(atomic_from_mut)]
use std::sync::atomic::{AtomicUsize, Ordering};

let mut some_ints = [0; 10];
let a = &*AtomicUsize::from_mut_slice(&mut some_ints);
std::thread::scope(|s| {
    for i in 0..a.len() {
        s.spawn(move || a[i].store(i as _, Ordering::Relaxed));
    }
});
for (i, n) in some_ints.into_iter().enumerate() {
    assert_eq!(i, n as usize);
}
```
```

--------------------------------

### AtomicUsize::get_mut_slice

Source: https://docs.rs/prodash/31.0.0/prodash/progress/type.AtomicStep.html

Gets non-atomic access to a mutable slice of `AtomicUsize`. This is a nightly-only experimental API.

```APIDOC
## pub fn get_mut_slice(this: &mut [AtomicUsize]) -> &mut [usize]

### Description
Get non-atomic access to a `&mut [AtomicUsize]` slice. This is safe because the mutable reference guarantees that no other threads are concurrently accessing the atomic data.

### Examples
```rust
#![feature(atomic_from_mut)]
use std::sync::atomic::{AtomicUsize, Ordering};

let mut some_ints = [const { AtomicUsize::new(0) }; 10];

let view: &mut [usize] = AtomicUsize::get_mut_slice(&mut some_ints);
assert_eq!(view, [0; 10]);
view
    .iter_mut()
    .enumerate()
    .for_each(|(idx, int)| *int = idx as _);

std::thread::scope(|s| {
    some_ints
        .iter()
        .enumerate()
        .for_each(|(idx, int)| {
            s.spawn(move || assert_eq!(int.load(Ordering::Relaxed), idx as _));
        })
});
```
```

--------------------------------

### Mode Initialization and Modification

Source: https://docs.rs/prodash/31.0.0/prodash/unit/display/struct.Mode.html

Methods for creating and configuring Mode instances.

```APIDOC
## Mode Initialization and Modification

### `with_percentage()`

- **Description**: Create a mode instance with percentage only.
- **Signature**: `pub fn with_percentage() -> Self`

### `with_throughput()`

- **Description**: Create a mode instance with throughput only.
- **Signature**: `pub fn with_throughput() -> Self`

### `and_percentage()`

- **Description**: Turn on percentage display on the current instance.
- **Signature**: `pub fn and_percentage(self) -> Self`

### `and_throughput()`

- **Description**: Turn on throughput display on the current instance.
- **Signature**: `pub fn and_throughput(self) -> Self`

### `show_before_value()`

- **Description**: Change the display location to show up in front of the value.
- **Signature**: `pub fn show_before_value(self) -> Self`
```

--------------------------------

### Create Root Instance from Options

Source: https://docs.rs/prodash/31.0.0/prodash/tree/root/struct.Options.html

Method to create a new Root instance based on the configuration provided by the Options struct.

```rust
pub fn create(self) -> Root
```

--------------------------------

### Get Progress ID

Source: https://docs.rs/prodash/31.0.0/prodash/trait.Progress.html

Retrieves a stable identifier for the progress instance. The identifier may be unknown.

```rust
fn id(&self) -> Id;

```

--------------------------------

### Get Log ID

Source: https://docs.rs/prodash/31.0.0/prodash/progress/struct.Log.html

Retrieves a stable identifier for this progress instance. The ID might be unknown.

```rust
fn id(&self) -> Id
```

--------------------------------

### Initialize and Update Progress

Source: https://docs.rs/prodash/31.0.0/prodash/tree/struct.Item.html

Demonstrates initializing a progress item with a maximum value and unit, then updating its progress and marking it as done. Also shows adding a sub-task with a specific ID, initializing it, and marking it as failed.

```rust
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");
```

--------------------------------

### Get Minimum Adjacency

Source: https://docs.rs/prodash/31.0.0/prodash/progress/key/struct.Adjacency.html

Returns the lesser of two Adjacency values. Requires Self to be Sized.

```rust
fn min(self, other: Self) -> Self
```

--------------------------------

### Key Ordering Implementations

Source: https://docs.rs/prodash/31.0.0/prodash/progress/struct.Key.html

Provides total ordering for Keys, allowing them to be compared and sorted. Includes methods for comparison, finding min/max, and clamping values.

```rust
fn cmp(&self, other: &Key) -> Ordering
```

```rust
fn max(self, other: Self) -> Self
where Self: Sized,
```

```rust
fn min(self, other: Self) -> Self
where Self: Sized,
```

```rust
fn clamp(self, min: Self, max: Self) -> Self
where Self: Sized,
```

--------------------------------

### Get Log Name

Source: https://docs.rs/prodash/31.0.0/prodash/progress/struct.Log.html

Retrieves the name of the progress instance. The name may not be preserved by the implementation.

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

--------------------------------

### Item::init

Source: https://docs.rs/prodash/31.0.0/prodash/tree/struct.Item.html

Initializes the Item for receiving progress information. It can set an upper bound for progress and a unit for display purposes. This method can be called multiple times.

```APIDOC
## Item::init

### Description
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.

### Method
`init(&self, max: Option<usize>, unit: Option<Unit>)`
```

--------------------------------

### Get Maximum Adjacency

Source: https://docs.rs/prodash/31.0.0/prodash/progress/key/struct.Adjacency.html

Returns the greater of two Adjacency values. Requires Self to be Sized.

```rust
fn max(self, other: Self) -> Self
```

--------------------------------

### From Options to Root

Source: https://docs.rs/prodash/31.0.0/prodash/tree/root/struct.Options.html

Converts an Options struct into a Root instance.

```rust
fn from(_: Options) -> Self
```

--------------------------------

### Get Log Counter

Source: https://docs.rs/prodash/31.0.0/prodash/progress/struct.Log.html

Returns an atomic counter for direct access to the underlying progress state.

```rust
fn counter(&self) -> StepShared
```

--------------------------------

### Get Unit as DisplayValue Trait Object

Source: https://docs.rs/prodash/31.0.0/prodash/struct.Unit.html

Returns the Unit as a trait object that implements the DisplayValue trait.

```rust
pub fn as_display_value(&self) -> &dyn DisplayValue
```

--------------------------------

### Get Log Maximum Value

Source: https://docs.rs/prodash/31.0.0/prodash/progress/struct.Log.html

Returns the maximum number of items expected for this progress, as set during initialization.

```rust
fn max(&self) -> Option<Step>
```

--------------------------------

### Root::new

Source: https://docs.rs/prodash/31.0.0/prodash/tree/struct.Root.html

Creates a new tree with default configuration. This type can be safely sent across threads.

```APIDOC
## Root::new

### Description
Create a new tree with default configuration. As opposed to Item instances, this type can be closed and sent safely across threads.

### Signature
```rust
pub fn new() -> Arc<Root>
```
```

--------------------------------

### Wait for JoinHandle

Source: https://docs.rs/prodash/31.0.0/prodash/render/line/struct.JoinHandle.html

Use `wait()` to block until the render thread shuts down naturally, for example, when there is no more progress to display.

```rust
pub fn wait(self)
```

--------------------------------

### Get Maximum Messages Capacity

Source: https://docs.rs/prodash/31.0.0/prodash/tree/struct.Root.html

Retrieves the maximum number of messages the tree can store before older messages are overwritten.

```rust
pub fn messages_capacity(&self) -> usize
```

--------------------------------

### impl Options

Source: https://docs.rs/prodash/31.0.0/prodash/render/line/struct.Options.html

Provides methods for configuring the Options struct.

```APIDOC
## impl Options

### auto_configure

#### Description
Automatically configure (and overwrite) the following fields based on terminal configuration: `output_is_terminal`, `colored`, `terminal_dimensions`, `hide-cursor` (based on presence of ‘signal-hook’ feature).

#### Method
`pub fn auto_configure(self, output: StreamKind) -> Self`
```

--------------------------------

### fn init

Source: https://docs.rs/prodash/31.0.0/prodash/trait.Progress.html

Initializes the progress item with an optional maximum value and unit. If max is None, the progress is unbounded. If unit is Some, it's used for display. Calling with both None resets the item.

```APIDOC
## fn init

### Description
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 in advance.
If `unit` is `Some(…)`, it is used for display purposes only. See `prodash::Unit` for more information.
If both `unit` and `max` are `None`, the item will be reset to be equivalent to ‘uninitialized’.
If this method is never called, this `Progress` instance will serve as organizational unit, useful to add more structure to the progress tree (e.g. a headline).
**Note** that this method can be called multiple times, changing the bounded-ness and unit at will.

### Parameters
- **max** (Option<Step>) - Description: The maximum value for the progress, or None if unbounded.
- **unit** (Option<Unit>) - Description: The unit for display purposes, or None.
```

--------------------------------

### Adjacency Methods

Source: https://docs.rs/prodash/31.0.0/prodash/progress/key/struct.Adjacency.html

Provides methods for interacting with the Adjacency struct, including getting the level, and accessing sibling locations.

```APIDOC
### impl Adjacency

#### pub fn level(&self) -> Level
Return the level at which this sibling is located in the hierarchy.

#### pub fn get(&self, level: Level) -> Option<&SiblingLocation>
Get a reference to the sibling location at `level`.

#### pub fn get_mut(&mut self, level: Level) -> Option<&mut SiblingLocation>
Get a mutable reference to the sibling location at `level`.
```

--------------------------------

### Struct Options

Source: https://docs.rs/prodash/31.0.0/prodash/render/line/struct.Options.html

Represents the configuration options for the line renderer.

```APIDOC
## Struct Options

### Description
Options used for configuring a line renderer.

### Fields
- **output_is_terminal**: `bool` - If true, assumes the output stream belongs to a terminal. If false, no live progress is printed, only log messages.
- **colored**: `bool` - If true, displays color. Should be determined by `output_is_terminal && crosstermion::should_colorize()`. Can be enforced even if the output stream is not connected to a terminal.
- **timestamp**: `bool` - If true, a timestamp will be shown before each message.
- **terminal_dimensions**: `(u16, u16)` - The amount of columns and rows to use for drawing. Defaults to (80, 20).
- **hide_cursor**: `bool` - If true, the cursor will be hidden for a more visually appealing display. Ensure proper shutdown to restore cursor settings.
- **throughput**: `bool` - If true, tracks previous progress state to derive continuous throughput information. Throughput is opt-in for units and incurs additional memory and CPU cost.
- **level_filter**: `Option<RangeInclusive<Level>>` - If set, specifies all levels that should be shown. Otherwise, all available levels are shown. Useful for filtering out high-noise lower-level progress items.
- **initial_delay**: `Option<Duration>` - If set, progress will only be shown after the given duration. Log messages are always shown without delay. Useful to avoid flickering for short actions.
- **frames_per_second**: `f32` - The amount of frames to draw per second. If below 1.0, it determines the amount of seconds between frames (e.g., 1.0/4.0 is one frame every 4 seconds).
- **keep_running_if_progress_is_empty**: `bool` - If true, continues waiting for progress even after encountering an empty list of drawable progress items. Ensure at least one item is added to `prodash::Tree` before launching to avoid race conditions.
```

--------------------------------

### Get Current Log Step

Source: https://docs.rs/prodash/31.0.0/prodash/progress/struct.Log.html

Returns the current progress step. This value is controlled by `inc*(…)` calls.

```rust
fn step(&self) -> usize
```

--------------------------------

### compare

Source: https://docs.rs/prodash/31.0.0/prodash/progress/struct.Key.html

Compares self to a given key and returns their ordering.

```APIDOC
## compare

### Description
Compares self to `key` and return their ordering.

### Signature
`fn compare(&self, key: &K) -> Ordering`
```

--------------------------------

### Default Implementation

Source: https://docs.rs/prodash/31.0.0/prodash/tree/root/struct.Options.html

Provides a default configuration for the Options struct.

```APIDOC
### impl Default for Options

#### fn default() -> Self
Returns the “default value” for a type.
```

--------------------------------

### Instantiate Scales with Binary keys

Source: https://docs.rs/prodash/31.0.0/prodash/unit/human/struct.Scales.html

Use this to create a new Scales instance with binary prefixes (KiB, MiB, etc.). Useful for memory or storage related scaling.

```rust
pub fn Binary() -> Scales
```

--------------------------------

### Get Progress Name

Source: https://docs.rs/prodash/31.0.0/prodash/trait.Progress.html

Retrieves the name of the progress instance. The name is not guaranteed to persist, as the progress instance may discard it.

```rust
fn name(&self) -> Option<String>;

```

--------------------------------

### Get Sibling Location by Level

Source: https://docs.rs/prodash/31.0.0/prodash/progress/key/struct.Adjacency.html

Retrieves a reference to the SiblingLocation at a specific hierarchical level. Returns None if the level is out of bounds.

```rust
pub fn get(&self, level: Level) -> Option<&SiblingLocation>
```

--------------------------------

### Get Mutable Reference to AtomicUsize Value

Source: https://docs.rs/prodash/31.0.0/prodash/progress/type.AtomicStep.html

Returns a mutable reference to the underlying integer of an AtomicUsize. This is safe as it guarantees no concurrent access.

```rust
use std::sync::atomic::{AtomicUsize, Ordering};

let mut some_var = AtomicUsize::new(10);
assert_eq!(*some_var.get_mut(), 10);
*some_var.get_mut() = 5;
assert_eq!(some_var.load(Ordering::SeqCst), 5);
```

--------------------------------

### Implement From<Option<T>> for DoOrDiscard<T>

Source: https://docs.rs/prodash/31.0.0/prodash/progress/struct.DoOrDiscard.html

Enables creating a `DoOrDiscard<T>` directly from an `Option<T>`, where `T` must implement `NestedProgress`. This is the primary way to construct a `DoOrDiscard`.

```rust
fn from(p: Option<T>) -> Self
```

--------------------------------

### fn show_throughput_with

Source: https://docs.rs/prodash/31.0.0/prodash/trait.Progress.html

Prints throughput information with specified step, unit, and message level.

```APIDOC
## fn show_throughput_with

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

### Parameters
- **start** (Instant) - Description: The starting point in time for calculating throughput.
- **step** (Step) - Description: The number of steps completed.
- **unit** (Unit) - Description: The unit of measurement for the steps.
- **level** (MessageLevel) - Description: The message level for the throughput information.
```

--------------------------------

### Get Key Level

Source: https://docs.rs/prodash/31.0.0/prodash/progress/struct.Key.html

Retrieves the current depth or level of a Key within the hierarchy. This indicates how many path components are present.

```rust
pub fn level(&self) -> Level
```

--------------------------------

### compare

Source: https://docs.rs/prodash/31.0.0/prodash/progress/key/struct.Key.html

Compares the current key with another key and returns their ordering.

```APIDOC
## compare

### Description
Compares self to `key` and return their ordering.

### Method
`compare(&self, key: &K) -> Ordering`
```

--------------------------------

### Get Type ID of Message

Source: https://docs.rs/prodash/31.0.0/prodash/messages/struct.Message.html

Retrieves the TypeId of the Message struct. This is part of the Any trait implementation and is used for runtime type identification.

```rust
fn type_id(&self) -> TypeId
```

--------------------------------

### Get Minimum of Two Mode Instances

Source: https://docs.rs/prodash/31.0.0/prodash/unit/display/struct.Mode.html

Compares two Mode instances and returns the minimum of the two. This is part of the Ord trait implementation.

```rust
fn min(self, other: Self) -> Self
where Self: Sized,
```

--------------------------------

### Key Partial Ordering Implementations

Source: https://docs.rs/prodash/31.0.0/prodash/progress/struct.Key.html

Provides partial ordering for Keys, enabling comparisons like less than, greater than, less than or equal to, and greater than or equal to.

```rust
fn partial_cmp(&self, other: &Key) -> Option<Ordering>
```

```rust
fn lt(&self, other: &Rhs) -> bool
```

```rust
fn le(&self, other: &Rhs) -> bool
```

```rust
fn gt(&self, other: &Rhs) -> bool
```

```rust
fn ge(&self, other: &Rhs) -> bool
```

--------------------------------

### Get Maximum of Two Mode Instances

Source: https://docs.rs/prodash/31.0.0/prodash/unit/display/struct.Mode.html

Compares two Mode instances and returns the maximum of the two. This is part of the Ord trait implementation.

```rust
fn max(self, other: Self) -> Self
where Self: Sized,
```

--------------------------------

### Log a simple info message

Source: https://docs.rs/prodash/31.0.0/prodash/macro.info.html

Use this snippet to log a basic info message with arguments. Ensure the `log` crate is imported.

```rust
use log::info;

let conn_info = Connection { port: 40, speed: 3.20 };

info!("Connected to port {} at {} Mb/s", conn_info.port, conn_info.speed);
```

--------------------------------

### Implement Count for BoxedProgress

Source: https://docs.rs/prodash/31.0.0/prodash/type.BoxedProgress.html

Provides implementations for the Count trait on BoxedProgress, enabling operations like setting, getting, and incrementing progress steps.

```rust
impl Count for BoxedProgress {
    fn set(&self, step: Step) {
        // ...
    }
    fn step(&self) -> Step {
        // ...
    }
    fn inc_by(&self, step: Step) {
        // ...
    }
    fn inc(&self) {
        // ...
    }
    fn counter(&self) -> StepShared {
        // ...
    }
}
```

--------------------------------

### Initialize Log Progress

Source: https://docs.rs/prodash/31.0.0/prodash/progress/struct.Log.html

Initializes the Log item with an optional maximum value and unit. This prepares the progress tracker for receiving updates.

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

--------------------------------

### Instantiate Scales with SI keys

Source: https://docs.rs/prodash/31.0.0/prodash/unit/human/struct.Scales.html

Use this to create a new Scales instance with standard SI prefixes. This is the default behavior for many scaling operations.

```rust
pub fn new() -> Scales
```

```rust
pub fn SI() -> Scales
```

--------------------------------

### Get Mutable Sibling Location by Level

Source: https://docs.rs/prodash/31.0.0/prodash/progress/key/struct.Adjacency.html

Retrieves a mutable reference to the SiblingLocation at a specific hierarchical level. Returns None if the level is out of bounds.

```rust
pub fn get_mut(&mut self, level: Level) -> Option<&mut SiblingLocation>
```

--------------------------------

### AtomicUsize::new

Source: https://docs.rs/prodash/31.0.0/prodash/progress/type.AtomicStep.html

Creates a new `AtomicUsize` with the specified initial value.

```APIDOC
## pub const fn new(v: usize) -> AtomicUsize

### Description
Creates a new atomic integer.

### Examples
```rust
use std::sync::atomic::AtomicUsize;

let atomic_forty_two = AtomicUsize::new(42);
```
```

--------------------------------

### fn info

Source: https://docs.rs/prodash/31.0.0/prodash/trait.Progress.html

Creates an informational message about the progress made so far.

```APIDOC
## fn info

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

### Parameters
- **message** (String) - Description: The informational message content.
```

--------------------------------

### Human::new

Source: https://docs.rs/prodash/31.0.0/prodash/unit/struct.Human.html

A convenience constructor for creating a new `Human` instance. It initializes the `formatter` and `name` fields.

```APIDOC
### impl Human

#### pub fn new(formatter: Formatter, name: &'static str) -> Self

A convenience method to create a new new instance and its `formatter` and `name` fields.
```

--------------------------------

### Get Sorted Snapshot of Progress Tree

Source: https://docs.rs/prodash/31.0.0/prodash/tree/struct.Root.html

Copies the entire progress tree into a provided vector, ordered by hierarchy. This allows for sequential traversal of all tasks.

```rust
pub fn sorted_snapshot(&self, out: &mut Vec<(Key, Task)>)
```

--------------------------------

### Options Struct

Source: https://docs.rs/prodash/31.0.0/prodash/render/tui/struct.Options.html

Defines the configuration options for the terminal user interface.

```APIDOC
## Struct Options

Configure the terminal user interface

### Fields

*   `title`: String - The initial title to show for the whole window.
*   `frames_per_second`: f32 - The amount of frames to draw per second.
*   `throughput`: bool - If true, enables throughput tracking.
*   `recompute_column_width_every_nth_frame`: Option<usize> - If set, recompute the column width of the task tree only every given frame.
*   `window_size`: Option<Rect> - The initial window size.
*   `stop_if_progress_missing`: bool - If true, stop running the TUI once the progress isn’t available anymore.
```

--------------------------------

### Experimental Clone to Uninit

Source: https://docs.rs/prodash/31.0.0/prodash/unit/struct.Bytes.html

Performs copy-assignment from self to dest. This is a nightly-only experimental API.

```rust
unsafe fn clone_to_uninit(&self, dest: *mut u8)

```

--------------------------------

### Progress Trait Methods

Source: https://docs.rs/prodash/31.0.0/prodash/tree/struct.Item.html

Core methods for initializing and managing progress.

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

### Description
Initialize the Item for receiving progress information.

### Method
`init`

### Parameters
- `max` (Option<Step>) - The maximum value for the progress.
- `unit` (Option<Unit>) - The unit of measurement for the progress.

### Request Example
```rust
item.init(Some(100), Some("tasks".to_string()));
```

### Response
This method does not return a value.
```

```APIDOC
## fn unit(&self) -> Option<Unit>

### Description
Returns the (cloned) unit associated with this Progress.

### Method
`unit`

### Parameters
None.

### Response
- `Option<Unit>` - The unit of measurement for the progress, if set.
```

```APIDOC
## fn max(&self) -> Option<usize>

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

### Method
`max`

### Parameters
None.

### Response
- `Option<usize>` - The maximum progress value, if set.
```

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

### Description
Set the maximum value to `max` and return the old maximum value.

### Method
`set_max`

### Parameters
- `max` (Option<Step>) - The new maximum value for the progress.

### Request Example
```rust
let old_max = item.set_max(Some(200));
```

### Response
- `Option<Step>` - The previous maximum progress value.
```

```APIDOC
## fn set_name(&mut self, name: String)

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

### Method
`set_name`

### Parameters
- `name` (String) - The new name for the progress instance.

### Request Example
```rust
item.set_name("Processing Data".to_string());
```

### Response
This method does not return a value.
```

```APIDOC
## fn name(&self) -> Option<String>

### Description
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’.

### Method
`name`

### Parameters
None.

### Response
- `Option<String>` - The name of the progress instance, if set.
```

```APIDOC
## fn id(&self) -> Id

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

### Method
`id`

### Parameters
None.

### Response
- `Id` - A stable identifier for the progress instance.
```

```APIDOC
## fn message(&self, level: MessageLevel, message: String)

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

### Method
`message`

### Parameters
- `level` (MessageLevel) - The severity level of the message.
- `message` (String) - The content of the message.

### Request Example
```rust
item.message(MessageLevel::Warning, "Potential issue detected.".to_string());
```

### Response
This method does not return a value.
```

```APIDOC
## fn info(&self, message: String)

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

### Method
`info`

### Parameters
- `message` (String) - The informational message.

### Request Example
```rust
item.info("Completed initial setup.".to_string());
```

### Response
This method does not return a value.
```

```APIDOC
## fn done(&self, message: String)

### Description
Create a message indicating the task is done successfully.

### Method
`done`

### Parameters
- `message` (String) - The success message.

### Request Example
```rust
item.done("Task completed successfully.".to_string());
```

### Response
This method does not return a value.
```

```APIDOC
## fn fail(&self, message: String)

### Description
Create a message indicating the task failed.

### Method
`fail`

### Parameters
- `message` (String) - The failure message.

### Request Example
```rust
item.fail("Task failed to complete.".to_string());
```

### Response
This method does not return a value.
```

```APIDOC
## fn show_throughput(&self, start: Instant)

### Description
A shorthand to print throughput information.

### Method
`show_throughput`

### Parameters
- `start` (Instant) - The starting time for throughput calculation.

### Request Example
```rust
use std::time::Instant;
let start_time = Instant::now();
// ... perform some work ...
item.show_throughput(start_time);
```

### Response
This method does not return a value.
```

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

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

### Method
`show_throughput_with`

### Parameters
- `start` (Instant) - The starting time for throughput calculation.
- `step` (Step) - The number of steps completed.
- `unit` (Unit) - The unit of measurement for the progress.
- `level` (MessageLevel) - The message level for the throughput information.

### Request Example
```rust
use std::time::Instant;
let start_time = Instant::now();
item.show_throughput_with(start_time, 100, "items".to_string(), MessageLevel::Info);
```

### Response
This method does not return a value.
```

--------------------------------

### Initialize Progress Item

Source: https://docs.rs/prodash/31.0.0/prodash/tree/struct.Item.html

Initializes an Item for progress tracking. Use `max` to set an upper bound for progress and `unit` for display purposes. If not called, the Item acts as an organizational unit.

```rust
progress.init(Some(10), Some("elements".into()));
```

--------------------------------

### Get Current Number of Tasks

Source: https://docs.rs/prodash/31.0.0/prodash/tree/struct.Root.html

Returns an estimated count of the current `Item`s stored in the tree. Note that this is a best-effort guess due to potential parallel modifications.

```rust
pub fn num_tasks(&self) -> usize
```

--------------------------------

### Format current datetime with seconds

Source: https://docs.rs/prodash/31.0.0/prodash/time/fn.format_now_datetime_seconds.html

Use this function to get a string representation of the current local time, including seconds. Ensure the `localtime` feature is enabled.

```rust
pub fn format_now_datetime_seconds() -> String
```

--------------------------------

### Create Mode with Percentage Only

Source: https://docs.rs/prodash/31.0.0/prodash/unit/display/struct.Mode.html

Initializes a new Mode instance configured to display only the percentage.

```rust
pub fn with_percentage() -> Self
```

--------------------------------

### UnitDisplay Methods for Display Control

Source: https://docs.rs/prodash/31.0.0/prodash/unit/display/struct.UnitDisplay.html

Provides methods to control the display output of UnitDisplay. Use `all` to show both values and units, `values` for only values, and `unit` for only units.

```rust
pub fn all(&mut self) -> &Self
```

```rust
pub fn values(&mut self) -> &Self
```

```rust
pub fn unit(&mut self) -> &Self
```

--------------------------------

### compare

Source: https://docs.rs/prodash/31.0.0/prodash/unit/struct.Duration.html

Compares the Duration struct with a given key and returns their ordering.

```APIDOC
## compare

### Description
Compare self to `key` and return their ordering.

### Method
`compare(&self, key: &K) -> Ordering`
```

--------------------------------

### Update Progress and Get Throughput

Source: https://docs.rs/prodash/31.0.0/prodash/struct.Throughput.html

Looks up or creates a progress value for a given key, sets its current progress, and returns the computed throughput. Use this to track and report progress.

```rust
pub fn update_and_get( &mut self, key: &Key, progress: Option<&Value>, ) -> Option<Throughput>
```

--------------------------------

### Show Throughput with Details

Source: https://docs.rs/prodash/31.0.0/prodash/progress/struct.Log.html

Prints throughput information with specified step, unit, and message level.

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

--------------------------------

### impl Default for Options

Source: https://docs.rs/prodash/31.0.0/prodash/render/line/struct.Options.html

Provides default value initialization for the Options struct.

```APIDOC
## impl Default for Options

### default

#### Description
Returns the “default value” for a type.

#### Method
`fn default() -> Self`
```

--------------------------------

### TryFrom

Source: https://docs.rs/prodash/31.0.0/prodash/render/line/struct.Options.html

Enables attempting to convert one type into another, returning a Result.

```APIDOC
## TryFrom

### Description
Enables attempting to convert one type into another, returning a `Result`.

### Associated Types
* `Error = Infallible`: The type returned in the event of a conversion error.

### Methods
* `try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>`: Performs the conversion.
```

--------------------------------

### From Options to Arc<Root>

Source: https://docs.rs/prodash/31.0.0/prodash/tree/root/struct.Options.html

Converts an Options struct into an Arc<Root> instance.

```rust
fn from(opts: Options) -> Self
```

--------------------------------

### Log::new

Source: https://docs.rs/prodash/31.0.0/prodash/progress/struct.Log.html

Creates a new instance of the Log struct. It takes a name for the progress log and an optional maximum level to control the verbosity of progress information displayed.

```APIDOC
## Log::new

### Description
Create a new instance from `name` while displaying progress information only up to `max_level`.

### Signature
`pub fn new(name: impl Into<String>, max_level: Option<usize>) -> Self`

### Parameters
* `name` - The name of the progress log.
* `max_level` - An optional maximum level to filter progress messages.
```

--------------------------------

### Get Non-Atomic Slice Access from &mut [AtomicUsize] (Nightly)

Source: https://docs.rs/prodash/31.0.0/prodash/progress/type.AtomicStep.html

Allows non-atomic access to a mutable slice of AtomicUsize. This experimental API requires nightly Rust and ensures no concurrent access to the slice.

```rust
#![feature(atomic_from_mut)]
use std::sync::atomic::{AtomicUsize, Ordering};

let mut some_ints = [const { AtomicUsize::new(0) }; 10];

let view: &mut [usize] = AtomicUsize::get_mut_slice(&mut some_ints);
assert_eq!(view, [0; 10]);
view
    .iter_mut()
    .enumerate()
    .for_each(|(idx, int)| *int = idx as _);

std::thread::scope(|s| {
    some_ints
        .iter()
        .enumerate()
        .for_each(|(idx, int)| {
            s.spawn(move || assert_eq!(int.load(Ordering::Relaxed), idx as _));
        })
});
```

--------------------------------

### Get Atomic Access to &mut usize (Nightly)

Source: https://docs.rs/prodash/31.0.0/prodash/progress/type.AtomicStep.html

Provides atomic access to a mutable reference to a usize. This experimental API requires nightly Rust and is only available on targets where AtomicUsize has the same alignment as usize.

```rust
#![feature(atomic_from_mut)]
use std::sync::atomic::{AtomicUsize, Ordering};

let mut some_int = 123;
let a = AtomicUsize::from_mut(&mut some_int);
a.store(100, Ordering::Relaxed);
assert_eq!(some_int, 100);
```

--------------------------------

### Define the info macro

Source: https://docs.rs/prodash/31.0.0/prodash/macro.info.html

This is the definition of the `info` macro, showing its different argument patterns.

```rust
macro_rules! info {
    (logger: $logger:expr, target: $target:expr, $($arg:tt)+) => { ... };
    (logger: $logger:expr, $($arg:tt)+) => { ... };
    (target: $target:expr, $($arg:tt)+) => { ... };
    ($($arg:tt)+) => { ... };
}
```

--------------------------------

### Display Unit with Configurable Options

Source: https://docs.rs/prodash/31.0.0/prodash/struct.Unit.html

Creates a representation of the Unit that implements Display. It allows for configurable display of current progress, an optional upper bound, and throughput.

```rust
pub fn display( &self, current_value: Step, upper_bound: Option<Step>, throughput: impl Into<Option<Throughput>>, ) -> UnitDisplay<'_>
```
Tokens:
Raw