mirror of
https://github.com/wshobson/agents.git
synced 2026-03-18 17:47:16 +00:00
47a5dbc3f9
Remove references to non-existent resource files (references/, assets/, scripts/, examples/) from 115 skill SKILL.md files. These sections pointed to directories and files that were never created, causing confusion when users install skills. Also fix broken Code of Conduct links in issue templates to use absolute GitHub URLs instead of relative paths that 404.
514 lines
12 KiB
Markdown
514 lines
12 KiB
Markdown
---
|
|
name: rust-async-patterns
|
|
description: 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.
|
|
---
|
|
|
|
# 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
|
|
|
|
```toml
|
|
# 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"
|
|
```
|
|
|
|
```rust
|
|
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))
|
|
}
|
|
```
|
|
|
|
## Patterns
|
|
|
|
### Pattern 1: Concurrent Task Execution
|
|
|
|
```rust
|
|
use tokio::task::JoinSet;
|
|
use anyhow::Result;
|
|
|
|
// Spawn multiple concurrent tasks
|
|
async fn fetch_all_concurrent(urls: Vec<String>) -> Result<Vec<String>> {
|
|
let mut set = JoinSet::new();
|
|
|
|
for url in urls {
|
|
set.spawn(async move {
|
|
fetch_data(&url).await
|
|
});
|
|
}
|
|
|
|
let mut results = Vec::new();
|
|
while let Some(res) = set.join_next().await {
|
|
match res {
|
|
Ok(Ok(data)) => results.push(data),
|
|
Ok(Err(e)) => tracing::error!("Task failed: {}", e),
|
|
Err(e) => tracing::error!("Join error: {}", e),
|
|
}
|
|
}
|
|
|
|
Ok(results)
|
|
}
|
|
|
|
// With concurrency limit
|
|
use futures::stream::{self, StreamExt};
|
|
|
|
async fn fetch_with_limit(urls: Vec<String>, limit: usize) -> Vec<Result<String>> {
|
|
stream::iter(urls)
|
|
.map(|url| async move { fetch_data(&url).await })
|
|
.buffer_unordered(limit) // Max concurrent tasks
|
|
.collect()
|
|
.await
|
|
}
|
|
|
|
// Select first to complete
|
|
use tokio::select;
|
|
|
|
async fn race_requests(url1: &str, url2: &str) -> Result<String> {
|
|
select! {
|
|
result = fetch_data(url1) => result,
|
|
result = fetch_data(url2) => result,
|
|
}
|
|
}
|
|
```
|
|
|
|
### Pattern 2: Channels for Communication
|
|
|
|
```rust
|
|
use tokio::sync::{mpsc, broadcast, oneshot, watch};
|
|
|
|
// Multi-producer, single-consumer
|
|
async fn mpsc_example() {
|
|
let (tx, mut rx) = mpsc::channel::<String>(100);
|
|
|
|
// Spawn producer
|
|
let tx2 = tx.clone();
|
|
tokio::spawn(async move {
|
|
tx2.send("Hello".to_string()).await.unwrap();
|
|
});
|
|
|
|
// Consume
|
|
while let Some(msg) = rx.recv().await {
|
|
println!("Got: {}", msg);
|
|
}
|
|
}
|
|
|
|
// Broadcast: multi-producer, multi-consumer
|
|
async fn broadcast_example() {
|
|
let (tx, _) = broadcast::channel::<String>(100);
|
|
|
|
let mut rx1 = tx.subscribe();
|
|
let mut rx2 = tx.subscribe();
|
|
|
|
tx.send("Event".to_string()).unwrap();
|
|
|
|
// Both receivers get the message
|
|
let _ = rx1.recv().await;
|
|
let _ = rx2.recv().await;
|
|
}
|
|
|
|
// Oneshot: single value, single use
|
|
async fn oneshot_example() -> String {
|
|
let (tx, rx) = oneshot::channel::<String>();
|
|
|
|
tokio::spawn(async move {
|
|
tx.send("Result".to_string()).unwrap();
|
|
});
|
|
|
|
rx.await.unwrap()
|
|
}
|
|
|
|
// Watch: single producer, multi-consumer, latest value
|
|
async fn watch_example() {
|
|
let (tx, mut rx) = watch::channel("initial".to_string());
|
|
|
|
tokio::spawn(async move {
|
|
loop {
|
|
// Wait for changes
|
|
rx.changed().await.unwrap();
|
|
println!("New value: {}", *rx.borrow());
|
|
}
|
|
});
|
|
|
|
tx.send("updated".to_string()).unwrap();
|
|
}
|
|
```
|
|
|
|
### Pattern 3: Async Error Handling
|
|
|
|
```rust
|
|
use anyhow::{Context, Result, bail};
|
|
use thiserror::Error;
|
|
|
|
#[derive(Error, Debug)]
|
|
pub enum ServiceError {
|
|
#[error("Network error: {0}")]
|
|
Network(#[from] reqwest::Error),
|
|
|
|
#[error("Database error: {0}")]
|
|
Database(#[from] sqlx::Error),
|
|
|
|
#[error("Not found: {0}")]
|
|
NotFound(String),
|
|
|
|
#[error("Timeout after {0:?}")]
|
|
Timeout(std::time::Duration),
|
|
}
|
|
|
|
// Using anyhow for application errors
|
|
async fn process_request(id: &str) -> Result<Response> {
|
|
let data = fetch_data(id)
|
|
.await
|
|
.context("Failed to fetch data")?;
|
|
|
|
let parsed = parse_response(&data)
|
|
.context("Failed to parse response")?;
|
|
|
|
Ok(parsed)
|
|
}
|
|
|
|
// Using custom errors for library code
|
|
async fn get_user(id: &str) -> Result<User, ServiceError> {
|
|
let result = db.query(id).await?;
|
|
|
|
match result {
|
|
Some(user) => Ok(user),
|
|
None => Err(ServiceError::NotFound(id.to_string())),
|
|
}
|
|
}
|
|
|
|
// Timeout wrapper
|
|
use tokio::time::timeout;
|
|
|
|
async fn with_timeout<T, F>(duration: Duration, future: F) -> Result<T, ServiceError>
|
|
where
|
|
F: std::future::Future<Output = Result<T, ServiceError>>,
|
|
{
|
|
timeout(duration, future)
|
|
.await
|
|
.map_err(|_| ServiceError::Timeout(duration))?
|
|
}
|
|
```
|
|
|
|
### Pattern 4: Graceful Shutdown
|
|
|
|
```rust
|
|
use tokio::signal;
|
|
use tokio::sync::broadcast;
|
|
use tokio_util::sync::CancellationToken;
|
|
|
|
async fn run_server() -> Result<()> {
|
|
// Method 1: CancellationToken
|
|
let token = CancellationToken::new();
|
|
let token_clone = token.clone();
|
|
|
|
// Spawn task that respects cancellation
|
|
tokio::spawn(async move {
|
|
loop {
|
|
tokio::select! {
|
|
_ = token_clone.cancelled() => {
|
|
tracing::info!("Task shutting down");
|
|
break;
|
|
}
|
|
_ = do_work() => {}
|
|
}
|
|
}
|
|
});
|
|
|
|
// Wait for shutdown signal
|
|
signal::ctrl_c().await?;
|
|
tracing::info!("Shutdown signal received");
|
|
|
|
// Cancel all tasks
|
|
token.cancel();
|
|
|
|
// Give tasks time to cleanup
|
|
tokio::time::sleep(Duration::from_secs(5)).await;
|
|
|
|
Ok(())
|
|
}
|
|
|
|
// Method 2: Broadcast channel for shutdown
|
|
async fn run_with_broadcast() -> Result<()> {
|
|
let (shutdown_tx, _) = broadcast::channel::<()>(1);
|
|
|
|
let mut rx = shutdown_tx.subscribe();
|
|
tokio::spawn(async move {
|
|
tokio::select! {
|
|
_ = rx.recv() => {
|
|
tracing::info!("Received shutdown");
|
|
}
|
|
_ = async { loop { do_work().await } } => {}
|
|
}
|
|
});
|
|
|
|
signal::ctrl_c().await?;
|
|
let _ = shutdown_tx.send(());
|
|
|
|
Ok(())
|
|
}
|
|
```
|
|
|
|
### Pattern 5: Async Traits
|
|
|
|
```rust
|
|
use async_trait::async_trait;
|
|
|
|
#[async_trait]
|
|
pub trait Repository {
|
|
async fn get(&self, id: &str) -> Result<Entity>;
|
|
async fn save(&self, entity: &Entity) -> Result<()>;
|
|
async fn delete(&self, id: &str) -> Result<()>;
|
|
}
|
|
|
|
pub struct PostgresRepository {
|
|
pool: sqlx::PgPool,
|
|
}
|
|
|
|
#[async_trait]
|
|
impl Repository for PostgresRepository {
|
|
async fn get(&self, id: &str) -> Result<Entity> {
|
|
sqlx::query_as!(Entity, "SELECT * FROM entities WHERE id = $1", id)
|
|
.fetch_one(&self.pool)
|
|
.await
|
|
.map_err(Into::into)
|
|
}
|
|
|
|
async fn save(&self, entity: &Entity) -> Result<()> {
|
|
sqlx::query!(
|
|
"INSERT INTO entities (id, data) VALUES ($1, $2)
|
|
ON CONFLICT (id) DO UPDATE SET data = $2",
|
|
entity.id,
|
|
entity.data
|
|
)
|
|
.execute(&self.pool)
|
|
.await?;
|
|
Ok(())
|
|
}
|
|
|
|
async fn delete(&self, id: &str) -> Result<()> {
|
|
sqlx::query!("DELETE FROM entities WHERE id = $1", id)
|
|
.execute(&self.pool)
|
|
.await?;
|
|
Ok(())
|
|
}
|
|
}
|
|
|
|
// Trait object usage
|
|
async fn process(repo: &dyn Repository, id: &str) -> Result<()> {
|
|
let entity = repo.get(id).await?;
|
|
// Process...
|
|
repo.save(&entity).await
|
|
}
|
|
```
|
|
|
|
### Pattern 6: Streams and Async Iteration
|
|
|
|
```rust
|
|
use futures::stream::{self, Stream, StreamExt};
|
|
use async_stream::stream;
|
|
|
|
// Create stream from async iterator
|
|
fn numbers_stream() -> impl Stream<Item = i32> {
|
|
stream! {
|
|
for i in 0..10 {
|
|
tokio::time::sleep(Duration::from_millis(100)).await;
|
|
yield i;
|
|
}
|
|
}
|
|
}
|
|
|
|
// Process stream
|
|
async fn process_stream() {
|
|
let stream = numbers_stream();
|
|
|
|
// Map and filter
|
|
let processed: Vec<_> = stream
|
|
.filter(|n| futures::future::ready(*n % 2 == 0))
|
|
.map(|n| n * 2)
|
|
.collect()
|
|
.await;
|
|
|
|
println!("{:?}", processed);
|
|
}
|
|
|
|
// Chunked processing
|
|
async fn process_in_chunks() {
|
|
let stream = numbers_stream();
|
|
|
|
let mut chunks = stream.chunks(3);
|
|
|
|
while let Some(chunk) = chunks.next().await {
|
|
println!("Processing chunk: {:?}", chunk);
|
|
}
|
|
}
|
|
|
|
// Merge multiple streams
|
|
async fn merge_streams() {
|
|
let stream1 = numbers_stream();
|
|
let stream2 = numbers_stream();
|
|
|
|
let merged = stream::select(stream1, stream2);
|
|
|
|
merged
|
|
.for_each(|n| async move {
|
|
println!("Got: {}", n);
|
|
})
|
|
.await;
|
|
}
|
|
```
|
|
|
|
### Pattern 7: Resource Management
|
|
|
|
```rust
|
|
use std::sync::Arc;
|
|
use tokio::sync::{Mutex, RwLock, Semaphore};
|
|
|
|
// Shared state with RwLock (prefer for read-heavy)
|
|
struct Cache {
|
|
data: RwLock<HashMap<String, String>>,
|
|
}
|
|
|
|
impl Cache {
|
|
async fn get(&self, key: &str) -> Option<String> {
|
|
self.data.read().await.get(key).cloned()
|
|
}
|
|
|
|
async fn set(&self, key: String, value: String) {
|
|
self.data.write().await.insert(key, value);
|
|
}
|
|
}
|
|
|
|
// Connection pool with semaphore
|
|
struct Pool {
|
|
semaphore: Semaphore,
|
|
connections: Mutex<Vec<Connection>>,
|
|
}
|
|
|
|
impl Pool {
|
|
fn new(size: usize) -> Self {
|
|
Self {
|
|
semaphore: Semaphore::new(size),
|
|
connections: Mutex::new((0..size).map(|_| Connection::new()).collect()),
|
|
}
|
|
}
|
|
|
|
async fn acquire(&self) -> PooledConnection<'_> {
|
|
let permit = self.semaphore.acquire().await.unwrap();
|
|
let conn = self.connections.lock().await.pop().unwrap();
|
|
PooledConnection { pool: self, conn: Some(conn), _permit: permit }
|
|
}
|
|
}
|
|
|
|
struct PooledConnection<'a> {
|
|
pool: &'a Pool,
|
|
conn: Option<Connection>,
|
|
_permit: tokio::sync::SemaphorePermit<'a>,
|
|
}
|
|
|
|
impl Drop for PooledConnection<'_> {
|
|
fn drop(&mut self) {
|
|
if let Some(conn) = self.conn.take() {
|
|
let pool = self.pool;
|
|
tokio::spawn(async move {
|
|
pool.connections.lock().await.push(conn);
|
|
});
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
## Debugging Tips
|
|
|
|
```rust
|
|
// Enable tokio-console for runtime debugging
|
|
// Cargo.toml: tokio = { features = ["tracing"] }
|
|
// Run: RUSTFLAGS="--cfg tokio_unstable" cargo run
|
|
// Then: tokio-console
|
|
|
|
// Instrument async functions
|
|
use tracing::instrument;
|
|
|
|
#[instrument(skip(pool))]
|
|
async fn fetch_user(pool: &PgPool, id: &str) -> Result<User> {
|
|
tracing::debug!("Fetching user");
|
|
// ...
|
|
}
|
|
|
|
// Track task spawning
|
|
let span = tracing::info_span!("worker", id = %worker_id);
|
|
tokio::spawn(async move {
|
|
// Enters span when polled
|
|
}.instrument(span));
|
|
```
|
|
|
|
## 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
|