agy-superpowers 5.1.3 → 5.1.5

package/template/agent/skills/rust-developer/references/rust-rules/own-mutex-interior.md

@@ -0,0 +1,105 @@
+# own-mutex-interior
+
+> Use `Mutex<T>` for interior mutability across threads
+
+## Why It Matters
+
+When you need shared mutable state across threads, `Mutex<T>` provides safe interior mutability with synchronization. Unlike `RefCell`, `Mutex` is `Send + Sync` and uses OS-level locking to ensure only one thread can access the data at a time.
+
+## Bad
+
+```rust
+use std::cell::RefCell;
+use std::sync::Arc;
+
+// RefCell is !Sync - this won't compile
+let shared = Arc::new(RefCell::new(vec![]));
+
+// ERROR: RefCell cannot be shared between threads safely
+std::thread::spawn({
+    let shared = shared.clone();
+    move || shared.borrow_mut().push(1)
+});
+```
+
+## Good
+
+```rust
+use std::sync::{Arc, Mutex};
+
+let shared = Arc::new(Mutex::new(vec![]));
+
+let handles: Vec<_> = (0..10).map(|i| {
+    let shared = shared.clone();
+    std::thread::spawn(move || {
+        let mut data = shared.lock().unwrap();
+        data.push(i);
+    })
+}).collect();
+
+for handle in handles {
+    handle.join().unwrap();
+}
+
+println!("{:?}", shared.lock().unwrap()); // All values present
+```
+
+## Mutex Poisoning
+
+If a thread panics while holding a lock, the mutex becomes "poisoned":
+
+```rust
+use std::sync::{Arc, Mutex};
+
+let mutex = Arc::new(Mutex::new(0));
+
+// Handle poisoning gracefully
+match mutex.lock() {
+    Ok(guard) => println!("Value: {}", *guard),
+    Err(poisoned) => {
+        // Recover the data anyway
+        let guard = poisoned.into_inner();
+        println!("Recovered value: {}", *guard);
+    }
+}
+
+// Or ignore poisoning (use with caution)
+let guard = mutex.lock().unwrap_or_else(|e| e.into_inner());
+```
+
+## Prefer parking_lot::Mutex
+
+For better performance, consider `parking_lot::Mutex`:
+
+```rust
+use parking_lot::Mutex;
+use std::sync::Arc;
+
+let shared = Arc::new(Mutex::new(vec![]));
+
+// No poisoning, no Result to unwrap
+let mut data = shared.lock();
+data.push(42);
+// Lock automatically released when guard drops
+```
+
+Benefits of `parking_lot`:
+- No poisoning (returns guard directly)
+- Smaller size (1 byte vs 40+ bytes)
+- Better performance under contention
+- Fair locking option available
+
+## When to Use What
+
+| Type | Threading | Overhead | Use Case |
+|------|-----------|----------|----------|
+| `RefCell<T>` | Single | Minimal | Interior mutability, same thread |
+| `Mutex<T>` | Multi | Locking | Shared mutable state across threads |
+| `RwLock<T>` | Multi | Locking | Many readers, few writers |
+| `parking_lot::Mutex` | Multi | Less | Drop-in std::Mutex replacement |
+
+## See Also
+
+- [own-rwlock-readers](./own-rwlock-readers.md) - When reads dominate writes
+- [own-refcell-interior](./own-refcell-interior.md) - Single-threaded alternative
+- [async-no-lock-await](./async-no-lock-await.md) - Avoiding locks across await points

package/template/agent/skills/rust-developer/references/rust-rules/own-rc-single-thread.md

@@ -0,0 +1,65 @@
+# own-rc-single-thread
+
+> Use `Rc<T>` for shared ownership in single-threaded contexts
+
+## Why It Matters
+
+`Rc<T>` (Reference Counted) provides shared ownership without the atomic overhead of `Arc<T>`. In single-threaded code, `Rc` is faster because it uses non-atomic reference counting. Using `Arc` when you don't need thread-safety wastes CPU cycles on unnecessary synchronization.
+
+## Bad
+
+```rust
+use std::sync::Arc;
+
+// Single-threaded application using Arc unnecessarily
+fn build_tree() -> Arc<Node> {
+    let root = Arc::new(Node::new("root"));
+    let child1 = Arc::new(Node::new("child1"));
+    let child2 = Arc::new(Node::new("child2"));
+    
+    // All in same thread, but paying atomic overhead
+    root.add_child(child1.clone());
+    root.add_child(child2.clone());
+    root
+}
+```
+
+Atomic operations have measurable overhead even without contention.
+
+## Good
+
+```rust
+use std::rc::Rc;
+
+// Single-threaded: use Rc for zero atomic overhead
+fn build_tree() -> Rc<Node> {
+    let root = Rc::new(Node::new("root"));
+    let child1 = Rc::new(Node::new("child1"));
+    let child2 = Rc::new(Node::new("child2"));
+    
+    root.add_child(child1.clone());
+    root.add_child(child2.clone());
+    root
+}
+
+// Compiler enforces single-thread: Rc is !Send + !Sync
+// Attempting to send across threads = compile error
+```
+
+## Decision Guide
+
+| Scenario | Use |
+|----------|-----|
+| Single-threaded, shared ownership | `Rc<T>` |
+| Multi-threaded, shared ownership | `Arc<T>` |
+| Single owner, might need multiple later | Start with `Rc`, upgrade if needed |
+| Library code, unknown threading model | `Arc<T>` (safer default) |
+
+## Evidence
+
+The Rust standard library itself uses `Rc` extensively in single-threaded contexts like the `std::rc` module documentation examples.
+
+## See Also
+
+- [own-arc-shared](./own-arc-shared.md) - When you need thread-safe sharing
+- [own-refcell-interior](./own-refcell-interior.md) - Combining Rc with interior mutability

package/template/agent/skills/rust-developer/references/rust-rules/own-refcell-interior.md

@@ -0,0 +1,97 @@
+# own-refcell-interior
+
+> Use `RefCell<T>` for interior mutability in single-threaded code
+
+## Why It Matters
+
+Rust's borrow checker enforces rules at compile time, but sometimes you need to mutate data through a shared reference. `RefCell<T>` moves borrow checking to runtime, allowing mutation through `&self`. This is essential for patterns like caches, lazy initialization, and observer patterns where compile-time borrowing is too restrictive.
+
+## Bad
+
+```rust
+struct Cache {
+    // Requires &mut self to update, breaking shared reference patterns
+    data: HashMap<String, String>,
+}
+
+impl Cache {
+    fn get_or_compute(&mut self, key: &str) -> &str {
+        // Caller needs &mut Cache, can't share cache reference
+        if !self.data.contains_key(key) {
+            self.data.insert(key.to_string(), expensive_compute(key));
+        }
+        &self.data[key]
+    }
+}
+```
+
+This forces exclusive access even for logically shared operations.
+
+## Good
+
+```rust
+use std::cell::RefCell;
+use std::collections::HashMap;
+
+struct Cache {
+    data: RefCell<HashMap<String, String>>,
+}
+
+impl Cache {
+    fn get_or_compute(&self, key: &str) -> String {
+        // Can mutate through &self
+        let mut data = self.data.borrow_mut();
+        if !data.contains_key(key) {
+            data.insert(key.to_string(), expensive_compute(key));
+        }
+        data[key].clone()
+    }
+}
+
+// Multiple references can coexist
+let cache = Cache::new();
+let ref1 = &cache;
+let ref2 = &cache;
+ref1.get_or_compute("key1");
+ref2.get_or_compute("key2");
+```
+
+## Common Pattern: Rc<RefCell<T>>
+
+```rust
+use std::rc::Rc;
+use std::cell::RefCell;
+
+// Shared mutable state in single-threaded code
+type SharedState = Rc<RefCell<AppState>>;
+
+fn create_handlers(state: SharedState) -> Vec<Box<dyn Fn()>> {
+    vec![
+        Box::new({
+            let state = state.clone();
+            move || state.borrow_mut().increment()
+        }),
+        Box::new({
+            let state = state.clone();
+            move || state.borrow_mut().decrement()
+        }),
+    ]
+}
+```
+
+## Runtime Panics
+
+`RefCell` panics if you violate borrowing rules at runtime:
+
+```rust
+let cell = RefCell::new(5);
+let borrow1 = cell.borrow();
+let borrow2 = cell.borrow_mut(); // PANIC: already borrowed
+```
+
+Use `try_borrow()` and `try_borrow_mut()` for fallible borrowing.
+
+## See Also
+
+- [own-rc-single-thread](./own-rc-single-thread.md) - Combining with Rc for shared ownership
+- [own-mutex-interior](./own-mutex-interior.md) - Thread-safe alternative

package/template/agent/skills/rust-developer/references/rust-rules/own-rwlock-readers.md

@@ -0,0 +1,122 @@
+# own-rwlock-readers
+
+> Use `RwLock<T>` when reads significantly outnumber writes
+
+## Why It Matters
+
+`Mutex<T>` allows only one thread to access data at a time, even for reads. `RwLock<T>` allows multiple concurrent readers OR one exclusive writer. For read-heavy workloads, this dramatically improves throughput by eliminating unnecessary serialization of read operations.
+
+## Bad
+
+```rust
+use std::sync::{Arc, Mutex};
+
+// Configuration rarely changes but is read constantly
+let config = Arc::new(Mutex::new(Config::load()));
+
+// Every read blocks other reads unnecessarily
+fn get_setting(config: &Mutex<Config>, key: &str) -> String {
+    let guard = config.lock().unwrap();
+    guard.get(key).to_string()
+}
+
+// 100 threads reading = serialized, one at a time
+```
+
+## Good
+
+```rust
+use std::sync::{Arc, RwLock};
+
+// Multiple readers can proceed concurrently
+let config = Arc::new(RwLock::new(Config::load()));
+
+fn get_setting(config: &RwLock<Config>, key: &str) -> String {
+    let guard = config.read().unwrap(); // Multiple threads can hold read lock
+    guard.get(key).to_string()
+}
+
+fn update_setting(config: &RwLock<Config>, key: &str, value: &str) {
+    let mut guard = config.write().unwrap(); // Exclusive access for writes
+    guard.set(key, value);
+}
+
+// 100 threads reading = parallel execution
+```
+
+## parking_lot::RwLock
+
+Prefer `parking_lot::RwLock` for better performance:
+
+```rust
+use parking_lot::RwLock;
+use std::sync::Arc;
+
+let data = Arc::new(RwLock::new(HashMap::new()));
+
+// Read - no unwrap needed
+let value = data.read().get("key").cloned();
+
+// Write
+data.write().insert("key".to_string(), "value".to_string());
+
+// Upgradeable read lock (unique to parking_lot)
+let upgradeable = data.upgradable_read();
+if upgradeable.get("key").is_none() {
+    let mut write = parking_lot::RwLockUpgradableReadGuard::upgrade(upgradeable);
+    write.insert("key".to_string(), "default".to_string());
+}
+```
+
+## When RwLock Hurts
+
+RwLock has overhead for tracking readers. It can be slower than Mutex when:
+
+| Scenario | Better Choice |
+|----------|---------------|
+| Writes are frequent (>20% of operations) | `Mutex` |
+| Lock held very briefly | `Mutex` |
+| Single-threaded | `RefCell` |
+| Reads dominate, lock held longer | `RwLock` |
+
+## Write Starvation
+
+Standard `RwLock` may starve writers if readers are continuous. `parking_lot::RwLock` is fair by default.
+
+```rust
+// parking_lot is writer-fair, preventing starvation
+use parking_lot::RwLock;
+
+// Or use std with explicit fairness (nightly)
+// #![feature(rwlock_downgrade)]
+```
+
+## Real-World Pattern: Cached Computation
+
+```rust
+use parking_lot::RwLock;
+use std::sync::Arc;
+
+struct CachedData {
+    cache: RwLock<Option<ExpensiveResult>>,
+}
+
+impl CachedData {
+    fn get(&self) -> ExpensiveResult {
+        // Fast path: read lock
+        if let Some(cached) = self.cache.read().as_ref() {
+            return cached.clone();
+        }
+        
+        // Slow path: compute and cache
+        let result = compute_expensive();
+        *self.cache.write() = Some(result.clone());
+        result
+    }
+}
+```
+
+## See Also
+
+- [own-mutex-interior](./own-mutex-interior.md) - When writes are frequent
+- [async-no-lock-await](./async-no-lock-await.md) - RwLock in async contexts

package/template/agent/skills/rust-developer/references/rust-rules/own-slice-over-vec.md

@@ -0,0 +1,119 @@
+# own-slice-over-vec
+
+> Accept `&[T]` not `&Vec<T>`, `&str` not `&String`
+
+## Why It Matters
+
+Accepting `&[T]` instead of `&Vec<T>` makes your function more flexible - it can accept slices from arrays, vectors, or other sources. Similarly, `&str` accepts string slices from `String`, `&'static str`, or substrings.
+
+## Bad
+
+```rust
+// Overly restrictive - only accepts &Vec
+fn sum(numbers: &Vec<i32>) -> i32 {
+    numbers.iter().sum()
+}
+
+// Overly restrictive - only accepts &String
+fn greet(name: &String) {
+    println!("Hello, {}", name);
+}
+
+// Can't call with arrays or slices
+let arr = [1, 2, 3];
+// sum(&arr);  // ERROR: expected &Vec<i32>
+
+let literal = "world";
+// greet(&literal);  // ERROR: expected &String
+```
+
+## Good
+
+```rust
+// Flexible - accepts any slice-like thing
+fn sum(numbers: &[i32]) -> i32 {
+    numbers.iter().sum()
+}
+
+// Flexible - accepts any string-like thing
+fn greet(name: &str) {
+    println!("Hello, {}", name);
+}
+
+// Now all of these work:
+let vec = vec![1, 2, 3];
+let arr = [4, 5, 6];
+let slice = &vec[0..2];
+
+sum(&vec);    // Vec coerces to slice
+sum(&arr);    // Array coerces to slice
+sum(slice);   // Slice works directly
+
+let string = String::from("Alice");
+let literal = "Bob";
+
+greet(&string);  // String coerces to &str
+greet(literal);  // &str works directly
+```
+
+## The Deref Coercion Chain
+
+```rust
+// These coercions happen automatically:
+// Vec<T>  -> &[T]   (via Deref)
+// String  -> &str   (via Deref)
+// Box<T>  -> &T     (via Deref)
+// Arc<T>  -> &T     (via Deref)
+
+fn process(data: &[u8]) { /* ... */ }
+
+let vec: Vec<u8> = vec![1, 2, 3];
+let boxed: Box<[u8]> = vec.into_boxed_slice();
+let arc: Arc<[u8]> = Arc::from(&[1, 2, 3][..]);
+
+process(&vec);    // Works
+process(&boxed);  // Works
+process(&arc);    // Works
+```
+
+## Path Types Too
+
+```rust
+// Bad
+fn read_config(path: &PathBuf) -> Config { /* ... */ }
+
+// Good - accepts &Path, &PathBuf, &str, &String
+fn read_config(path: &Path) -> Config { /* ... */ }
+
+// Even better - accept anything path-like
+fn read_config(path: impl AsRef<Path>) -> Config {
+    let path = path.as_ref();
+    // ...
+}
+```
+
+## When to Accept Owned Types
+
+```rust
+// Accept owned when you need to store it
+struct Logger {
+    prefix: String,  // Needs to own the string
+}
+
+impl Logger {
+    // Take ownership - caller decides to clone or move
+    fn new(prefix: String) -> Self {
+        Self { prefix }
+    }
+    
+    // Or use Into for flexibility
+    fn with_prefix(prefix: impl Into<String>) -> Self {
+        Self { prefix: prefix.into() }
+    }
+}
+```
+
+## See Also
+
+- [api-impl-asref](api-impl-asref.md) - Accept `impl AsRef<T>` for maximum flexibility
+- [own-borrow-over-clone](own-borrow-over-clone.md) - Prefer borrowing over cloning

package/template/agent/skills/rust-developer/references/rust-rules/perf-black-box-bench.md

@@ -0,0 +1,153 @@
+# perf-black-box-bench
+
+> Use black_box in benchmarks
+
+## Why It Matters
+
+The compiler aggressively optimizes code, potentially eliminating computations whose results aren't used. In benchmarks, this can lead to measuring nothing instead of the actual code. `std::hint::black_box()` prevents the compiler from optimizing away values, ensuring accurate measurements.
+
+## Bad
+
+```rust
+use criterion::{black_box, criterion_group, criterion_main, Criterion};
+
+fn benchmark_bad(c: &mut Criterion) {
+    c.bench_function("compute", |b| {
+        b.iter(|| {
+            let result = expensive_computation(42);
+            // Result unused - compiler may eliminate the call!
+        });
+    });
+}
+
+fn benchmark_also_bad(c: &mut Criterion) {
+    let input = 42;  // Constant - compiler may precompute
+    
+    c.bench_function("compute", |b| {
+        b.iter(|| {
+            expensive_computation(input)
+            // Return value may still be optimized away
+        });
+    });
+}
+```
+
+## Good
+
+```rust
+use criterion::{black_box, criterion_group, criterion_main, Criterion};
+
+fn benchmark_good(c: &mut Criterion) {
+    c.bench_function("compute", |b| {
+        b.iter(|| {
+            // black_box on input prevents constant folding
+            let result = expensive_computation(black_box(42));
+            // black_box on output prevents dead code elimination
+            black_box(result)
+        });
+    });
+}
+
+// Or simpler with Criterion's built-in support
+fn benchmark_simpler(c: &mut Criterion) {
+    c.bench_function("compute", |b| {
+        b.iter(|| expensive_computation(black_box(42)))
+    });
+}
+```
+
+## What black_box Does
+
+| Without black_box | With black_box |
+|-------------------|----------------|
+| Input may be constant-folded | Input treated as unknown |
+| Result may be eliminated | Result must be computed |
+| Loops may be optimized away | Each iteration runs |
+| Functions may be inlined | Call semantics preserved |
+
+## Standard Library Usage
+
+```rust
+use std::hint::black_box;
+
+fn main() {
+    // In std since Rust 1.66
+    let result = black_box(compute_something(black_box(input)));
+}
+```
+
+## Criterion's black_box
+
+Criterion re-exports `std::hint::black_box`:
+
+```rust
+use criterion::black_box;
+
+// Equivalent to std::hint::black_box
+```
+
+## Pattern: Benchmark with Setup
+
+```rust
+fn benchmark_with_setup(c: &mut Criterion) {
+    c.bench_function("process_data", |b| {
+        // Setup outside iter - not measured
+        let data = generate_test_data(1000);
+        
+        b.iter(|| {
+            // black_box the input reference
+            let result = process(black_box(&data));
+            black_box(result)
+        });
+    });
+}
+```
+
+## Pattern: Benchmark Multiple Inputs
+
+```rust
+fn benchmark_sizes(c: &mut Criterion) {
+    let mut group = c.benchmark_group("scaling");
+    
+    for size in [100, 1000, 10000] {
+        let data = generate_data(size);
+        
+        group.bench_with_input(
+            BenchmarkId::from_parameter(size),
+            &data,
+            |b, data| {
+                b.iter(|| process(black_box(data)))
+            },
+        );
+    }
+    group.finish();
+}
+```
+
+## Common Mistakes
+
+```rust
+// WRONG: black_box inside loop does nothing useful
+for _ in 0..1000 {
+    black_box(());  // Doesn't help
+    compute();
+}
+
+// RIGHT: black_box the computation result
+for _ in 0..1000 {
+    black_box(compute());
+}
+
+// WRONG: Only blocking output, not input
+let x = 42;  // Constant, may be optimized
+black_box(expensive(x));
+
+// RIGHT: Block both
+black_box(expensive(black_box(42)));
+```
+
+## See Also
+
+- [test-criterion-bench](./test-criterion-bench.md) - Using Criterion
+- [perf-profile-first](./perf-profile-first.md) - Profile before optimize
+- [perf-release-profile](./perf-release-profile.md) - Release settings