rust-async-task-design
Design and review Rust async code around task ownership, suspension points, cancellation, blocking work, and runtime boundaries. Use when writing, refactoring, or reviewing futures, async functions, Tokio tasks, spawn, JoinHandle, Send futures, async traits, cancellation, or mutexes across await points.
- License 许可
- MIT
- 最近更新
- 2026-06-26
- Stars
- ★ 0
- Forks
- 0
01 前言 Front Matter
- name
- rust-async-task-design
- license
- MIT
- metadata
- { "tags": "rust,async,tokio,futures,tasks", "version": "0.1.0", "category": "Rust", "displayName": "Rust Async Task Design" }
- description
- Design and review Rust async code around task ownership, suspension points, cancellation, blocking work, and runtime boundaries. Use when writing, refactoring, or reviewing futures, async functions, Tokio tasks, spawn, JoinHandle, Send futures, async traits, cancellation, or mutexes across await points.
- compatibility
- Codex, Claude Code, and other Agent Skills-compatible clients.
02 资源文件 2
- 参考文档agents/openai.yaml253 B
- 参考文档references/async-runtime-patterns.md1.6 KB
03 SKILL.md 正文
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
- Identify the async boundary: runtime entrypoint, handler, client call, stream, background task, or trait method.
- Mark every
.awaitas a possible suspension point. Check what state is held across it. - Use
tokio::spawn(async move { ... })only when the task can own everything it needs and its future isSend + 'staticon the selected runtime. - Keep
JoinHandles when task success, panic, cancellation, or shutdown matters. Do not silently detach important work. - Keep blocking IO and CPU-heavy work out of async tasks. Use async APIs,
spawn_blocking, Rayon, or dedicated threads as the workload requires. - Do not hold a synchronous
MutexGuard,RefCellborrow, or non-Sendvalue across.await. - 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::Mutexin async code only for short, low-contention critical sections that do not cross.await. - Use
tokio::sync::Mutexwhen a lock must be held across.await, but first consider moving the state behind a task and interacting by messages. - Use
spawn_blockingfor blocking operations that eventually finish. Limit parallelism for CPU-heavy work; Tokio's blocking pool can grow large. - Use
tokio::time::timeoutor 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 fnin 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
Sendfutures should usually spell the method asfn name(...) -> impl Future<Output = T> + Sendor usetrait-variantto offer local andSendvariants. - Public traits that need dynamic dispatch usually need an explicit boxed
future return type, such as
Pin<Box<dyn Future<Output = T> + Send + '_>>. Useasync-traitas 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
.awaitaccidentally. - 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
JoinErroror timeout noise.
04 同仓库更多 Skills
android-emulator-qa
Use when validating Android feature flows in an emulator with adb-driven launch, input, UI-tree inspection, screenshots, and logcat capture.
supabase-postgres-best-practices
Postgres performance optimization and best practices from Supabase. Use this skill when writing, reviewing, or optimizing Postgres queries, schema designs, or database configurations.
sentry
Use when the user asks to inspect Sentry issues or events, summarize recent production errors, or pull basic Sentry health data via the Sentry API; perform read-only queries with the bundled script and require `SENTRY_AUTH_TOKEN`.
render-workflows
Sets up, develops, tests, and deploys Render Workflows. Covers first-time scaffolding (via CLI or manual), SDK installation (Python or TypeScript), task patterns (retries, subtasks, fan-out), local development, Dashboard deployment, and troubleshooting. Use when a user wants to set up Render Workflows for the first time, scaffold a workflow service, add or modify workflow tasks, test workflows locally, or deploy workflows to Render.
render-web-services
Configures Render web services—port binding, TLS, health checks, custom domains, auto-deploy, PR previews, persistent disks, and deploy lifecycle. Use when the user needs to set up a web service, fix health check failures, add a custom domain, configure zero-downtime deploys, or troubleshoot port binding issues.
render-static-sites
Deploys and configures static sites on Render's global CDN—build commands, publish paths, SPA routing, redirects, custom headers, and PR previews. Use when the user needs to deploy a static site, set up a React/Vue/Hugo/Gatsby frontend, configure SPA fallback routing, add redirect rules, customize response headers, or choose between a static site and a web service for their frontend. Trigger terms: static site, CDN, SPA, single-page app, React deploy, Vue deploy, Hugo, Gatsby, Docusaurus, Jekyll, staticPublishPath.