Crate progress_token

A hierarchical progress tracking library that allows monitoring and reporting progress of long-running tasks with support for cancellation, status updates, and nested operations.

Overview

This library provides a ProgressToken type that combines progress tracking, status updates, and cancellation into a single unified interface. Unlike a basic CancellationToken, ProgressToken supports:

• Hierarchical progress tracking with weighted child operations
• Status message updates that propagate through the hierarchy
• Both determinate (0.0-1.0) and indeterminate progress states
• Multiple subscribers for progress/status updates
• Automatic progress aggregation from child tasks

Examples

Basic usage with progress updates:

use progress_token::ProgressToken;

#[tokio::main]
async fn main() {
    // Create a root token
    let token = ProgressToken::new("Processing files");
     
    // Update progress as work is done
    token.progress(0.25);
    token.status("Processing file 1/4");
     
    // Subscribe to updates
    let mut updates = token.subscribe();
    while let Some(update) = updates.next().await {
        println!("Progress: {:?}, Status: {}", 
            update.progress, 
            update.status());
    }
}

Using hierarchical progress with weighted child tasks:

use progress_token::ProgressToken;

#[tokio::main]
async fn main() {
    let root = ProgressToken::new("Main task");
     
    // Create child tasks with weights
    let process = ProgressToken::child(&root, 0.7, "Processing"); // 70% of total
    let cleanup = ProgressToken::child(&root, 0.3, "Cleanup");    // 30% of total
     
    // Child progress is automatically weighted and propagated
    process.progress(0.5);  // Root progress becomes 0.35 (0.5 * 0.7)
    cleanup.progress(1.0);  // Root progress becomes 0.65 (0.35 + 1.0 * 0.3)
}

Status Updates

The status feature allows tracking the current operation being performed. Status messages propagate up through the hierarchy, with the most specific (deepest) status being reported:

use progress_token::ProgressToken;

#[tokio::main]
async fn main() {
    let root = ProgressToken::new("Backup");
    let compress = ProgressToken::child(&root, 1.0, "Compressing files");
     
    // Update status with more specific information
    compress.status("Compressing images/photo1.jpg");
     
    // Get full status hierarchy
    let statuses = root.statuses();
    assert_eq!(statuses, vec![
        "Backup",
        "Compressing files", 
        "Compressing images/photo1.jpg"
    ]);
}

Differences from CancellationToken

While this library includes cancellation support, ProgressToken provides several advantages over a basic CancellationToken:

• Rich Status Information: Track not just whether an operation is cancelled, but its current progress and status.
• Hierarchical Structure: Create trees of operations where progress and cancellation flow naturally through parent-child relationships.
• Progress Aggregation: Automatically calculate overall progress from weighted child tasks instead of managing it manually.
• Multiple Subscribers: Allow multiple parts of your application to monitor progress through the subscription system.
• Determinate/Indeterminate States: Handle both measurable progress and operations where progress cannot be determined.

Implementation Notes

• Progress values are automatically clamped to the range 0.0-1.0
• Child task weights should sum to 1.0 for accurate progress calculation
• Status updates and progress changes are broadcast to all subscribers
• Completed or cancelled tokens ignore further progress/status updates
• The broadcast channel has a reasonable buffer size to prevent lagging

Structs

ProgressStream

A Stream that yields progress updates from a token

ProgressToken

A token that tracks the progress of a task and can be organized hierarchically

ProgressUpdate

Data for a progress update event

WaitForUpdateFuture

A Future that is resolved once the corresponding ProgressToken is updated. Resolves to None if the progress token is cancelled.

Enums

Progress

Represents either a determinate progress value or indeterminate state

ProgressError