Runtime independence is shared by both libraries. Tokio documents its synchronization primitives as runtime agnostic, with an exception for methods such as send_timeout that use its timer. Asyncband can also run on a Tokio executor. The choice of synchronization API does not by itself require a change of runtime.

This guide compares Asyncband 0.7.3 with Tokio 1.53.3. Links point to those versions.

Modules and features​

Asyncband has no default features. Enable the primitives your code uses:

asyncband = { version = "0.7.3", features = ["mutex", "semaphore", "once-cell"] }

Types live in their respective modules. For example, Mutex is imported from asyncband::mutex, while OnceCell lives in asyncband::once and requires the once-cell feature. The once feature enables the separate Once primitive.

The following table is a starting point for locating APIs. Paths in the second column are relative to asyncband.

Both libraries use guards to release locks and semaphore permits. Their queued lock and semaphore acquisitions preserve queue order; cancelling an acquisition gives up its place without leaking permits. This does not undo changes made by application code while holding a guard. Both barriers are reusable and designate one leader per generation, but wait is not cancel-safe: if another branch wins and you still intend to wait, retain the same pending future instead of registering another arrival.

Initialization and externally supplied values​

Both libraries provide OnceCell::get_or_init and get_or_try_init. A failed, panicked, or cancelled initialization attempt leaves the cell available for another attempt. There are still call-site differences. Tokio's OnceCell::set is synchronous and can report that initialization is already in progress. Asyncband's set is awaited: it waits for an ongoing attempt, then either stores the supplied value or returns it if the cell has already been initialized.

Tokio also provides SetOnce. One caller supplies a value with set, and other callers can wait for it without supplying an initializer. Asyncband's OnceCell does not have that waiting API. Its completion module serves a related use case: a single-use Completer publishes a value to cloneable Completion observers. Observers receive an Abandoned error if the completer is dropped without publishing. That separation of capabilities and the abandonment result are part of the migration decision; it is not a type rename.

Notifications and shutdown​

Tokio's Notify supports several notification operations. Choose an Asyncband event based on the state that the application needs to retain:

• notify_one() wakes one waiter or stores one permit for a later waiter. AutoResetEvent::set() has the corresponding one-signal behavior. Multiple calls with no waiting consumer coalesce into one stored signal.
• notify_waiters() notifies existing Notified futures, including those created but not yet polled. It does not retain a notification for futures created afterward.
• ManualResetEvent::set() releases current waiters and keeps the event set until reset(). Later waits also pass while it remains set. It suits a persistent readiness condition, but a set()/reset() pair is not a direct replacement for notify_waiters().

For shutdown, retain the shutdown state explicitly. A bare notify_waiters() call made before a task creates its wait future cannot tell that task to stop later. Asyncband's shutdown module combines a persistent request with completion tracking: request_shutdown() records the request for current and future observers, and awaiting the coordinator waits for every ShutdownGuard to be dropped. Workers still decide how to finish their work and release their guards.

Semaphore counts and closure​

Tokio's acquire().await acquires one permit and returns a Result. Asyncband spells the operation acquire(1).await and returns the guard directly, so remove error handling for acquisition when changing that call. Its non-waiting try_acquire(n) returns Option.

This difference follows from the absence of a closed state. Tokio's Semaphore::close makes pending and future acquisitions fail. Asyncband has no corresponding operation. Code that uses closure to stop admission must keep a separate shutdown signal and select between it and acquisition. An acquisition that can never be satisfied still needs to be rejected or given a deadline by the caller.

Permit counts also differ. Tokio accepts usize in new and add_permits, but u32 in acquire_many; its MAX_PERMITS is usize::MAX >> 3 because the representation reserves bits. Asyncband uses usize counts throughout and does not reserve count bits. acquire(n) handles both single- and multi-permit requests, and release(n) adds capacity.

Both libraries let a permit guard forget its permits so that dropping it does not return them. When adjusting capacity without first acquiring a guard, distinguish these operations:

• Tokio's forget_permits(n) and Asyncband's drain_permits(n) remove up to n currently available permits and report the amount removed.
• Asyncband's reduce_permits(n) reduces the logical balance by exactly n. It leaves existing guards valid; if too few permits are available, future returns repay the deficit before ordinary queued acquisitions proceed.

For example, reducing a fully occupied eight-slot budget by three eventually leaves five slots. Draining three at that moment removes zero. Forgetting an acquired guard requires obtaining those permits first, which may itself wait.

Channel behavior​

MPSC constructors and receive results​

Tokio's mpsc::channel(capacity) becomes Asyncband's mpsc::bounded(capacity), and unbounded_channel() becomes unbounded(). Both bounded variants apply backpressure when full. Their receive results differ: Tokio uses Option<T>, with None after the channel drains and closes; Asyncband uses Result<T, RecvError>, reporting disconnection after buffered values drain. Update receive loops and their end-of-stream handling along with the imports.

Broadcast retention​

Tokio's broadcast lets a producer send without waiting for buffer capacity. When its bounded buffer fills, old values are evicted and affected receivers observe RecvError::Lagged.

Asyncband's broadcast::mpmc::bounded retains messages until active receivers have read them or dropped their subscriptions. A slow receiver therefore makes send(value).await wait once the shared backlog fills. There is no lag error, but one receiver that stops draining can stall every producer. Reading a message releases that receiver's claim on buffer capacity; processing it afterward does not hold the slot.

The send result also changes: Asyncband's bounded send returns (), rather than Tokio's result containing a receiver count. With no active receivers, an Asyncband broadcast send retains nothing. The channel design and bounded broadcast discussion describe these retention choices. Before porting, decide whether slow consumers should cause missed messages or producer backpressure.

Watch reads​

Both watch channels retain the latest value and may coalesce intermediate updates. Tokio exposes borrow() and borrow_and_update() guards. Asyncband's get() clones the current value without marking it observed; recv().await waits for an update, clones the latest value, and marks that version observed together. Use recv when the consumer needs the updated value, and consider an Arc<T> payload when cloning the underlying value would be expensive.

Oneshot selection​

Both oneshot channels provide a synchronous send and let the receiver await one value. Tokio's receiver implements Future, so it can be borrowed as &mut receiver in a select!. Asyncband's receiver implements IntoFuture. Call receiver.into_future() once and retain the returned Recv future, then select on &mut recv when the receive should survive another branch winning. Dropping the Asyncband receiver or its receive future disconnects the channel and discards any unread message.

Additional coordination APIs​

Asyncband also provides dedicated APIs for the following tasks:

The useful questions are what one permit represents, which operations share the budget, and how long each operation holds its permits. This post works through those choices with Asyncband's Semaphore, including how Apache OpenDAL and prek use it.

The Asyncband APIs below are from version 0.7.3, with the semaphore feature enabled. The HTTP example uses reqwest; the semaphore itself is runtime-independent.

Share a budget across operations​

Suppose a client should perform at most eight downloads at once. Create one Semaphore::new(8) and share it across the calls that consume that budget. Each download acquires one permit. When all eight are held, another acquisition waits asynchronously until capacity becomes available.

use asyncband::semaphore::Semaphore;

async fn download(
    client: &reqwest::Client,
    slots: &Semaphore,
    url: &str,
) -> Result<Vec<u8>, reqwest::Error> {
    let _permit = slots.acquire(1).await;
    let response = client.get(url).send().await?.error_for_status()?;
    Ok(response.bytes().await?.to_vec())
}

acquire returns a guard. Keeping that guard in _permit holds the slot through the download, including reading the response body. Returning from the function drops the guard and gives the slot back, including on an error. There is no separate success or error branch that needs to release it manually.

The semaphore must live outside the individual calls. Creating a new semaphore inside download would give every call its own eight-slot budget. An Arc<Semaphore> lets independently owned tasks share the same budget; each task can borrow it for acquire or use acquire_owned when the permit itself must own a reference to the semaphore.

This is useful when work comes from several places. Apache OpenDAL's ConcurrentLimitLayer lets multiple operators share an Asyncband semaphore. The hook runner prek similarly passes one semaphore through project runs to limit concurrent hook execution. The scope of the shared semaphore determines the scope of the limit.

Eight slots limit simultaneous downloads. The number completed per second still depends on their duration. A policy expressed in requests per second needs a time-based rate limiter.

Keep the permit with the resource​

In the example above, the download ends when the response body has been read. A streaming API has a different lifetime: it can return a response while the caller is still receiving its body. Releasing a permit when the response is returned would leave that later transfer outside the budget.

OpenDAL handles this at its HTTP transport boundary. When an HTTP concurrency limit is configured, it acquires a permit before sending the request and moves the permit into a wrapper around the response body stream. The stream holds the permit until it is dropped. If sending the request fails, the local permit is dropped instead.

That ownership pattern also applies to a returned buffer or a queued job: put the permit in the object that owns the charged resource. If ownership moves to another task, move the permit with it. The function that acquired the permit may return long before the resource is released.

The download example's returned Vec<u8> illustrates the boundary. Its slot covers the transfer, but the caller can retain the downloaded bytes afterward. Limiting transfers alone does not bound retained memory.

Charge for the size of the work​

A permit can represent a byte of capacity instead of one operation. This matters when a small buffer and a large buffer should consume different amounts of a shared budget.

Here is a standalone example of a fixed payload budget. It reserves capacity before allocating a buffer and keeps the reservation with the returned value:

use std::sync::Arc;

use asyncband::semaphore::{OwnedSemaphorePermit, Semaphore};

struct BufferBudget {
    capacity: usize,
    available: Arc<Semaphore>,
}

struct BudgetedBuffer {
    data: Vec<u8>,
    _permit: OwnedSemaphorePermit,
}

impl BufferBudget {
    fn new(capacity: usize) -> Self {
        Self {
            capacity,
            available: Arc::new(Semaphore::new(capacity)),
        }
    }

    async fn allocate(&self, len: usize) -> Option<BudgetedBuffer> {
        if len > self.capacity {
            return None;
        }

        let permit = self.available.clone().acquire_owned(len).await;
        Some(BudgetedBuffer {
            data: vec![0; len],
            _permit: permit,
        })
    }
}

With BufferBudget::new(8 * 1024 * 1024), the budget covers eight MiB of payload. A 64 KiB allocation charges 64 KiB; a two MiB allocation charges two MiB. The buffer and its reservation can move together between tasks. Dropping the buffer frees its data and returns the permits.

Rejecting a request larger than the entire fixed budget is necessary: returning every outstanding permit could still never satisfy it. Reserve the full amount in one acquisition, too. Acquiring a large reservation incrementally can leave several callers each holding some capacity while all wait for the rest.

This budget counts the payload bytes in these buffers. Allocator overhead, other allocations, and extra copies require their own accounting. Growing or copying a buffer must reserve the additional capacity before doing so.

Decide what happens when capacity runs out​

Waiting is one admission policy. acquire(n).await waits for capacity; try_acquire(n) returns None when it cannot acquire the requested permits immediately. A caller can use the latter to reject or defer work instead of joining the wait queue. A deadline around acquire gives waiting a time limit.

The placement of the acquisition matters. If a program allocates a large payload and only then waits for its permit, that payload already consumes memory outside the budget. Likewise, spawning one task per incoming job and acquiring inside each task limits admitted work while allowing an arbitrarily large population of waiting tasks. Apply admission before creating the resource whose growth you intend to bound, or bound the waiting population separately.

Asyncband assigns permits to queued acquisitions in order. A large acquisition at the front can therefore hold back smaller ones behind it. If a budget has three units left and the first waiter needs five, a later one-unit waiter waits too. This preserves ordering, with a latency cost when request sizes vary substantially.

Dropping a pending acquisition removes it from the queue without leaking permits; retrying joins at the back. After acquisition completes, dropping the permit guard returns its permits. This accounting does not undo application side effects or stop work that has been handed to another task; the task doing that work must retain the permit for its actual lifetime.

Adjust a running budget​

Some applications change their concurrency budget while work is already running. Asyncband provides two operations for this: release(n) adds capacity, and reduce_permits(n) removes exactly n permits from the logical balance. A reduction does not revoke permits that callers already hold. If insufficient permits are currently available, later returns repay the deficit before ordinary queued acquisitions proceed.

For example, suppose an eight-slot budget is fully occupied and its controller reduces it by three. The eight operations can finish normally. As their guards are dropped, three returned permits retire the deficit; after all eight return, five slots remain available. The controller should serialize budget changes so that each adjustment is applied once.

drain_permits(n) only removes permits that are available at the time and returns the number removed. Draining three from that fully occupied budget removes zero, so it cannot promise the same capacity reduction. Also, returning an ordinary guard already restores its permits: an additional release would add capacity a second time.

For a fixed limit, acquiring and dropping guards is enough. Add weighted reservations or capacity adjustments when the resource being controlled calls for them, and keep the permit's lifetime aligned with the work it accounts for.