Async Rust with Tokio

Runtime patterns + common foot-guns.

When to use

New binary: #[tokio::main] (multi-thread) or #[tokio::main(flavor = "current_thread")] for single-thread / WASM
New lib: don't pull in tokio — return impl Future and let callers pick a runtime
Spawn long-running task: tokio::spawn(async move { ... })
Run blocking code: tokio::task::spawn_blocking(|| ...) — NEVER call blocking sync APIs (std::fs, std::thread::sleep) inside an async fn on the main runtime
Cancel a task: drop the JoinHandle or use tokio::select! { _ = cancel_rx => ..., r = work => ... }
Channels: tokio::sync::mpsc (multi-producer), oneshot (single message), broadcast (fanout), watch (latest-value)
Async mutex only when you .await while holding the lock — otherwise use std::sync::Mutex