nledford/engineering-review-board / skills/rust-async-web
rust-async-web
VerifiedAsync Rust and Rust web/full-stack guidance. Use when working with Tokio, async tasks, cancellation, timeouts, backpressure, channels, shared state, synchronization, Axum handlers/extractors/state/middleware, Leptos components, leptos-use, server functions, SSR/hydration/WASM, or Axum-Leptos full-stack applications. Use rust-desktop-gui for native desktop GUI event-loop integration, api-design for endpoint contracts, observability-engineering for durable telemetry, css-scss-styling for CSS/SCSS/Leptos styling decisions, rust-persistence-sql for SQLx/database work, and rust-testing-quality for test lanes.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 17.7 KB |
| references/axum-leptos-debt-audit.md | markdown | 13.7 KB |
| references/tokio-runtime.md | markdown | 6.4 KB |
references/tokio-runtime.md
View on GitHub# Tokio Runtime, Coordination, And Cancellation
Use this reference after loading the parent `rust-async-web` skill when a task
needs detailed Tokio runtime, task, coordination, cancellation, or graceful
shutdown guidance.
## Runtime And Tasks
- Tokio schedules futures, timers, I/O resources, and tasks. An `async fn` does
not run until a runtime polls its future.
- Use `#[tokio::main]` for application binaries and `#[tokio::test]` for async
tests. Use an explicit `tokio::runtime::Runtime` or `Builder` only for sync
entry points, custom runtime configuration, embedding, or tests that need
precise runtime control.
- Do not create a nested runtime from code already running inside Tokio. Pass a
handle, restructure the boundary, or keep runtime construction at process
edges.
- Use `tokio::spawn` for independent async work that must run concurrently.
Spawned futures and outputs must be `Send + 'static`.
- Await `JoinHandle`s and handle `Result<T, JoinError>`; panics, aborts, and
cancellations are not normal successful task results. Detached
fire-and-forget tasks need an explicit justification, observability, and
shutdown path.
- Use `JoinSet` or a task tracker for related dynamic task groups so fan-out,
result collection, error handling, and shutdown are supervised in one place.
- Use `tokio::task::spawn_local` inside a `LocalSet` when `!Send` futures are
genuinely required. Prefer `Send` futures and `tokio::spawn` for server and
worker code unless a local-only dependency forces the constraint.
- Use `spawn_blocking` for blocking I/O or CPU-heavy work that must coexist with
async code. Cancellation does not forcibly stop an already-running blocking
closure, so give long blocking work its own cooperative stop signal when it
needs graceful shutdown.
- Tokio's blocking-thread limit is intentionally high because blocking calls can
wait for long periods. Explicitly limit CPU-bound fan-out with a semaphore or
use a specialized executor; do not treat that limit as CPU parallelism policy.
- A started `spawn_blocking` task cannot be aborted. Keep long-lived blocking
work on dedicated threads or workers with an explicit stop protocol.
- Instrument async services with tracing around request IDs, task starts and
stops, retries, timeouts, cancellation, queue depth, and adapter calls. Load
[`observability-engineering`](../../observability-engineering/SKILL.md) when
those signals become durable operator-facing telemetry.
## Checklist
- Do not block runtime threads with CPU-heavy work, synchronous I/O, or long
lock holds. Use async APIs or `spawn_blocking` when appropriate.
- Give every spawned task an ownership story: cancellation, shutdown, error
reporting, tracing context, and whether its `JoinHandle` is awaited,
supervised, or deliberately detached.
- Use `JoinSet`, task trackers, semaphores, or bounded queues when spawning many
related tasks so concurrency and shutdown stay explicit.
- Apply timeouts or cancellation tokens at external boundaries where unbounded
waiting would leak resources or stall requests.
- Treat `tokio::select!` cancellation as real control flow. Dropped branches
must be safe to cancel or explicitly protected.
- Prefer bounded channels for backpressure. Choose `mpsc`, `oneshot`, `watch`,
or `broadcast` according to fan-out and state semantics.
- Choose `std::sync`, `tokio::sync`, or message passing based on whether work
crosses `.await` points.
- Avoid holding non-async mutex guards or borrowed request data across `.await`.
Keep database transactions narrow unless a wider consistency boundary is
deliberate.
## Coordination Primitives
- `tokio::select!` races cancellation, channel operations, timeouts, signals,
and child completion. Select only over futures that are safe to drop or are
intentionally pinned or protected.
- `tokio::time::timeout` bounds external waits. Convert elapsed time into an
application or domain error at the boundary.
- Use `sleep` for one-off delays and `interval` for recurring work. Avoid real
sleeps in tests; use Tokio time controls where practical.
- Use bounded `mpsc` for work queues. Capacity is part of overload policy;
unbounded channels require a documented memory bound elsewhere.
- Use `oneshot` for one reply or acknowledgement, `watch` for latest-state
notifications, and `broadcast` when many subscribers need each event and lag
handling is acceptable.
- Use `Semaphore` for concurrency limits around outbound calls, CPU handoff,
queue consumers, or scarce resources. Spawning alone is not a limit.
- Use `tokio::sync::Mutex` or `RwLock` when a guard must cross `.await`, and keep
critical sections short. Prefer ownership transfer or message passing when
shared mutation is only coordinating work.
- Standard `std::sync::Mutex` or `RwLock` is acceptable when the critical
section is short, never crosses `.await`, and performs no blocking I/O.
- Use `Notify` for lightweight wakeups without data. Use channels when the
signal carries work, state, or errors.
## Cancellation And Graceful Shutdown
- Tokio cancellation is cooperative: dropping a future or taking another
`select!` branch stops polling it, but blocking work and external systems are
not forcibly cleaned up.
- Use `tokio_util::sync::CancellationToken` to fan cancellation out to tasks
that should stop together.
- Pass cancellation through application services and adapters that own
cancellable I/O. Keep it out of pure domain objects unless it is domain
language.
- Graceful shutdown usually means stopping acceptance, signalling cancellation,
closing senders, deliberately draining or rejecting queued work, and joining
tasks with a bounded timeout.
- Ordinary runtime shutdown may wait indefinitely for started blocking work.
`Runtime::shutdown_timeout` stops waiting after its timeout, but does not stop
that work; design it to finish or be managed independently.
- Dropping a `JoinHandle` detaches the task. Own, join, intentionally abort, or
supervise every spawned task.
- Cancellation does not forcibly stop `spawn_blocking`, synchronous file or
process calls, driver operations that ignore cancellation, or remote side
effects already sent. Design idempotency, timeouts, and cleanup around those
facts.
```rust
loop {
tokio::select! {
_ = token.cancelled() => break,
maybe_job = jobs.recv() => match maybe_job {
Some(job) => handle(job).await?,
None => break,
},
}
}
```
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| finishing-a-development-branchobra/superpowersUse when implementation is complete, all tests pass, and you need to decide how to integrate the work | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| systematic-debuggingobra/superpowersUse when encountering any bug, test failure, or unexpected behavior, before proposing fixes | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| test-driven-developmentobra/superpowersUse when implementing any feature or bugfix, before writing implementation code | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| skill-creatoranthropics/skillsCreate new skills, modify and improve existing skills, and measure skill performance. Use when users want to create a skill from scratch, edit, or optimize an existing skill, run evals to test a skill, benchmark skill performance with variance analysis, or optimize a skill's description for better triggering accuracy. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |