Apache Asyncband (Incubating)

Asyncband is a focused collection of composable, runtime-agnostic concurrency building blocks for async Rust. It provides synchronization, initialization, task coordination, channels, resource reuse, and workload control without choosing an executor for the application.

Asyncband's async APIs are built on standard futures and wakers. The library does not spawn tasks, own worker threads, install timers, or require a reactor or I/O driver. Applications can poll its futures with Tokio, async-std, smol, a custom executor, or any other standards-based runtime, and compose runtime services such as deadlines around them.

The project is not limited to small or stateless synchronization primitives. Stateful utilities such as a singleflight group or an object pool fit when they provide a generally reusable coordination mechanism and remain independent of executor policy.

The boundary is mechanism versus policy. Task placement, timers, deadlines, retries, periodic maintenance, and application lifecycle orchestration stay with the caller and its runtime. Potential future-concurrency or scheduling APIs are evaluated against the same boundary: they must remain executor-independent and compose with caller-owned execution and timing.

The crate enables no APIs by default. Enable only the features your application uses:

cargo add asyncband --features mutex,oneshot

use asyncband::mutex::Mutex;

async fn increment() {
    let counter = Mutex::new(0);
    *counter.lock().await += 1;
    assert_eq!(*counter.lock().await, 1);
}

Public paths stay direct—such as asyncband::mutex, asyncband::pool, and asyncband::once::OnceCell—while Cargo features keep unused implementations out of the build.

The optional blocking module is a boundary adapter for synchronous callers. It parks the calling thread while driving one future; it is not a general-purpose executor.

cargo add asyncband --features blocking

use std::time::Duration;

use asyncband::blocking::FutureExt as _;

let value = async { 42 }.block_on();
assert_eq!(value, 42);

let value = async { 42 }.wait_timeout(Duration::ZERO);
assert_eq!(value, Some(42));

Async and synchronous synchronization primitives have different optimization constraints. Once an async operation is exposed as a runtime-agnostic future, synchronous code can usually drive that future through a block_on adapter. Asyncband therefore designs its primitives for async use and provides blocking interoperability at the boundary instead of duplicating synchronous methods across every type.

A sync-first implementation can exploit OS- or platform-specific facilities that an async implementation cannot assume. Libraries focused on synchronous code can therefore make different and sometimes better tradeoffs. Asyncband leaves those optimizations to dedicated libraries rather than treating blocking adaptation as a second family of primitives.

The blocking module is a lightweight, thread-parking single-future executor, not a general-purpose async runtime. wait_timeout drops the future on timeout. Futures that depend on a runtime-specific timer or I/O driver still need that runtime's driver to make progress, and blocking an executor thread can cause starvation or deadlocks. See the blocking module documentation for the full contract.

Asyncband types implement Send and Sync only when the protected, transferred, or managed value satisfies the necessary bounds. See each API's documentation for its exact contract.

This crate is built against the latest stable release, and its minimum supported rustc version is 1.86.0.

The policy is that the minimum Rust version required to use this crate can be increased in minor version updates. For example, if Asyncband 1.0 requires Rust 1.20.0, then Asyncband 1.0.z for all values of z will also require Rust 1.20.0 or newer. However, Asyncband 1.y for y > 0 may require a newer minimum version of Rust.

This project is licensed under Apache License, Version 2.0.

Apache Asyncband, Asyncband, and Apache are either registered trademarks or trademarks of The Apache Software Foundation in the United States and/or other countries.

See HISTORY.md for the external implementations that informed Asyncband's APIs.