Tokio

Tokio is the runtime behind async Rust in Rust. The part worth remembering is not "async equals fast." The real split is:

tokio::join! gives concurrency inside one parent task — see Concurrent Is Not Parallel
tokio::spawn gives the runtime an independent task it can schedule across worker threads
tokio::task::spawn_blocking keeps synchronous or CPU-heavy work off the async worker pool

This page is the hub. The load-bearing rules each have their own atomic note.

Rules I want to keep

Size throughput by worker threads. Do not treat #[tokio::main] as a bonus worker for parallelism math.
Classify the work first — async I/O, short CPU, bounded blocking, long-lived blocking, or heavy CPU parallelism. See Classify Async Work Before Refactoring.
Concurrent is not parallel. Use join! for a small fixed set of async I/O operations; use spawn when work should become its own task and may benefit from multi-thread scheduling. See Concurrent Is Not Parallel.
Bound the fan-out. Default to JoinSet plus a Semaphore, not unbounded spawn storms. See Bounded Concurrency First.
Protect the hot path from the warm path. Background work should have its own bounds, freshness rules, and downstream isolation. See Hot Path vs Warm Path and Priority Lanes Need Downstream Isolation.
Never hold a mutex guard across .await. See Don't Hold a Lock Across Await.
Prefer std::sync::Mutex or parking_lot::Mutex for short sync critical sections.
Use tokio::sync::Mutex only when the guarded operation truly has to cross .await.
Use spawn_blocking for bounded sync or CPU-heavy work.
Use a dedicated std::thread::spawn worker for long-lived blocking loops.

Good places to parallelize:

Bad places to parallelize:

tiny operations where spawn overhead dominates
paths that still serialize on one lock or one writer
anything that holds search, semantic, or similar shared state longer than necessary

Repo reference guide: docs/reference/tokio-runtime-guide.md