Async Operations · 20 min · free lesson

Bound Work Before Spawning

Put the limit before the expensive resource allocation, not after an unbounded queue has formed.

Core idea

A concurrency limit and a queue-size limit protect different resources.

Diagram for Bound Work Before Spawning: a Rust code example flows to the lesson rule and the key observation.
Semaphore permits and bounded queues

Understand it

A semaphore grants a finite number of permits. Holding a permit across the protected operation bounds the number of simultaneous operations. The important design question is where that permit is acquired. Spawning a million tasks that each wait for a permit still allocates a million waiting tasks; the semaphore has limited active work but has not bounded queued memory.

Acquire an owned permit before spawning each job when the producer should wait for capacity. Move the permit into the task and let it drop when that task finishes. This is backpressure: a fast producer cannot keep advancing independently of the consumer capacity. For a long-lived producer/consumer system, use a bounded channel as well, and decide whether a full queue waits, rejects, or drops according to the product's contract.

The example has six small jobs and two permits. It drains the JoinSet after submission and checks that every job completed. Because the runtime is current-thread, waiting for a permit yields so earlier jobs can run. Real I/O can overlap, but CPU-bound work does not become parallel here. A permit must cover the resource usage you intend to limit; releasing it before the expensive operation defeats that limit.

Test the policy using observable counters and an explicit barrier or yield, not timing guesses. Assert that the active count never exceeds the permit count and that every acquired permit is eventually returned after error paths. Do not use a zero-permit semaphore as a normal concurrency setting unless some other component will intentionally release capacity.

Local Cargo profile: open the supplied project in Crabrix or the browser Playground. Explicitly prepare its pinned Cargo packages once on each device, then Run and Debug compile and execute on that device without a backend. The project includes Cargo.lock. The lesson question remains the completion exercise; running an unchanged demonstration does not prove a separate programming challenge. Tokio 1.54.1 is built with default-features=false and only rt/sync. The current-thread builder needs no runtime attribute macro. JoinSet, Semaphore, watch and yield_now are real Tokio APIs. This profile supplies cooperative concurrency, not native threads, sockets, OS signals or CPU parallelism.

Read the code

use std::sync::Arc;
use tokio::{
    runtime::Builder, sync::Semaphore,
    task::JoinSet,
};
fn main() {
    Builder::new_current_thread()
        .build()
        .unwrap()
        .block_on(async {
            let limit = Arc::new(Semaphore::new(2));
            let mut tasks = JoinSet::new();
            for n in 0..6 {
                let permit = limit
                    .clone()
                    .acquire_owned()
                    .await
                    .unwrap();
                tasks.spawn(async move {
                    let _permit = permit;
                    tokio::task::yield_now().await;
                    n * 2
                });
            }
            let mut results = Vec::new();
            while let Some(value) =
                tasks.join_next().await
            {
                results.push(value.unwrap());
            }
            results.sort_unstable();
            assert_eq!(
                results,
                [0, 2, 4, 6, 8, 10]
            );
            assert_eq!(
                limit.available_permits(),
                2
            );
        });
    println!("semaphore-backpressure: ok");
}

Semaphore permits and bounded queues

Open local example in Playground ↗

Try it

Run the declared desktop Cargo example. Instrument active work and verify a peak no greater than two without relying on sleeps. Open the supplied local Cargo project, prepare packages, then Run or Debug it. Change inputs and examine the assertions. Answer the lesson question separately.

What success looks like: Bound production before spawning or use a bounded queue; limiting active work alone does not limit waiting tasks.

Check your understanding

Does acquiring a permit inside each of a million already-spawned tasks bound queued-task memory?

Reveal the answer
  1. No; active work is bounded, but all those waiting tasks still exist
  2. Yes; waiting tasks consume no memory
  3. Only when the jobs return integers

Bound production before spawning or use a bounded queue; limiting active work alone does not limit waiting tasks.

Go deeper

Common misconception: A semaphore automatically bounds every allocation in a pipeline.

Capacity must be applied at the relevant allocation boundary and combined with a queue policy.

  1. Reserve: Await capacity before creating another task.
  2. Hold: Move the owned permit into the protected operation.
  3. Release: Let RAII return capacity on success and ordinary error paths.

Transfer challenge: Add a bounded channel between input and workers, then specify what the UI should do when the channel is full.

Connections

  • Own Tasks with JoinSet: Completion order, errors, and task lifetime
  • A Graceful Shutdown Protocol: Stop admission, signal, and wait