rust-async-concurrency

It also covers the async-fn-in-traits Send problem — why async fn in traits does not give Send futures by default and how to work around it.

Out of scope: HTTP service structure (routing, extractors, middleware) is owned by rust-web-backend; sync-only ownership and borrowing questions belong to rust-core-language.

Rust Async & Concurrency

Agent Workflow (MANDATORY)

Before writing async code, spawn in parallel:

1. fuse-ai-pilot:explore-codebase — find the existing runtime, channel, and lock patterns already in use
2. fuse-ai-pilot:research-expert — verify current tokio/crate APIs via Context7/Exa (async APIs churn)
3. mcp__context7__query-docs — pull exact signatures for the primitives you touch

After writing, run fuse-ai-pilot:sniper.

---

Runtime Landscape

Runtime	Reality
tokio	The de-facto standard. Almost every async crate (axum, sqlx, reqwest, tonic) targets it. Default choice.
async-std	Niche, effectively in maintenance mode. Do not pick for new work.
smol	Niche, small/embeddable. Only for constrained or embedded contexts.

Default to tokio unless a hard constraint says otherwise.

---

Critical Rules

1. std::sync::Mutex first — it is faster. Reach for tokio::sync::Mutex ONLY when the guard must be held across an .await. Otherwise scope the guard so its destructor runs before the await.
2. Arc<Mutex<T>> is not the default — analyze contention first. Read-dominated → RwLock; a simple counter → atomics; work that is itself async → a task + message passing.
3. Never drop a JoinHandle you care about — a dropped tokio::spawn handle silently swallows the task's panic/error. .await it, or use JoinSet/tracing to surface failures.
4. spawn_blocking for heavy sync work — CPU-bound loops or blocking I/O (std file, blocking DB driver) starve the runtime if run on an async worker. Offload them.
5. Send across .await — everything held across an await point must be Send for tokio::spawn. A std::sync::MutexGuard is NOT Send; holding one across an await is a compile error (and async-mutex guards that are Send deadlock instead).