progress-token 0.1.0

A library for tracking progress of long-running tasks
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131

# progress-token


A Rust library for hierarchical progress tracking with support for cancellation, status updates, and nested operations.

[![Crates.io](https://img.shields.io/crates/v/progress-token.svg)](https://crates.io/crates/progress-token)
[![Documentation](https://docs.rs/progress-token/badge.svg)](https://docs.rs/progress-token)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

## 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`:

```toml
[dependencies]
progress-token = "0.1.0"
```

## Quick Start


```rust
use progress_token::ProgressToken;

#[tokio::main]

async fn main() {
    // Create a root progress token
    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
    
    // Subscribe to progress updates
    let mut updates = root.subscribe();
    
    // Update progress as work is done
    process.progress(0.5);  // Root progress becomes 0.35 (0.5 * 0.7)
    process.status("Processing file 1/10");
    
    cleanup.progress(1.0);  // Root progress becomes 0.65 (0.35 + 1.0 * 0.3)
    cleanup.status("Cleanup complete");
}
```

## Usage Examples


### Basic Progress Tracking


```rust
let token = ProgressToken::new("Processing files");

// Update progress
token.progress(0.25);
token.status("Processing file 1/4");

// Mark as complete when done
token.complete();
```

### Status Updates


Status messages propagate through the hierarchy, with the most specific (deepest) status being reported:

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

### Progress Subscription


```rust
let token = ProgressToken::new("Long operation");
let mut updates = token.subscribe();

tokio::spawn(async move {
    while let Some(update) = updates.next().await {
        println!(
            "Progress: {:?}, Current status: {}", 
            update.progress,
            update.status()
        );
    }
});
```

### Cancellation


```rust
let token = ProgressToken::new("Cancellable operation");

// In one part of your code
if error_condition {
    token.cancel(); // Cancels this token and all children
}

// In another part
if token.is_cancelled() {
    return;
}
```

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

## License


This project is licensed under the MIT License - see the [LICENSE.md](LICENSE.md) file for details.