noworkers

A small, ergonomic Rust crate for spawning and supervising groups of asynchronous “workers” on Tokio.
Manage concurrent tasks with optional limits, cancellation, and first-error propagation.

Inpired by golang (errgroups)

Disclaimer

The library is still new, and as such the API is subject to change, I don't expect changes to the add and wait functions, but the rest may change. I might also move to custom error types, and or removing the tokio_utils entirely to slim down the package. It shouldn't affect the user too much however.

The crate is in production, and has seen extensive use

Features

• Unlimited or bounded concurrency via with_limit(usize).
• Cancellation support with [tokio_util::sync::CancellationToken]—either external (with_cancel) or task-driven (with_cancel_task).
• First-error wins: the first worker to fail cancels the rest and reports its error.
• Graceful shutdown: .wait() awaits all workers, cancels any in-flight tasks, and returns the first error (if any).

Installation

Add to your Cargo.toml:

[dependencies]
noworkers = "0.1"

Then in your code:

use noworkers::Workers;

Quick Example

use noworkers::Workers;

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    // Create a worker group with up to 5 concurrent tasks
    let mut workers = Workers::new();

    // Limit amount of concurrent workers
    workers.with_limit(5);

    // Adds cancellation signal
    workers.with_cancel_task(async move {
      // send cancellation to tasks after 60 seconds
      tokio::time::sleep(std::time::Duration::from_secs(60)).await
    });

    // Spawn 10 async jobs
    for i in 0..10 {
        // Work is done immediatley, so this will wait in two batches of 1 seconds each (because of limit)
        workers.add(move |cancel_token| async move {
            // optional tokio::select, if you use cancellation for your tasks, if not just do your work
            tokio::select! {
                // Do work, in this case just sleep
                _ = tokio::time::sleep(tokio::time::Duration::from_secs(1)) => {
                    println!("Job {i} done");
                    Ok(())
                }
                // If we receive cancel we close
                _ = cancel_token.cancelled() => {
                    println!("Job {i} cancelled");
                    Ok(())
                }
            }
        }).await?;
    }

    // Wait for all to finish or for the first error
    workers.wait().await?;
    Ok(())
}

API Overview

• Workers::new() -> Workers Create a fresh worker group.

• with_limit(limit: usize) -> &mut Self Bound in-flight tasks to limit, back-pressuring .add() calls when full.

• with_cancel(token: &CancellationToken) -> &mut Self Tie this group’s lifetime to an external token.

• with_cancel_task(fut: impl Future<Output=()>) -> &mut Self Spawn a task that, when it completes, cancels the group.

• add<F, Fut>(&self, f: F) -> anyhow::Result<()> Spawn a new worker. f is a closure taking a child CancellationToken and returning Future<Output=anyhow::Result<()>>.

• wait(self) -> anyhow::Result<()> Await all workers. Returns the first error (if any), after cancelling in-flight workers.

Error Handling

• The first worker to return Err(_) wins: its error is sent on a oneshot and all others are cancelled.
• Subsequent errors are ignored.

License

Dual-licensed under MIT or Apache-2.0. See LICENSE-MIT and LICENSE-APACHE for details.

Contribute

Simply create an issue here or pr https://github.com/kjuulh/noworkers.git, development happens publicly at: https://git.kjuulh.io/kjuulh/noworkers.