Rust Async Task Design

Rust Async Task Design

Use this skill to make Rust async code explicit about task ownership, suspension points, blocking work, and cancellation. Async is a concurrency model, not a default replacement for threads or a performance guarantee.

Core Workflow

1. Identify the async boundary: runtime entrypoint, handler, client call, stream, background task, or trait method.
2. Mark every .await as a possible suspension point. Check what state is held across it.
3. Use tokio::spawn(async move { ... }) only when the task can own everything it needs and its future is Send + 'static on the selected runtime.
4. Keep JoinHandles when task success, panic, cancellation, or shutdown matters. Do not silently detach important work.
5. Keep blocking IO and CPU-heavy work out of async tasks. Use async APIs, spawn_blocking, Rayon, or dedicated threads as the workload requires.
6. Do not hold a synchronous MutexGuard, RefCell borrow, or non-Send value across .await.
7. Add tests for timeout, cancellation, dropped channel, and failed task paths when those outcomes affect behavior.

Runtime Rules

Read references/async-runtime-patterns.md when reviewing task spawning, shared state in async code, or blocking work.

• Use std::sync::Mutex in async code only for short, low-contention critical sections that do not cross .await.
• Use tokio::sync::Mutex when a lock must be held across .await, but first consider moving the state behind a task and interacting by messages.
• Use spawn_blocking for blocking operations that eventually finish. Limit parallelism for CPU-heavy work; Tokio's blocking pool can grow large.
• Use tokio::time::timeout or explicit cancellation tokens for bounded operations.
• Use select! carefully: dropping a future can cancel it. Check cancellation safety before using it around IO or partially completed work.

Async Trait Rules