1---
2name: rust-async-patterns
3description: Master Rust async programming with Tokio, async traits, error handling, and concurrent patterns. Use when building async Rust applications, implementing concurrent systems, or debugging async code.
4---
5 
6# Rust Async Patterns
7 
8Production patterns for async Rust programming with Tokio runtime, including tasks, channels, streams, and error handling.
9 
10## When to Use This Skill
11 
12- Building async Rust applications
13- Implementing concurrent network services
14- Using Tokio for async I/O
15- Handling async errors properly
16- Debugging async code issues
17- Optimizing async performance
18 
19## Core Concepts
20 
21### 1. Async Execution Model
22 
23```
24Future (lazy) → poll() → Ready(value) | Pending
25                ↑           ↓
26              Waker ← Runtime schedules
27```
28 
29### 2. Key Abstractions
30 
31| Concept    | Purpose                                  |
32| ---------- | ---------------------------------------- |
33| `Future`   | Lazy computation that may complete later |
34| `async fn` | Function returning impl Future           |
35| `await`    | Suspend until future completes           |
36| `Task`     | Spawned future running concurrently      |
37| `Runtime`  | Executor that polls futures              |
38 
39## Quick Start
40 
41```toml
42# Cargo.toml
43[dependencies]
44tokio = { version = "1", features = ["full"] }
45futures = "0.3"
46async-trait = "0.1"
47anyhow = "1.0"
48tracing = "0.1"
49tracing-subscriber = "0.3"
50```
51 
52```rust
53use tokio::time::{sleep, Duration};
54use anyhow::Result;
55 
56#[tokio::main]
57async fn main() -> Result<()> {
58    // Initialize tracing
59    tracing_subscriber::fmt::init();
60 
61    // Async operations
62    let result = fetch_data("https://api.example.com").await?;
63    println!("Got: {}", result);
64 
65    Ok(())
66}
67 
68async fn fetch_data(url: &str) -> Result<String> {
69    // Simulated async operation
70    sleep(Duration::from_millis(100)).await;
71    Ok(format!("Data from {}", url))
72}
73```
74 
75## Detailed patterns and worked examples
76 
77Detailed pattern documentation lives in `references/details.md`. Read that file when the navigation tier above is insufficient.
78 
79## Best Practices
80 
81### Do's
82 
83- **Use `tokio::select!`** - For racing futures
84- **Prefer channels** - Over shared state when possible
85- **Use `JoinSet`** - For managing multiple tasks
86- **Instrument with tracing** - For debugging async code
87- **Handle cancellation** - Check `CancellationToken`
88 
89### Don'ts
90 
91- **Don't block** - Never use `std::thread::sleep` in async
92- **Don't hold locks across awaits** - Causes deadlocks
93- **Don't spawn unboundedly** - Use semaphores for limits
94- **Don't ignore errors** - Propagate with `?` or log
95- **Don't forget Send bounds** - For spawned futures
96