agy-superpowers 5.2.1 → 5.2.3

package/template/agent/skills/rust-developer/references/rust-rules/async-select-racing.md

@@ -1,198 +0,0 @@
-# async-select-racing
-
-> Use `select!` to race futures and handle the first to complete
-
-## Why It Matters
-
-Sometimes you need the first result from multiple futures—timeout vs operation, cancellation vs work, or competing alternatives. `tokio::select!` lets you race futures and handle whichever completes first, while properly cancelling the others.
-
-## Bad
-
-```rust
-// Can't express "whichever finishes first"
-async fn fetch_with_fallback() -> Data {
-    match fetch_primary().await {
-        Ok(data) => data,
-        Err(_) => fetch_fallback().await.unwrap(),  // Sequential, not racing
-    }
-}
-
-// Manual timeout is error-prone
-async fn fetch_with_timeout() -> Option<Data> {
-    let start = Instant::now();
-    loop {
-        if start.elapsed() > Duration::from_secs(5) {
-            return None;
-        }
-        // How do we check timeout while awaiting?
-    }
-}
-```
-
-## Good
-
-```rust
-use tokio::select;
-
-async fn fetch_with_timeout() -> Result<Data, Error> {
-    select! {
-        result = fetch_data() => result,
-        _ = tokio::time::sleep(Duration::from_secs(5)) => {
-            Err(Error::Timeout)
-        }
-    }
-}
-
-async fn fetch_with_fallback() -> Data {
-    select! {
-        result = fetch_primary() => {
-            match result {
-                Ok(data) => data,
-                Err(_) => fetch_fallback().await.unwrap()
-            }
-        }
-        _ = tokio::time::sleep(Duration::from_secs(1)) => {
-            // Primary too slow, use fallback
-            fetch_fallback().await.unwrap()
-        }
-    }
-}
-```
-
-## select! Syntax
-
-```rust
-select! {
-    // Pattern = future => handler
-    result = async_operation() => {
-        // Handle result
-        println!("Got: {:?}", result);
-    }
-    
-    // Can bind with pattern matching
-    Ok(data) = fallible_operation() => {
-        process(data);
-    }
-    
-    // Conditional branches with if guards
-    msg = channel.recv(), if should_receive => {
-        handle_message(msg);
-    }
-    
-    // else branch for when all futures are disabled
-    else => {
-        println!("All branches disabled");
-    }
-}
-```
-
-## Cancellation Behavior
-
-```rust
-async fn select_example() {
-    select! {
-        _ = operation_a() => {
-            println!("A completed first");
-            // operation_b() is dropped/cancelled
-        }
-        _ = operation_b() => {
-            println!("B completed first");
-            // operation_a() is dropped/cancelled
-        }
-    }
-}
-
-// Futures are cancelled at their next .await point
-// For immediate cancellation, futures must be cancel-safe
-```
-
-## Biased Selection
-
-```rust
-// By default, select! randomly picks when multiple are ready
-// Use biased mode for deterministic priority
-select! {
-    biased;  // Check branches in order
-    
-    msg = high_priority.recv() => handle_high(msg),
-    msg = low_priority.recv() => handle_low(msg),
-}
-
-// Without biased, both channels have equal chance
-// when both have messages ready
-```
-
-## Loop with select!
-
-```rust
-async fn event_loop(
-    mut commands: mpsc::Receiver<Command>,
-    shutdown: CancellationToken,
-) {
-    loop {
-        select! {
-            _ = shutdown.cancelled() => {
-                println!("Shutting down");
-                break;
-            }
-            Some(cmd) = commands.recv() => {
-                process_command(cmd).await;
-            }
-            else => {
-                // commands channel closed
-                break;
-            }
-        }
-    }
-}
-```
-
-## Racing Multiple of Same Type
-
-```rust
-// Race multiple servers for fastest response
-async fn fastest_response(servers: &[String]) -> Result<Response> {
-    let futures = servers.iter()
-        .map(|s| fetch_from(s))
-        .collect::<Vec<_>>();
-    
-    // select! requires static branches, use select_all for dynamic
-    let (result, _index, _remaining) = 
-        futures::future::select_all(futures).await;
-    
-    result
-}
-```
-
-## Common Patterns
-
-```rust
-// Timeout
-select! {
-    result = operation() => result,
-    _ = sleep(Duration::from_secs(5)) => Err(Timeout),
-}
-
-// Cancellation
-select! {
-    result = operation() => result,
-    _ = cancel_token.cancelled() => Err(Cancelled),
-}
-
-// Interval with cancellation
-let mut interval = tokio::time::interval(Duration::from_secs(1));
-loop {
-    select! {
-        _ = shutdown.cancelled() => break,
-        _ = interval.tick() => {
-            do_periodic_work().await;
-        }
-    }
-}
-```
-
-## See Also
-
-- [async-cancellation-token](./async-cancellation-token.md) - Cancellation patterns
-- [async-join-parallel](./async-join-parallel.md) - All futures, not racing
-- [async-bounded-channel](./async-bounded-channel.md) - Channel operations in select

package/template/agent/skills/rust-developer/references/rust-rules/async-spawn-blocking.md

@@ -1,154 +0,0 @@
-# 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

package/template/agent/skills/rust-developer/references/rust-rules/async-tokio-fs.md

@@ -1,167 +0,0 @@
-# async-tokio-fs
-
-> Use `tokio::fs` instead of `std::fs` in async code
-
-## Why It Matters
-
-`std::fs` operations are blocking—they stop the current thread until the syscall completes. In async code, this blocks the executor thread, preventing it from running other tasks. `tokio::fs` wraps filesystem operations in `spawn_blocking`, keeping the executor responsive.
-
-## Bad
-
-```rust
-async fn process_files(paths: &[PathBuf]) -> Result<Vec<String>> {
-    let mut contents = Vec::new();
-    
-    for path in paths {
-        // BLOCKS the entire executor thread!
-        let data = std::fs::read_to_string(path)?;
-        contents.push(data);
-    }
-    
-    Ok(contents)
-}
-
-// While reading a file, NO other tasks can run on this thread
-```
-
-## Good
-
-```rust
-use tokio::fs;
-
-async fn process_files(paths: &[PathBuf]) -> Result<Vec<String>> {
-    let mut contents = Vec::new();
-    
-    for path in paths {
-        // Non-blocking: allows other tasks to run
-        let data = fs::read_to_string(path).await?;
-        contents.push(data);
-    }
-    
-    Ok(contents)
-}
-
-// Even better: concurrent reads
-async fn process_files_concurrent(paths: &[PathBuf]) -> Result<Vec<String>> {
-    let futures: Vec<_> = paths.iter()
-        .map(|path| fs::read_to_string(path))
-        .collect();
-    
-    futures::future::try_join_all(futures).await
-}
-```
-
-## tokio::fs API
-
-```rust
-use tokio::fs;
-
-// Reading
-let contents = fs::read_to_string("file.txt").await?;
-let bytes = fs::read("file.bin").await?;
-
-// Writing
-fs::write("output.txt", "contents").await?;
-
-// File operations
-let file = fs::File::open("file.txt").await?;
-let file = fs::File::create("new.txt").await?;
-
-// Directory operations
-fs::create_dir("new_dir").await?;
-fs::create_dir_all("nested/dir/path").await?;
-fs::remove_dir("empty_dir").await?;
-fs::remove_dir_all("dir_with_contents").await?;
-
-// Metadata
-let metadata = fs::metadata("file.txt").await?;
-let canonical = fs::canonicalize("./relative").await?;
-
-// Rename/remove
-fs::rename("old.txt", "new.txt").await?;
-fs::remove_file("file.txt").await?;
-
-// Read directory
-let mut entries = fs::read_dir("some_dir").await?;
-while let Some(entry) = entries.next_entry().await? {
-    println!("{}", entry.path().display());
-}
-```
-
-## Async File I/O
-
-```rust
-use tokio::fs::File;
-use tokio::io::{AsyncReadExt, AsyncWriteExt, AsyncBufReadExt, BufReader};
-
-// Read with buffer
-let mut file = File::open("large.bin").await?;
-let mut buffer = vec![0u8; 4096];
-let bytes_read = file.read(&mut buffer).await?;
-
-// Read all
-let mut contents = Vec::new();
-file.read_to_end(&mut contents).await?;
-
-// Write
-let mut file = File::create("output.bin").await?;
-file.write_all(b"data").await?;
-file.flush().await?;
-
-// Buffered line reading
-let file = File::open("lines.txt").await?;
-let reader = BufReader::new(file);
-let mut lines = reader.lines();
-
-while let Some(line) = lines.next_line().await? {
-    println!("{}", line);
-}
-```
-
-## When std::fs is Acceptable
-
-```rust
-// Startup/initialization (before async runtime)
-fn main() {
-    let config = std::fs::read_to_string("config.toml")
-        .expect("config file required");
-    
-    tokio::runtime::Runtime::new()
-        .unwrap()
-        .block_on(run_with_config(config));
-}
-
-// Single-threaded current_thread runtime (less impact)
-#[tokio::main(flavor = "current_thread")]
-async fn main() {
-    // Still prefer tokio::fs, but impact is lower
-}
-
-// When file operations are rare and quick
-// (e.g., reading small config once per hour)
-```
-
-## Performance Considerations
-
-```rust
-// tokio::fs uses spawn_blocking internally
-// For many small files, the overhead adds up
-
-// Batch operations when possible
-let paths: Vec<_> = entries.iter()
-    .map(|e| e.path())
-    .collect();
-
-let contents = futures::future::try_join_all(
-    paths.iter().map(|p| fs::read_to_string(p))
-).await?;
-
-// For heavy I/O, consider memory-mapped files
-// (requires unsafe or mmap crate)
-```
-
-## See Also
-
-- [async-spawn-blocking](./async-spawn-blocking.md) - How tokio::fs works internally
-- [async-tokio-runtime](./async-tokio-runtime.md) - Runtime configuration
-- [err-context-chain](./err-context-chain.md) - Adding path context to IO errors

package/template/agent/skills/rust-developer/references/rust-rules/async-tokio-runtime.md

@@ -1,169 +0,0 @@
-# async-tokio-runtime
-
-> Configure Tokio runtime appropriately for your workload
-
-## Why It Matters
-
-Tokio's default multi-threaded runtime isn't always optimal. CPU-bound work needs different configuration than IO-bound work. Incorrect configuration leads to poor performance, blocked workers, or resource exhaustion. Understanding runtime options lets you tune for your specific use case.
-
-## Bad
-
-```rust
-// Default runtime for everything - not optimal
-#[tokio::main]
-async fn main() {
-    // CPU-heavy work on async executor starves IO tasks
-    for data in datasets {
-        let result = heavy_computation(data).await;
-    }
-}
-
-// Single-threaded when multi-threaded is needed
-#[tokio::main(flavor = "current_thread")]
-async fn main() {
-    // Can't utilize multiple cores for concurrent tasks
-    for _ in 0..1000 {
-        tokio::spawn(async { /* IO work */ });
-    }
-}
-```
-
-## Good
-
-```rust
-// Multi-threaded for concurrent IO (default)
-#[tokio::main]
-async fn main() {
-    // Good for many concurrent network connections
-    let handles: Vec<_> = urls.iter()
-        .map(|url| tokio::spawn(fetch(url.clone())))
-        .collect();
-    
-    futures::future::join_all(handles).await;
-}
-
-// Current-thread for single-threaded scenarios
-#[tokio::main(flavor = "current_thread")]
-async fn main() {
-    // Good for single-connection clients, simpler debugging
-    let client = Client::new();
-    client.run().await;
-}
-
-// Custom configuration
-#[tokio::main(worker_threads = 4)]
-async fn main() {
-    // Limit to 4 worker threads
-}
-
-// Or manual setup for more control
-fn main() {
-    let runtime = tokio::runtime::Builder::new_multi_thread()
-        .worker_threads(4)
-        .enable_all()
-        .thread_name("my-worker")
-        .build()
-        .unwrap();
-    
-    runtime.block_on(async_main());
-}
-```
-
-## Runtime Types
-
-| Runtime | Use Case | Configuration |
-|---------|----------|---------------|
-| Multi-thread | IO-bound, many connections | `#[tokio::main]` (default) |
-| Current-thread | CLI tools, tests, single connection | `flavor = "current_thread"` |
-| Custom | Fine-tuned performance | `Builder::new_*()` |
-
-## Worker Thread Tuning
-
-```rust
-use tokio::runtime::Builder;
-
-// IO-bound: more threads than cores can help
-let io_runtime = Builder::new_multi_thread()
-    .worker_threads(num_cpus::get() * 2)  // IO can benefit from oversubscription
-    .max_blocking_threads(32)              // For spawn_blocking calls
-    .enable_io()
-    .enable_time()
-    .build()?;
-
-// CPU-bound: match core count
-let cpu_runtime = Builder::new_multi_thread()
-    .worker_threads(num_cpus::get())       // No benefit from more than cores
-    .build()?;
-```
-
-## Multiple Runtimes
-
-```rust
-// Separate runtimes for different workloads
-struct App {
-    io_runtime: Runtime,
-    cpu_runtime: Runtime,
-}
-
-impl App {
-    fn new() -> Self {
-        Self {
-            io_runtime: Builder::new_multi_thread()
-                .worker_threads(8)
-                .thread_name("io-worker")
-                .build()
-                .unwrap(),
-            cpu_runtime: Builder::new_multi_thread()
-                .worker_threads(4)
-                .thread_name("cpu-worker")
-                .build()
-                .unwrap(),
-        }
-    }
-    
-    fn spawn_io<F>(&self, future: F) 
-    where F: Future + Send + 'static, F::Output: Send + 'static 
-    {
-        self.io_runtime.spawn(future);
-    }
-    
-    fn spawn_cpu<F>(&self, task: F) 
-    where F: FnOnce() + Send + 'static 
-    {
-        self.cpu_runtime.spawn_blocking(task);
-    }
-}
-```
-
-## Runtime in Tests
-
-```rust
-// Single test runtime
-#[tokio::test]
-async fn test_single() {
-    assert!(true);
-}
-
-// Multi-threaded test
-#[tokio::test(flavor = "multi_thread", worker_threads = 2)]
-async fn test_concurrent() {
-    let (tx, rx) = tokio::sync::oneshot::channel();
-    tokio::spawn(async move { tx.send(42).unwrap() });
-    assert_eq!(rx.await.unwrap(), 42);
-}
-
-// Custom runtime in test
-#[test]
-fn test_with_custom_runtime() {
-    let rt = Builder::new_current_thread().build().unwrap();
-    rt.block_on(async {
-        // test code
-    });
-}
-```
-
-## See Also
-
-- [async-spawn-blocking](./async-spawn-blocking.md) - Handling blocking code
-- [async-no-lock-await](./async-no-lock-await.md) - Avoiding lock issues
-- [async-joinset-structured](./async-joinset-structured.md) - Managing spawned tasks