AGENT SKILL

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

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

  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

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

04 同仓库更多 Skills

ConcertoNotes
ConcertoNotes/codex-plugins

android-emulator-qa

Use when validating Android feature flows in an emulator with adb-driven launch, input, UI-tree inspection, screenshots, and logcat capture.

★ 0
ConcertoNotes
ConcertoNotes/codex-plugins

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.

★ 0
ConcertoNotes
ConcertoNotes/codex-plugins

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

★ 0
ConcertoNotes
ConcertoNotes/codex-plugins

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.

★ 0
ConcertoNotes
ConcertoNotes/codex-plugins

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.

★ 0
ConcertoNotes
ConcertoNotes/codex-plugins

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.

★ 0