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.

1. Mark every .await as a possible suspension point. Check what state is held

across it.

1. Use tokio::spawn(async move { ... }) only when the task can own everything

it needs and its future is Send + 'static on the selected runtime.

1. Keep JoinHandles when task success, panic, cancellation, or shutdown

matters. Do not silently detach important work.

1. Keep blocking IO and CPU-heavy work out of async tasks. Use async APIs,

spawn_blocking, Rayon, or dedicated threads as the workload requires.

1. Do not hold a synchronous MutexGuard, RefCell borrow, or non-Send value

across .await.

1. 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

• Native async fn in traits is fine for private traits and static dispatch

when callers do not need to add bounds to the returned future.

• Public traits that need Send futures should usually spell the method as

fn name(...) -> impl Future<Output = T> + Send or use trait-variant to

offer local and Send variants.

• Public traits that need dynamic dispatch usually need an explicit boxed

future return type, such as Pin<Box<dyn Future<Output = T> + Send + '_>>.

Use async-trait as an ergonomics layer only when the dependency and

allocation tradeoff are acceptable.

• Avoid leaking executor-specific types from a trait unless the trait is

intentionally runtime-specific.

Review Checklist

• No lock or borrow crosses .await accidentally.
• Spawned tasks own their inputs with async move.
• Important JoinHandles are awaited, monitored, or aborted on shutdown.
• Blocking work is isolated and bounded.
• Error paths preserve context instead of becoming JoinError or timeout noise.