progress-token
A Rust library for hierarchical progress tracking with support for cancellation, status updates, and nested operations.
Features
- 🌳 Hierarchical Progress: Create trees of operations with weighted progress tracking
- 📢 Status Updates: Track and propagate status messages through the operation hierarchy
- ⏸️ Cancellation: Built-in support for cancelling operations and their children
- 📊 Progress States: Support for both determinate (0.0-1.0) and indeterminate progress
- 🔄 Multiple Subscribers: Allow multiple parts of your application to monitor progress
- 🧮 Automatic Aggregation: Progress automatically calculated from weighted child tasks
Installation
Add this to your Cargo.toml
:
[]
= "0.1.0"
Quick Start
use ProgressToken;
async
Usage Examples
Basic Progress Tracking
let token = new;
// Update progress
token.update_progress;
token.update_status;
// Mark as complete when done - sets progress to 1.0 and prevents further updates
token.complete;
// These updates will be ignored since the token is completed
token.update_progress;
token.update_status;
Automatic Completion with Guards
let token = new;
// Token is automatically completed here
// Or prevent completion by forgetting the guard
let token = new;
Status Updates
Status messages propagate through the hierarchy, with the most specific (deepest) status being reported:
let root = new;
let compress = root.child;
// Update status with more specific information
compress.update_status;
// Get full status hierarchy
let statuses = root.statuses;
assert_eq!;
Progress Subscription
let token = new;
let mut updates = token.subscribe;
spawn;
Cancellation
let token = new;
// In one part of your code
if error_condition
// These updates will be ignored since the token is cancelled
token.update_progress;
token.update_status;
// Check cancellation state
if token.is_cancelled
Convenient Cancellation Checking
The check()
method and ?
operator make it easy to handle cancellation in async functions:
use ;
async
async
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
- Once a token is completed or cancelled, all further updates are ignored
- The broadcast channel has a reasonable buffer size to prevent lagging
- Completion and cancellation are permanent states - they cannot be undone
- When a token is cancelled, all its children are also cancelled
- When a token is completed, its progress is set to 1.0 and no further updates are allowed
License
This project is licensed under the MIT License - see the LICENSE.md file for details.