BumpyClock/agent-templates / skills_archive/rust-skills
rust-skills
UnverifiedRust guidance for ownership, APIs, concurrency, and safety. Use when writing, reviewing, or refactoring Rust code.
rules/async-spawn-blocking.md
View on GitHub# async-spawn-blocking
> Use `spawn_blocking` for CPU-intensive work
## Why It Matters
Async runtimes like Tokio use a small number of threads to handle many tasks. CPU-intensive or blocking operations on these threads starve other tasks. `spawn_blocking` moves such work to a dedicated thread pool.
## Bad
```rust
// BAD: Blocks the async runtime thread
async fn process_image(data: &[u8]) -> ProcessedImage {
// CPU-intensive work on async thread!
let resized = resize_image(data); // Blocks!
let compressed = compress(resized); // Blocks!
compressed
}
// BAD: Synchronous file I/O in async context
async fn read_large_file(path: &Path) -> Vec<u8> {
std::fs::read(path).unwrap() // Blocks the runtime!
}
```
## Good
```rust
use tokio::task;
// GOOD: Offload CPU work to blocking pool
async fn process_image(data: Vec<u8>) -> ProcessedImage {
task::spawn_blocking(move || {
let resized = resize_image(&data);
compress(resized)
})
.await
.expect("spawn_blocking failed")
}
// GOOD: Use async file I/O
async fn read_large_file(path: &Path) -> tokio::io::Result<Vec<u8>> {
tokio::fs::read(path).await
}
// GOOD: Or spawn_blocking for unavoidable sync I/O
async fn read_with_sync_lib(path: PathBuf) -> Vec<u8> {
task::spawn_blocking(move || {
sync_library::read_file(&path)
})
.await
.unwrap()
}
```
## What Counts as Blocking
```rust
// CPU-intensive operations
- Cryptographic operations (hashing, encryption)
- Image/video processing
- Compression/decompression
- Complex parsing
- Mathematical computations
// Blocking I/O
- std::fs operations
- Synchronous database drivers
- Synchronous HTTP clients
- Thread::sleep
// Example thresholds (rough guidelines):
// < 10µs: OK on async thread
// 10µs - 1ms: Consider spawn_blocking
// > 1ms: Definitely spawn_blocking
```
## Practical Examples
```rust
// Password hashing (CPU-intensive)
async fn hash_password(password: String) -> String {
task::spawn_blocking(move || {
bcrypt::hash(password, bcrypt::DEFAULT_COST).unwrap()
})
.await
.unwrap()
}
// JSON parsing of large documents
async fn parse_large_json(data: String) -> serde_json::Value {
task::spawn_blocking(move || {
serde_json::from_str(&data).unwrap()
})
.await
.unwrap()
}
// Compression
async fn compress_data(data: Vec<u8>) -> Vec<u8> {
task::spawn_blocking(move || {
let mut encoder = flate2::write::GzEncoder::new(
Vec::new(),
flate2::Compression::default(),
);
encoder.write_all(&data).unwrap();
encoder.finish().unwrap()
})
.await
.unwrap()
}
```
## spawn_blocking vs spawn
```rust
// spawn: Runs async code on runtime threads
tokio::spawn(async {
// Async code here
some_async_operation().await;
});
// spawn_blocking: Runs sync code on blocking thread pool
tokio::task::spawn_blocking(|| {
// Synchronous, possibly CPU-intensive code
heavy_computation();
});
// spawn_blocking returns JoinHandle that can be awaited
let result = tokio::task::spawn_blocking(|| {
expensive_sync_operation()
}).await?;
```
## Rayon for Parallel CPU Work
```rust
// For parallel CPU work, consider Rayon inside spawn_blocking
async fn parallel_process(items: Vec<Item>) -> Vec<Output> {
task::spawn_blocking(move || {
use rayon::prelude::*;
items.par_iter()
.map(|item| cpu_intensive_transform(item))
.collect()
})
.await
.unwrap()
}
```
## See Also
- [async-tokio-fs](async-tokio-fs.md) - Use tokio::fs for async file I/O
- [async-no-lock-await](async-no-lock-await.md) - Don't hold locks across await
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis. | Stars: 466k | Updated | Claude CodeCodex | Verified | Install |
| reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis. | Stars: 466k | Updated | Claude CodeCodex | Verified | Install |
| diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness. | Stars: 319k | Updated | Claude CodeCodex | Verified | Install |
| dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies | Stars: 319k | Updated | Claude CodeCodex | Verified | Install |