wshobson/rust-async-patterns

Rust Async Patterns

Production patterns for async Rust programming with Tokio runtime, including tasks, channels, streams, and error handling.

When to Use This Skill

• Building async Rust applications
• Implementing concurrent network services
• Using Tokio for async I/O
• Handling async errors properly
• Debugging async code issues
• Optimizing async performance

Core Concepts

1. Async Execution Model

Future (lazy) → poll() → Ready(value) | Pending
                ↑           ↓
              Waker ← Runtime schedules

2. Key Abstractions

| Concept | Purpose | | ---------- | ---------------------------------------- | | Future | Lazy computation that may complete later | | async fn | Function returning impl Future | | await | Suspend until future completes | | Task | Spawned future running concurrently | | Runtime | Executor that polls futures |

Quick Start

# Cargo.toml
[dependencies]
tokio = { version = "1", features = ["full"] }
futures = "0.3"
async-trait = "0.1"
anyhow = "1.0"
tracing = "0.1"
tracing-subscriber = "0.3"

use tokio::time::{sleep, Duration};
use anyhow::Result;

#[tokio::main]
async fn main() -> Result<()> {
    // Initialize tracing
    tracing_subscriber::fmt::init();

    // Async operations
    let result = fetch_data("https://api.example.com").await?;
    println!("Got: {}", result);

    Ok(())
}

async fn fetch_data(url: &str) -> Result<String> {
    // Simulated async operation
    sleep(Duration::from_millis(100)).await;
    Ok(format!("Data from {}", url))
}

Detailed patterns and worked examples

Detailed pattern documentation lives in references/details.md. Read that file when the navigation tier above is insufficient.

Best Practices

Do's

• Use tokio::select! - For racing futures
• Prefer channels - Over shared state when possible
• Use JoinSet - For managing multiple tasks
• Instrument with tracing - For debugging async code
• Handle cancellation - Check CancellationToken

Don'ts

• Don't block - Never use std::thread::sleep in async
• Don't hold locks across awaits - Causes deadlocks
• Don't spawn unboundedly - Use semaphores for limits
• Don't ignore errors - Propagate with ? or log
• Don't forget Send bounds - For spawned futures