Async & Concurrency

Core Question

Is this I/O-bound (async) or CPU-bound (threads/spawn_blocking)?

Async is for waiting on external things (network, disk, timers). CPU-heavy work blocks the runtime — move it to spawn_blocking or a dedicated thread pool.

Error → Design Question

Quick Decisions

Channel Selection

Always use bounded channels unless you have a specific reason not to. Unbounded channels grow without limit when producer outpaces consumer.

Buffer sizing: start with num_producers * 2 or expected burst size. Monitor with capacity() and len().

The Lock-Across-Await Problem

Never hold a std::sync::Mutex guard across an .await:

// Bad: guard held across await — can deadlock
let mut guard = data.lock().unwrap();
*guard = fetch().await;

// Good: extract, await, then lock again
let current = data.lock().unwrap().clone();
let new_data = process(current).await;
*data.lock().unwrap() = new_data;

tokio::sync::Mutex is await-safe but has higher overhead. Prefer restructuring to avoid holding locks across await entirely.

Usage Scenarios

Scenario 1: "I need to make 5 HTTP requests and combine the results" → Use tokio::try_join! for a fixed number, or JoinSet for a dynamic number. Don't await them sequentially — that's 5x slower.

Scenario 2: "My async task needs to do JSON parsing on large payloads" → JSON parsing is CPU-bound. Use spawn_blocking(move || serde_json::from_str(&data)) to avoid blocking the runtime.

Scenario 3: "I need to shut down gracefully when Ctrl+C is pressed" → Create a CancellationToken, pass child tokens to tasks, and use tokio::select! to race work against token.cancelled(). On signal, cancel the root token.

Reference Files

Cross-References