agy-superpowers 5.1.4 → 5.1.6

package/template/agent/skills/rust-developer/references/rust-rules/opt-inline-never-cold.md

@@ -0,0 +1,181 @@
+# opt-inline-never-cold
+
+> Use `#[inline(never)]` and `#[cold]` for error paths and rarely-executed code
+
+## Why It Matters
+
+Inlining error handling code into hot paths wastes instruction cache space and can prevent other optimizations. `#[inline(never)]` keeps cold code out of the hot path. `#[cold]` tells the compiler this branch is unlikely, enabling better branch prediction hints and code layout.
+
+## Bad
+
+```rust
+fn process_data(data: &[u8]) -> Result<Output, Error> {
+    if data.is_empty() {
+        // Error path inlined into hot function
+        return Err(Error::Empty {
+            context: format!("Expected data, got empty slice"),
+            suggestions: vec!["Check input", "Validate before calling"],
+        });
+    }
+    
+    // Hot path - now polluted with error construction code
+    do_processing(data)
+}
+```
+
+## Good
+
+```rust
+fn process_data(data: &[u8]) -> Result<Output, Error> {
+    if data.is_empty() {
+        return Err(empty_data_error());  // Cold path stays small
+    }
+    
+    do_processing(data)
+}
+
+#[cold]
+#[inline(never)]
+fn empty_data_error() -> Error {
+    Error::Empty {
+        context: format!("Expected data, got empty slice"),
+        suggestions: vec!["Check input", "Validate before calling"],
+    }
+}
+```
+
+## #[cold] for Unlikely Branches
+
+```rust
+fn parse_value(input: &str) -> Result<i32, ParseError> {
+    match input.parse() {
+        Ok(n) => Ok(n),
+        Err(e) => cold_parse_error(input, e),
+    }
+}
+
+#[cold]
+fn cold_parse_error(input: &str, e: std::num::ParseIntError) -> Result<i32, ParseError> {
+    Err(ParseError {
+        input: input.to_string(),
+        source: e,
+    })
+}
+```
+
+## Panic Paths
+
+```rust
+fn get_index(&self, idx: usize) -> &T {
+    if idx >= self.len {
+        cold_out_of_bounds(idx, self.len);
+    }
+    unsafe { self.ptr.add(idx).as_ref().unwrap() }
+}
+
+#[cold]
+#[inline(never)]
+fn cold_out_of_bounds(idx: usize, len: usize) -> ! {
+    panic!("index {} out of bounds for length {}", idx, len);
+}
+```
+
+## Error Construction Functions
+
+```rust
+// Keep error construction out of hot path
+impl MyError {
+    #[cold]
+    pub fn io_error(source: std::io::Error, path: &Path) -> Self {
+        MyError::Io {
+            source,
+            path: path.to_path_buf(),
+            context: get_context(),
+        }
+    }
+    
+    #[cold]
+    pub fn validation_error(msg: &str, field: &str) -> Self {
+        MyError::Validation {
+            message: msg.to_string(),
+            field: field.to_string(),
+        }
+    }
+}
+
+fn read_config(path: &Path) -> Result<Config, MyError> {
+    std::fs::read_to_string(path)
+        .map_err(|e| MyError::io_error(e, path))?
+        .parse()
+        .map_err(|e| MyError::parse_error(e))
+}
+```
+
+## likely/unlikely Hints
+
+```rust
+// Nightly: intrinsics for branch hints
+#![feature(core_intrinsics)]
+use std::intrinsics::{likely, unlikely};
+
+fn process(data: Option<&Data>) -> Result<Output, Error> {
+    if unlikely(data.is_none()) {
+        return cold_none_error();
+    }
+    
+    let data = data.unwrap();
+    
+    if likely(data.is_valid()) {
+        fast_process(data)
+    } else {
+        slow_validate_and_process(data)
+    }
+}
+
+// Stable alternative: structure code so hot path is "fall through"
+fn process(data: Option<&Data>) -> Result<Output, Error> {
+    let data = match data {
+        Some(d) => d,
+        None => return cold_none_error(),  // Early return = unlikely hint
+    };
+    
+    // Compiler assumes code after early returns is "hot"
+    fast_process(data)
+}
+```
+
+## Pattern: Extract Cold Code
+
+```rust
+// Before: cold code inline
+fn hot_function(x: i32) -> i32 {
+    if x < 0 {
+        log::error!("Negative value: {}", x);
+        eprintln!("Debug info: {:?}", std::backtrace::Backtrace::capture());
+        return 0;
+    }
+    x * 2
+}
+
+// After: cold code extracted
+fn hot_function(x: i32) -> i32 {
+    if x < 0 {
+        return handle_negative(x);
+    }
+    x * 2
+}
+
+#[cold]
+#[inline(never)]
+fn handle_negative(x: i32) -> i32 {
+    log::error!("Negative value: {}", x);
+    eprintln!("Debug info: {:?}", std::backtrace::Backtrace::capture());
+    0
+}
+```
+
+## See Also
+
+- [opt-inline-small](./opt-inline-small.md) - Inlining for hot code
+- [opt-inline-always-rare](./opt-inline-always-rare.md) - Forced inlining
+- [err-result-over-panic](./err-result-over-panic.md) - Error handling patterns

package/template/agent/skills/rust-developer/references/rust-rules/opt-inline-small.md

@@ -0,0 +1,160 @@
+# opt-inline-small
+
+> Use `#[inline]` for small hot functions
+
+## Why It Matters
+
+Function call overhead (stack frame setup, register saves, jumps) can dominate small functions. Inlining eliminates this overhead and enables further optimizations by the compiler. The compiler often inlines automatically, but hints help for cross-crate calls.
+
+## Bad
+
+```rust
+// Small hot function without inline hint
+// May not be inlined across crate boundaries
+fn is_ascii_digit(b: u8) -> bool {
+    b >= b'0' && b <= b'9'
+}
+
+// Called millions of times
+for byte in data {
+    if is_ascii_digit(*byte) {  // Function call overhead
+        count += 1;
+    }
+}
+```
+
+## Good
+
+```rust
+#[inline]
+fn is_ascii_digit(b: u8) -> bool {
+    b >= b'0' && b <= b'9'
+}
+
+// Now the compiler will inline this
+for byte in data {
+    if is_ascii_digit(*byte) {  // Inlined, no call overhead
+        count += 1;
+    }
+}
+```
+
+## Inline Attributes
+
+```rust
+// No attribute - compiler decides (usually good for same-crate)
+fn auto_decide() { }
+
+// Suggest inlining - helps cross-crate
+#[inline]
+fn suggest_inline() { }
+
+// Strongly suggest inlining - almost always inlined
+#[inline(always)]
+fn force_inline() { }
+
+// Strongly suggest NOT inlining - for large/cold code
+#[inline(never)]
+fn prevent_inline() { }
+```
+
+## When to Use Each
+
+```rust
+// #[inline] - Small functions, especially in libraries
+#[inline]
+pub fn len(&self) -> usize {
+    self.inner.len()
+}
+
+// #[inline(always)] - Critical hot path, verified by profiling
+#[inline(always)]
+fn hot_inner_loop_helper(x: u32) -> u32 {
+    x.wrapping_mul(0x9E3779B9)
+}
+
+// #[inline(never)] - Error handlers, cold paths
+#[inline(never)]
+fn handle_error(err: Error) -> ! {
+    eprintln!("Fatal: {}", err);
+    std::process::exit(1);
+}
+
+// No attribute - large functions, infrequent calls
+fn complex_processing(data: &mut Data) {
+    // Many lines of code...
+}
+```
+
+## Evidence from ripgrep
+
+```rust
+// https://github.com/BurntSushi/ripgrep/blob/master/crates/printer/src/standard.rs
+
+#[inline(always)]
+fn write_prelude(
+    &self,
+    absolute_byte_offset: u64,
+    line_number: Option<u64>,
+    column: Option<u64>,
+) -> io::Result<()> {
+    // Hot path in printing matches
+}
+
+#[inline(always)]
+fn write_line(&self, line: &[u8]) -> io::Result<()> {
+    // Called for every line
+}
+```
+
+## Generic Functions
+
+```rust
+// Generic functions are already candidates for per-monomorphization inlining
+// But #[inline] helps ensure it across crates
+
+#[inline]
+pub fn min<T: Ord>(a: T, b: T) -> T {
+    if a < b { a } else { b }
+}
+```
+
+## Cautions
+
+```rust
+// DON'T inline large functions - hurts instruction cache
+#[inline(always)]  // BAD for large function
+fn large_complex_function(data: &mut [u8]) {
+    // 100+ lines of code
+    // Inlining bloats every call site
+}
+
+// DON'T assume inlining always helps - measure!
+// Sometimes the compiler makes better decisions
+
+// Inlining is non-transitive
+#[inline]
+fn outer() {
+    inner();  // inner() also needs #[inline] to be inlined together
+}
+
+fn inner() { }  // Won't be inlined at outer's call sites
+```
+
+## Verifying Inlining
+
+```bash
+# Check if function was inlined using Cachegrind
+# Non-inlined functions show entry/exit counts
+
+# Or examine assembly
+cargo rustc --release -- --emit=asm
+# Look for call instructions vs inlined code
+```
+
+## See Also
+
+- [opt-inline-always-rare](opt-inline-always-rare.md) - Use #[inline(always)] sparingly
+- [opt-inline-never-cold](opt-inline-never-cold.md) - Use #[inline(never)] for cold paths
+- [opt-cold-unlikely](opt-cold-unlikely.md) - Use #[cold] for unlikely paths
+- [opt-lto-release](opt-lto-release.md) - LTO enables cross-crate inlining

package/template/agent/skills/rust-developer/references/rust-rules/opt-likely-hint.md

@@ -0,0 +1,171 @@
+# opt-likely-hint
+
+> Use code structure to hint at likely branches; use intrinsics on nightly
+
+## Why It Matters
+
+Modern CPUs predict branches to speculatively execute code. Mispredictions cause pipeline stalls (10-20 cycles). Helping the compiler understand which branches are likely allows it to generate optimal code layout and branch hints, improving performance in hot paths.
+
+## Stable Rust: Code Structure Hints
+
+```rust
+// Pattern 1: Early returns for unlikely cases
+fn process(data: Option<&Data>) -> i32 {
+    // Compiler assumes early return is "unlikely"
+    let data = match data {
+        None => return 0,  // Unlikely
+        Some(d) => d,
+    };
+    
+    // Hot path continues here
+    complex_processing(data)
+}
+
+// Pattern 2: if-else ordering
+fn calculate(x: i32) -> i32 {
+    if x >= 0 {
+        // Put likely case in "if" branch
+        x * 2
+    } else {
+        // Unlikely case in "else"
+        handle_negative(x)
+    }
+}
+
+// Pattern 3: Cold function extraction
+fn hot_path(data: &[u8]) -> Result<(), Error> {
+    if data.is_empty() {
+        return cold_empty_error();  // Extracted = unlikely
+    }
+    
+    process_fast(data)
+}
+
+#[cold]
+fn cold_empty_error() -> Result<(), Error> {
+    Err(Error::EmptyInput)
+}
+```
+
+## Nightly: Intrinsics
+
+```rust
+#![feature(core_intrinsics)]
+use std::intrinsics::{likely, unlikely};
+
+fn process(data: &Data) -> i32 {
+    if unlikely(data.is_corrupted()) {
+        return handle_corruption(data);
+    }
+    
+    if likely(data.is_cached()) {
+        return fast_cached_path(data);
+    }
+    
+    slow_uncached_path(data)
+}
+```
+
+## Boolean Likely Wrapper (Nightly)
+
+```rust
+#![feature(core_intrinsics)]
+
+#[inline(always)]
+fn likely(b: bool) -> bool {
+    std::intrinsics::likely(b)
+}
+
+#[inline(always)]
+fn unlikely(b: bool) -> bool {
+    std::intrinsics::unlikely(b)
+}
+
+// Usage
+if likely(x > 0) {
+    hot_path(x)
+} else {
+    cold_path(x)
+}
+```
+
+## Stable: likely-stable Crate
+
+```rust
+use likely_stable::{likely, unlikely};
+
+fn check(value: i32) -> bool {
+    if unlikely(value < 0) {
+        handle_negative()
+    } else if likely(value < 1000) {
+        handle_common()
+    } else {
+        handle_large()
+    }
+}
+```
+
+## Loop Optimization
+
+```rust
+fn search(data: &[i32], target: i32) -> Option<usize> {
+    for (i, &item) in data.iter().enumerate() {
+        // Assume most iterations DON'T find the target
+        if unlikely(item == target) {
+            return Some(i);
+        }
+    }
+    None
+}
+
+// Alternative: structure for likely case
+fn search_common(data: &[i32], target: i32) -> Option<usize> {
+    // If target is usually found
+    for (i, &item) in data.iter().enumerate() {
+        if likely(item == target) {
+            return Some(i);
+        }
+    }
+    None
+}
+```
+
+## Match Arm Ordering
+
+```rust
+// Put most common variants first
+fn process_message(msg: Message) {
+    match msg {
+        // Most common - listed first
+        Message::Data(d) => handle_data(d),
+        Message::Heartbeat => (), // Second most common
+        
+        // Rare cases last
+        Message::Error(e) => handle_error(e),
+        Message::Shutdown => shutdown(),
+    }
+}
+```
+
+## Benchmark-Driven Hints
+
+```rust
+// Profile first to know which branches are actually likely!
+fn speculative(x: i32) -> i32 {
+    // DON'T GUESS - measure with profiling
+    // perf record / perf report
+    // cargo flamegraph
+    
+    if x > threshold {  // Is this actually common?
+        path_a(x)
+    } else {
+        path_b(x)
+    }
+}
+```
+
+## See Also
+
+- [opt-cold-unlikely](./opt-cold-unlikely.md) - #[cold] for unlikely functions
+- [opt-inline-never-cold](./opt-inline-never-cold.md) - Keeping cold code separate
+- [perf-profile-first](./perf-profile-first.md) - Profile to know what's likely

package/template/agent/skills/rust-developer/references/rust-rules/opt-lto-release.md

@@ -0,0 +1,130 @@
+# opt-lto-release
+
+> Enable LTO in release builds
+
+## Why It Matters
+
+Link-Time Optimization (LTO) enables optimizations across crate boundaries that aren't possible during normal compilation. This includes cross-crate inlining, dead code elimination, and devirtualization. Typically provides 5-20% performance improvement.
+
+## Bad
+
+```toml
+# Cargo.toml - default release profile
+[profile.release]
+opt-level = 3
+# No LTO = missed optimization opportunities
+```
+
+## Good
+
+```toml
+# Cargo.toml - optimized release profile
+[profile.release]
+opt-level = 3
+lto = "fat"          # Maximum optimization
+codegen-units = 1    # Better optimization (single codegen unit)
+panic = "abort"      # Smaller binary, no unwind tables
+strip = true         # Remove symbols for smaller binary
+```
+
+## LTO Options Explained
+
+```toml
+# No LTO (default)
+lto = false
+
+# Thin LTO - fast compilation, most benefits
+lto = "thin"
+
+# Fat LTO - slowest compilation, maximum optimization
+lto = "fat"
+# Equivalent to:
+lto = true
+
+# Thin-local - LTO within each crate only
+lto = "off"
+```
+
+## Trade-offs
+
+| Setting | Compile Time | Binary Size | Performance |
+|---------|--------------|-------------|-------------|
+| `lto = false` | Fast | Larger | Baseline |
+| `lto = "thin"` | Medium | Smaller | +5-15% |
+| `lto = "fat"` | Slow | Smallest | +10-20% |
+
+## Evidence from Production
+
+```toml
+# From Anchor (Solana framework)
+# https://github.com/solana-foundation/anchor/blob/master/cli/src/rust_template.rs
+[profile.release]
+overflow-checks = true
+lto = "fat"
+codegen-units = 1
+
+# From sol-trade-sdk
+# https://github.com/0xfnzero/sol-trade-sdk
+[profile.release]
+opt-level = 3
+lto = "fat"
+codegen-units = 1
+panic = "abort"
+```
+
+## Complete Optimized Profile
+
+```toml
+[profile.release]
+opt-level = 3        # Maximum optimization
+lto = "fat"          # Link-time optimization
+codegen-units = 1    # Single codegen unit for better optimization
+panic = "abort"      # Remove panic unwinding code
+strip = true         # Strip symbols
+debug = false        # No debug info
+
+# For benchmarking (need some debug info for profiling)
+[profile.bench]
+inherits = "release"
+debug = true
+strip = false
+
+# Fast dev builds with optimized dependencies
+[profile.dev]
+opt-level = 0
+debug = true
+
+[profile.dev.package."*"]
+opt-level = 3        # Optimize dependencies even in dev
+```
+
+## When to Use Each
+
+| Situation | LTO Setting |
+|-----------|-------------|
+| Development | `false` (fast compiles) |
+| CI builds | `"thin"` (balance) |
+| Release binaries | `"fat"` (max perf) |
+| Libraries (crates.io) | `false` (users choose) |
+
+## Measuring Impact
+
+```bash
+# Build without LTO
+cargo build --release
+hyperfine ./target/release/myapp
+
+# Build with LTO
+# (after adding lto = "fat" to Cargo.toml)
+cargo build --release
+hyperfine ./target/release/myapp
+
+# Compare binary sizes
+ls -la target/release/myapp
+```
+
+## See Also
+
+- [opt-codegen-units](opt-codegen-units.md) - Use codegen-units = 1
+- [opt-pgo-profile](opt-pgo-profile.md) - Profile-guided optimization
+- [perf-release-profile](perf-release-profile.md) - Full release profile settings