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:
- fuse-ai-pilot:explore-codebase — find the existing runtime, channel, and lock patterns already in use
- fuse-ai-pilot:research-expert — verify current tokio/crate APIs via Context7/Exa (async APIs churn)
- 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
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.
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.
- 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.
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.
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).
Reference Guide
Concepts
| Topic |
Reference |
When to Consult |
| Runtime & tasks |
runtime-and-tasks.md |
spawn, JoinHandle, JoinSet, spawn_blocking, 'static bound |
| Shared state |
shared-state.md |
Choosing Mutex vs RwLock vs atomics vs actor task |
| Channels |
channels.md |
Picking mpsc / oneshot / broadcast / watch |
| Async traits |
async-traits.md |
async fn in traits + the Send-bound problem |
Templates
| Template |
When to Use |
| task-patterns.md |
Concurrent tasks, JoinSet, actor pattern, spawn_blocking |
| graceful-shutdown.md |
Cancellation, shutdown signal, draining tasks |
Quick Reference
Scope the guard, don't hold it across .await
// GOOD: lock released before the await
{
let mut db = state.lock().unwrap();
db.insert(key, value);
} // guard dropped here
do_async_work().await;
→ See shared-state.md
Pick the channel by shape
// one value back to a caller → oneshot
// many producers, one consumer → mpsc
// fan-out same value to all → broadcast
// latest-value-only state → watch
→ See channels.md
Best Practices
DO
- Measure contention before choosing a lock; prefer the cheapest primitive that fits.
- Surface task failures:
.await handles, or collect them with JoinSet.
- Move heavy synchronous work to
spawn_blocking.
DON'T
- Reach for
tokio::sync::Mutex by reflex — it wraps a sync mutex internally and rarely helps throughput.
- Fire-and-forget a
tokio::spawn whose result or panic matters.
- Assume
async fn in traits gives you Send futures — it does not (see async-traits.md).
Sources (verified)
- tokio.rs/tokio/tutorial — shared-state, spawning, channels (fetched 2026-07-05)
- rust-lang.github.io/async-fundamentals-initiative/roadmap.html — AFIT status
- crates.io — tokio 1.52.3 (current at fetch)
1---2name: rust-async-concurrency3description: Use when writing async Rust — spawning tasks, sharing state across tasks/threads, choosing channels vs mutexes, or hitting Send-bound errors with async traits. Not for HTTP service structure (rust-web-backend) or sync-only ownership (rust-core-language).4versions:5 tokio: "1.52"6 rust-edition: "2024"7user-invocable: false8references: references/runtime-and-tasks.md, references/shared-state.md, references/channels.md, references/async-traits.md, references/templates/task-patterns.md, references/templates/graceful-shutdown.md9related-skills: rust-web-backend, solid-rust10metadata:11 source: https://skillmd.com/skills/fusengine/rust-async-concurrency12---1314<objective>15This skill covers writing and reviewing async Rust code on the tokio runtime: spawning and16supervising tasks (spawn, JoinHandle, JoinSet, spawn_blocking), choosing shared-state17primitives (Mutex, RwLock, atomics) versus message passing, and picking the right channel18shape (mpsc, oneshot, broadcast, watch).1920It also covers the async-fn-in-traits Send problem — why `async fn` in traits does not give21Send futures by default and how to work around it.2223Out of scope: HTTP service structure (routing, extractors, middleware) is owned by24rust-web-backend; sync-only ownership and borrowing questions belong to rust-core-language.25</objective>2627# Rust Async & Concurrency2829## Agent Workflow (MANDATORY)3031Before writing async code, spawn in parallel:32331. **fuse-ai-pilot:explore-codebase** — find the existing runtime, channel, and lock patterns already in use342. **fuse-ai-pilot:research-expert** — verify current tokio/crate APIs via Context7/Exa (async APIs churn)353. **mcp__context7__query-docs** — pull exact signatures for the primitives you touch3637After writing, run **fuse-ai-pilot:sniper**.3839---4041## Runtime Landscape4243| Runtime | Reality |44|---------|---------|45| **tokio** | The de-facto standard. Almost every async crate (axum, sqlx, reqwest, tonic) targets it. Default choice. |46| **async-std** | Niche, effectively in maintenance mode. Do not pick for new work. |47| **smol** | Niche, small/embeddable. Only for constrained or embedded contexts. |4849Default to tokio unless a hard constraint says otherwise.5051---5253## Critical Rules54551. **`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.562. **`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.573. **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.584. **`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.595. **`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).6061---6263## Reference Guide6465### Concepts6667| Topic | Reference | When to Consult |68|-------|-----------|-----------------|69| **Runtime & tasks** | [runtime-and-tasks.md](references/runtime-and-tasks.md) | spawn, JoinHandle, JoinSet, spawn_blocking, `'static` bound |70| **Shared state** | [shared-state.md](references/shared-state.md) | Choosing Mutex vs RwLock vs atomics vs actor task |71| **Channels** | [channels.md](references/channels.md) | Picking mpsc / oneshot / broadcast / watch |72| **Async traits** | [async-traits.md](references/async-traits.md) | `async fn` in traits + the Send-bound problem |7374### Templates7576| Template | When to Use |77|----------|-------------|78| [task-patterns.md](references/templates/task-patterns.md) | Concurrent tasks, JoinSet, actor pattern, spawn_blocking |79| [graceful-shutdown.md](references/templates/graceful-shutdown.md) | Cancellation, shutdown signal, draining tasks |8081---8283## Quick Reference8485### Scope the guard, don't hold it across `.await`8687```rust88// GOOD: lock released before the await89{90 let mut db = state.lock().unwrap();91 db.insert(key, value);92} // guard dropped here93do_async_work().await;94```9596→ See [shared-state.md](references/shared-state.md)9798### Pick the channel by shape99100```rust101// one value back to a caller → oneshot102// many producers, one consumer → mpsc103// fan-out same value to all → broadcast104// latest-value-only state → watch105```106107→ See [channels.md](references/channels.md)108109---110111## Best Practices112113### DO114- Measure contention before choosing a lock; prefer the cheapest primitive that fits.115- Surface task failures: `.await` handles, or collect them with `JoinSet`.116- Move heavy synchronous work to `spawn_blocking`.117118### DON'T119- Reach for `tokio::sync::Mutex` by reflex — it wraps a sync mutex internally and rarely helps throughput.120- Fire-and-forget a `tokio::spawn` whose result or panic matters.121- Assume `async fn` in traits gives you `Send` futures — it does not (see async-traits.md).122123---124125## Sources (verified)126127- tokio.rs/tokio/tutorial — shared-state, spawning, channels (fetched 2026-07-05)128- rust-lang.github.io/async-fundamentals-initiative/roadmap.html — AFIT status129- crates.io — tokio 1.52.3 (current at fetch)