agy-superpowers 5.1.4 → 5.1.6

package/template/agent/skills/rust-developer/references/rust-rules/async-clone-before-await.md

@@ -0,0 +1,171 @@
+# async-clone-before-await
+
+> Clone Arc/Rc data before await points to avoid holding references across suspension
+
+## Why It Matters
+
+References held across `.await` points extend the future's lifetime and can cause borrow checker issues or prevent `Send` bounds. Cloning `Arc`/`Rc` before the await ensures the future only holds owned data, making it `Send` and avoiding lifetime complications.
+
+## Bad
+
+```rust
+use std::sync::Arc;
+
+async fn process(data: Arc<Data>) {
+    // Borrow extends across await - future is not Send
+    let slice = &data.items[..];  // Borrow of Arc contents
+    
+    expensive_async_operation().await;  // Await with active borrow
+    
+    use_slice(slice);  // Still using the borrow
+}
+
+// Error: future cannot be sent between threads safely
+// because `&[Item]` cannot be sent between threads safely
+tokio::spawn(process(data));
+```
+
+## Good
+
+```rust
+use std::sync::Arc;
+
+async fn process(data: Arc<Data>) {
+    // Clone what you need before await
+    let items = data.items.clone();  // Owned Vec
+    
+    expensive_async_operation().await;
+    
+    use_items(&items);  // Using owned data
+}
+
+// Or clone the Arc itself
+async fn share_data(data: Arc<Data>) {
+    let data = data.clone();  // Another Arc handle
+    
+    some_async_work().await;
+    
+    process(&data);  // Safe - we own the Arc
+}
+```
+
+## The Send Problem
+
+```rust
+// Futures must be Send to spawn on multi-threaded runtime
+async fn not_send() {
+    let rc = Rc::new(42);  // Rc is !Send
+    
+    tokio::time::sleep(Duration::from_secs(1)).await;
+    
+    println!("{}", rc);  // rc held across await
+}
+
+tokio::spawn(not_send());  // ERROR: future is not Send
+
+// Fix: use Arc or don't hold across await
+async fn is_send() {
+    let arc = Arc::new(42);  // Arc is Send
+    
+    tokio::time::sleep(Duration::from_secs(1)).await;
+    
+    println!("{}", arc);
+}
+
+tokio::spawn(is_send());  // OK
+```
+
+## Minimizing Clones
+
+```rust
+// Bad: clone everything eagerly
+async fn wasteful(data: Arc<LargeData>) {
+    let data = (*data).clone();  // Clones entire LargeData
+    async_work().await;
+    use_one_field(&data.small_field);
+}
+
+// Good: clone only what you need
+async fn efficient(data: Arc<LargeData>) {
+    let small = data.small_field.clone();  // Clone only needed field
+    async_work().await;
+    use_one_field(&small);
+}
+
+// Good: if you need the whole thing, keep the Arc
+async fn arc_efficient(data: Arc<LargeData>) {
+    let data = data.clone();  // Cheap Arc clone
+    async_work().await;
+    use_data(&data);  // Access through Arc
+}
+```
+
+## Spawn Pattern
+
+```rust
+// Common pattern: clone for spawned task
+let shared = Arc::new(SharedState::new());
+
+for i in 0..10 {
+    let shared = shared.clone();  // Clone before moving into spawn
+    tokio::spawn(async move {
+        // Task owns its Arc clone
+        shared.do_something(i).await;
+    });
+}
+```
+
+## Scope-Based Approach
+
+```rust
+// Limit borrow scope to before await
+async fn scoped(data: Arc<Data>) {
+    // Scope 1: borrow, compute, drop borrow
+    let computed = {
+        let slice = &data.items[..];  // Borrow
+        compute_something(slice)       // Use
+    };  // Borrow ends here
+    
+    // Now safe to await
+    expensive_async_operation().await;
+    
+    use_computed(computed);
+}
+```
+
+## MutexGuard Across Await
+
+```rust
+use tokio::sync::Mutex;
+
+// BAD: holding guard across await
+async fn bad(mutex: Arc<Mutex<Data>>) {
+    let mut guard = mutex.lock().await;
+    guard.value += 1;
+    
+    slow_operation().await;  // Guard held during await!
+    
+    guard.value += 1;
+}
+
+// GOOD: release before await
+async fn good(mutex: Arc<Mutex<Data>>) {
+    {
+        let mut guard = mutex.lock().await;
+        guard.value += 1;
+    }  // Guard released
+    
+    slow_operation().await;
+    
+    {
+        let mut guard = mutex.lock().await;
+        guard.value += 1;
+    }
+}
+```
+
+## See Also
+
+- [async-no-lock-await](./async-no-lock-await.md) - Lock guards across await
+- [own-arc-shared](./own-arc-shared.md) - Arc usage patterns
+- [async-spawn-blocking](./async-spawn-blocking.md) - Blocking in async

package/template/agent/skills/rust-developer/references/rust-rules/async-join-parallel.md

@@ -0,0 +1,158 @@
+# async-join-parallel
+
+> Use `join!` or `try_join!` for concurrent independent futures
+
+## Why It Matters
+
+Awaiting futures sequentially takes the sum of their durations. `join!` runs futures concurrently, taking only as long as the slowest one. For independent operations like multiple API calls or parallel file reads, this can dramatically reduce latency.
+
+## Bad
+
+```rust
+async fn fetch_data() -> (User, Posts, Comments) {
+    // Sequential: 300ms total (100 + 100 + 100)
+    let user = fetch_user().await;        // 100ms
+    let posts = fetch_posts().await;      // 100ms  
+    let comments = fetch_comments().await; // 100ms
+    
+    (user, posts, comments)
+}
+
+async fn read_configs() -> Result<(Config, Settings)> {
+    // Sequential: 20ms + 20ms = 40ms
+    let config = fs::read_to_string("config.toml").await?;
+    let settings = fs::read_to_string("settings.json").await?;
+    
+    Ok((parse_config(&config)?, parse_settings(&settings)?))
+}
+```
+
+## Good
+
+```rust
+use tokio::join;
+
+async fn fetch_data() -> (User, Posts, Comments) {
+    // Concurrent: ~100ms total (max of all three)
+    let (user, posts, comments) = join!(
+        fetch_user(),
+        fetch_posts(),
+        fetch_comments(),
+    );
+    
+    (user, posts, comments)
+}
+
+use tokio::try_join;
+
+async fn read_configs() -> Result<(Config, Settings)> {
+    // Concurrent: ~20ms total
+    let (config_str, settings_str) = try_join!(
+        fs::read_to_string("config.toml"),
+        fs::read_to_string("settings.json"),
+    )?;
+    
+    Ok((parse_config(&config_str)?, parse_settings(&settings_str)?))
+}
+```
+
+## join! vs try_join!
+
+```rust
+// join! - all futures run to completion, returns tuple
+let (a, b, c) = join!(future_a, future_b, future_c);
+
+// try_join! - short-circuits on first error
+let (a, b, c) = try_join!(fallible_a, fallible_b, fallible_c)?;
+// If fallible_b fails, returns Err immediately
+// Other futures may still be running (cancellation is async)
+```
+
+## futures::join_all for Dynamic Collections
+
+```rust
+use futures::future::join_all;
+
+async fn fetch_all_users(ids: &[u64]) -> Vec<User> {
+    let futures: Vec<_> = ids.iter()
+        .map(|id| fetch_user(*id))
+        .collect();
+    
+    join_all(futures).await
+}
+
+// With fallible futures
+use futures::future::try_join_all;
+
+async fn fetch_all_users(ids: &[u64]) -> Result<Vec<User>> {
+    let futures: Vec<_> = ids.iter()
+        .map(|id| fetch_user(*id))
+        .collect();
+    
+    try_join_all(futures).await
+}
+```
+
+## Limiting Concurrency
+
+```rust
+use futures::stream::{self, StreamExt};
+
+async fn fetch_with_limit(ids: &[u64]) -> Vec<Result<User>> {
+    stream::iter(ids)
+        .map(|id| fetch_user(*id))
+        .buffer_unordered(10)  // Max 10 concurrent requests
+        .collect()
+        .await
+}
+
+// Or with tokio::sync::Semaphore
+use tokio::sync::Semaphore;
+
+async fn fetch_with_semaphore(ids: &[u64]) -> Vec<User> {
+    let semaphore = Arc::new(Semaphore::new(10));
+    
+    let futures: Vec<_> = ids.iter().map(|id| {
+        let semaphore = semaphore.clone();
+        async move {
+            let _permit = semaphore.acquire().await.unwrap();
+            fetch_user(*id).await
+        }
+    }).collect();
+    
+    join_all(futures).await
+}
+```
+
+## When NOT to Use join!
+
+```rust
+// ❌ Dependent futures - must be sequential
+async fn create_and_populate() -> Result<()> {
+    let db = create_database().await?;   // Must complete first
+    populate_tables(&db).await?;          // Depends on db
+    Ok(())
+}
+
+// ❌ Short-circuiting logic
+async fn find_first() -> Option<Data> {
+    // Want to stop when one succeeds
+    // Use select! instead
+}
+
+// ❌ Shared mutable state
+async fn bad_shared_state() {
+    let counter = Arc::new(Mutex::new(0));
+    // This might work but can cause contention
+    join!(
+        increment(counter.clone()),
+        increment(counter.clone()),
+    );
+}
+```
+
+## See Also
+
+- [async-try-join](./async-try-join.md) - Error handling in concurrent futures
+- [async-select-racing](./async-select-racing.md) - Racing futures
+- [async-joinset-structured](./async-joinset-structured.md) - Dynamic task sets

package/template/agent/skills/rust-developer/references/rust-rules/async-joinset-structured.md

@@ -0,0 +1,195 @@
+# async-joinset-structured
+
+> Use `JoinSet` for managing dynamic collections of spawned tasks
+
+## Why It Matters
+
+When spawning a variable number of tasks, collecting `JoinHandle`s in a `Vec` and using `join_all` works but lacks flexibility. `JoinSet` provides a better abstraction: add/remove tasks dynamically, get results as they complete, and abort all on drop. It's the idiomatic way to manage task collections.
+
+## Bad
+
+```rust
+// Manual handle management
+let mut handles: Vec<JoinHandle<Result<Data>>> = Vec::new();
+
+for url in urls {
+    handles.push(tokio::spawn(fetch(url)));
+}
+
+// Wait for all, in order (not as they complete)
+let results = futures::future::join_all(handles).await;
+
+// No easy way to cancel all, handle errors progressively, or add more tasks
+```
+
+## Good
+
+```rust
+use tokio::task::JoinSet;
+
+let mut set = JoinSet::new();
+
+for url in urls {
+    set.spawn(fetch(url.clone()));
+}
+
+// Process results as they complete
+while let Some(result) = set.join_next().await {
+    match result {
+        Ok(Ok(data)) => process(data),
+        Ok(Err(e)) => log::error!("Task failed: {}", e),
+        Err(e) => log::error!("Task panicked: {}", e),
+    }
+}
+
+// All tasks done, set is empty
+```
+
+## Dynamic Task Addition
+
+```rust
+use tokio::task::JoinSet;
+
+async fn worker_pool(mut rx: mpsc::Receiver<Task>) {
+    let mut set = JoinSet::new();
+    let max_concurrent = 10;
+    
+    loop {
+        tokio::select! {
+            // Accept new tasks if under limit
+            Some(task) = rx.recv(), if set.len() < max_concurrent => {
+                set.spawn(process_task(task));
+            }
+            
+            // Process completed tasks
+            Some(result) = set.join_next() => {
+                handle_result(result);
+            }
+            
+            // Exit when no tasks and channel closed
+            else => break,
+        }
+    }
+}
+```
+
+## Abort on Drop
+
+```rust
+use tokio::task::JoinSet;
+
+{
+    let mut set = JoinSet::new();
+    set.spawn(long_running_task());
+    set.spawn(another_task());
+    
+    // Early exit
+    return;
+}  // JoinSet dropped here - all tasks are aborted!
+
+// Explicit abort
+let mut set = JoinSet::new();
+set.spawn(task());
+set.abort_all();  // Cancel all tasks
+```
+
+## Error Handling Pattern
+
+```rust
+use tokio::task::JoinSet;
+
+async fn fetch_all(urls: &[String]) -> Vec<Result<Data, Error>> {
+    let mut set = JoinSet::new();
+    let mut results = Vec::new();
+    
+    for url in urls {
+        set.spawn(fetch(url.clone()));
+    }
+    
+    while let Some(join_result) = set.join_next().await {
+        let result = match join_result {
+            Ok(task_result) => task_result,
+            Err(join_error) => {
+                if join_error.is_panic() {
+                    Err(Error::TaskPanicked)
+                } else {
+                    Err(Error::TaskCancelled)
+                }
+            }
+        };
+        results.push(result);
+    }
+    
+    results
+}
+```
+
+## With Cancellation
+
+```rust
+use tokio::task::JoinSet;
+use tokio_util::sync::CancellationToken;
+
+async fn run_workers(shutdown: CancellationToken) {
+    let mut set = JoinSet::new();
+    
+    for i in 0..4 {
+        let token = shutdown.child_token();
+        set.spawn(async move {
+            loop {
+                tokio::select! {
+                    _ = token.cancelled() => break,
+                    _ = do_work(i) => {}
+                }
+            }
+        });
+    }
+    
+    // Wait for shutdown
+    shutdown.cancelled().await;
+    
+    // Abort remaining tasks
+    set.abort_all();
+    
+    // Wait for all to finish (drain aborted tasks)
+    while set.join_next().await.is_some() {}
+}
+```
+
+## Spawning with Context
+
+```rust
+use tokio::task::JoinSet;
+
+let mut set: JoinSet<(usize, Result<Data, Error>)> = JoinSet::new();
+
+for (index, url) in urls.iter().enumerate() {
+    let url = url.clone();
+    set.spawn(async move {
+        (index, fetch(&url).await)
+    });
+}
+
+// Results include their index
+while let Some(result) = set.join_next().await {
+    if let Ok((index, data)) = result {
+        results[index] = Some(data);
+    }
+}
+```
+
+## JoinSet vs join_all
+
+| Feature | JoinSet | join_all |
+|---------|---------|----------|
+| Add tasks dynamically | Yes | No |
+| Results as-completed | Yes | No (all at once) |
+| Abort all on drop | Yes | No |
+| Cancel individual | Yes | No |
+| Memory efficient | Yes | Pre-allocates |
+
+## See Also
+
+- [async-join-parallel](./async-join-parallel.md) - Static concurrent futures
+- [async-cancellation-token](./async-cancellation-token.md) - Cancellation patterns
+- [async-try-join](./async-try-join.md) - Error handling in joins

package/template/agent/skills/rust-developer/references/rust-rules/async-mpsc-queue.md

@@ -0,0 +1,171 @@
+# async-mpsc-queue
+
+> Use `mpsc` channels for async message queues between tasks
+
+## Why It Matters
+
+`tokio::sync::mpsc` (multi-producer, single-consumer) is the workhorse channel for async Rust. It provides async send/receive, backpressure via bounded capacity, and efficient cloning of senders. It's the default choice for task-to-task communication.
+
+## Bad
+
+```rust
+use std::sync::mpsc;  // Wrong! Blocks the async runtime
+
+let (tx, rx) = std::sync::mpsc::channel();
+
+tokio::spawn(async move {
+    tx.send("hello").unwrap();  // Might block
+});
+
+tokio::spawn(async move {
+    let msg = rx.recv().unwrap();  // BLOCKS the executor thread!
+});
+```
+
+## Good
+
+```rust
+use tokio::sync::mpsc;
+
+let (tx, mut rx) = mpsc::channel::<String>(100);
+
+tokio::spawn(async move {
+    tx.send("hello".to_string()).await.unwrap();
+});
+
+tokio::spawn(async move {
+    while let Some(msg) = rx.recv().await {
+        println!("Received: {}", msg);
+    }
+});
+```
+
+## Sender Cloning
+
+```rust
+use tokio::sync::mpsc;
+
+let (tx, mut rx) = mpsc::channel::<Event>(100);
+
+// Multiple producers
+for i in 0..10 {
+    let tx = tx.clone();  // Cheap clone
+    tokio::spawn(async move {
+        tx.send(Event { source: i }).await.unwrap();
+    });
+}
+
+// Drop original sender so channel closes when all clones dropped
+drop(tx);
+
+// Consumer
+while let Some(event) = rx.recv().await {
+    process(event);
+}
+// Loop exits when all senders dropped
+```
+
+## Message Handler Pattern
+
+```rust
+use tokio::sync::mpsc;
+
+enum Command {
+    Get { key: String, reply: oneshot::Sender<Option<Value>> },
+    Set { key: String, value: Value },
+    Delete { key: String },
+}
+
+async fn run_store(mut commands: mpsc::Receiver<Command>) {
+    let mut store = HashMap::new();
+    
+    while let Some(cmd) = commands.recv().await {
+        match cmd {
+            Command::Get { key, reply } => {
+                let _ = reply.send(store.get(&key).cloned());
+            }
+            Command::Set { key, value } => {
+                store.insert(key, value);
+            }
+            Command::Delete { key } => {
+                store.remove(&key);
+            }
+        }
+    }
+}
+
+// Usage
+async fn client(tx: mpsc::Sender<Command>) -> Option<Value> {
+    let (reply_tx, reply_rx) = oneshot::channel();
+    
+    tx.send(Command::Get { 
+        key: "foo".to_string(), 
+        reply: reply_tx 
+    }).await.unwrap();
+    
+    reply_rx.await.unwrap()
+}
+```
+
+## Graceful Shutdown
+
+```rust
+async fn worker(mut rx: mpsc::Receiver<Task>, shutdown: CancellationToken) {
+    loop {
+        tokio::select! {
+            _ = shutdown.cancelled() => {
+                // Drain remaining messages
+                while let Ok(task) = rx.try_recv() {
+                    process(task).await;
+                }
+                break;
+            }
+            Some(task) = rx.recv() => {
+                process(task).await;
+            }
+            else => break,  // Channel closed
+        }
+    }
+}
+```
+
+## WeakSender for Optional Producers
+
+```rust
+use tokio::sync::mpsc;
+
+let (tx, mut rx) = mpsc::channel::<Message>(100);
+let weak = tx.downgrade();  // Doesn't keep channel alive
+
+tokio::spawn(async move {
+    // Strong sender - keeps channel alive
+    tx.send("from strong".into()).await.unwrap();
+});
+
+tokio::spawn(async move {
+    // Weak sender - may fail if strong senders dropped
+    if let Some(tx) = weak.upgrade() {
+        tx.send("from weak".into()).await.unwrap();
+    }
+});
+```
+
+## Permit Pattern
+
+```rust
+// Reserve slot before preparing message
+let permit = tx.reserve().await?;
+
+// Now we have guaranteed capacity
+let message = expensive_to_create_message();
+permit.send(message);  // Never fails
+
+// Useful when message creation is expensive
+// and you don't want to create it if channel is full
+```
+
+## See Also
+
+- [async-bounded-channel](./async-bounded-channel.md) - Why bounded channels
+- [async-oneshot-response](./async-oneshot-response.md) - Request-response with oneshot
+- [async-broadcast-pubsub](./async-broadcast-pubsub.md) - Multiple consumers