Crate progressor

A modern, async-first progress tracking library for Rust.

This crate provides types and utilities for tracking progress of long-running operations in an async context. It uses Rust’s Stream API to emit progress updates with support for different states (working, paused, completed, cancelled).

Features

• State-aware progress tracking: Support for working, paused, completed, and cancelled states
• Async-first design: Built around Future and Stream APIs
• Zero-cost abstractions: Efficient progress reporting with minimal overhead
• Type-safe: Full Rust type safety with meaningful error messages
• Flexible: Support for current/total values, custom messages, and state management

Examples

Basic usage with the progress tracker:

use progressor::{progress, Progress};
use futures_util::StreamExt;

let task = progress(100, |mut updater| async move {
    for i in 0..=100 {
        // Update progress
        updater.update(i);
         
        // Add messages for important milestones
        if i % 25 == 0 {
            updater.update_with_message(i, format!("Milestone: {}%", i));
        }
    }
    "Task completed!"
});

// Monitor progress concurrently
let mut progress_stream = task.progress();
tokio::select! {
    result = task => {
        println!("Result: {}", result);
    }
    _ = async {
        while let Some(update) = progress_stream.next().await {
            println!("Progress: {}%", (update.completed_fraction() * 100.0) as u32);
            if let Some(message) = update.message() {
                println!("  {}", message);
            }
        }
    } => {}
}

Advanced usage with pause and cancel:

use progressor::{progress, Progress, State};
use futures_util::StreamExt;

let task = progress(100, |mut updater| async move {
    for i in 0..=100 {
        // Update progress
        updater.update(i);
         
        // Pause at 50%
        if i == 50 {
            updater.pause();
            // Simulate some async work during pause
            tokio::time::sleep(tokio::time::Duration::from_millis(100)).await;
        }
    }
    "Task completed!"
});

// Monitor progress and handle different states
let mut progress_stream = task.progress();
while let Some(update) = progress_stream.next().await {
    match update.state() {
        State::Working => println!("Working: {}%", (update.completed_fraction() * 100.0) as u32),
        State::Paused => println!("Paused at {}%", (update.completed_fraction() * 100.0) as u32),
        State::Completed => println!("Completed!"),
        State::Cancelled => println!("Cancelled!"),
    }
}

Structs

ProgressUpdate

Represents a single progress update with current status, total, and optional metadata.

ProgressUpdaterstd

A handle for updating progress during execution of a future.

Enums

State

Represents the state of a progress-tracked operation.

Traits

Progress

A trait for futures that can report progress updates.

Functions

progressstd

Creates a progress-tracked future from a closure.