Rust Optimize

Rust Optimization

Optimize *.rs files in the target scope using the checklist below. This is a LOOP. You keep optimizing until you cannot find anything to optimize.

Termination

After each turn, end your response with exactly one of:

• Continue optimizing remaining files. — you made code changes this turn
• No optimizations this pass. — you read files but changed nothing

If you only summarized what you read without changing code, say "no optimizations this pass".

Checklist

1. Complexity: O(n) scan → O(1) lookup, merge HashMap lookups, merge loops, boundary-vs-volume (Stokes/divergence theorem: integrate boundary O(n^{(d-1)/d}) instead of interior O(n) for low-dim d≤3 region mass queries — curse-of-dim caps it at d≤3)
2. Allocations: String → &'static str, pre-allocate, eliminate .to_string()
3. Layout: field reorder (u64→u32→u8), #[repr(u8)] enums, remove #[repr(C)]
4. Arithmetic: f32 counters → u32/u64
5. Iterators: fix double chunks_exact(), use index arithmetic
6. Concurrency: Arc<RwLock<HashMap>> → papaya, Mutex<u32> → AtomicU32
7. SIMD: chunked loops, branch-free inner loops
8. Caching: pre-compute lookup tables, compute once not N×M
9. Errors: unwrap() → ?, let _ = → .log_err()
10. Bevy / Real-time loop (see § Bevy / Real-time Loop for details):
    • Event loop spin: WinitSettings::default() (Continuous) pegs CPU at 100% even idle — switch to UpdateMode::reactive_low_power(max_wait) matching tick rate
    • Vsync ≠ event loop: PresentMode::Fifo controls GPU only, independent of CPU loop spin
    • Static geometry: bake to LineList / TriangleList mesh once, NEVER redraw via gizmos.line() per-frame (each call is CPU + per-frame buffer grow)
    • Asset lifecycle: despawning a Bevy Entity does NOT release its Assets<Mesh> / Assets<StandardMaterial> handles — call meshes.remove(handle.0.id()) + materials.remove(...) on despawn or leak indefinitely (regrow-on-new-EntityId patterns leak ~N assets per cycle)
    • GUI repaint storms: bevy_egui sets set_request_repaint_callback that fires bevy_winit::WakeUp on delay.is_zero() — bypasses reactive max_wait and spins the loop. Diagnose via in-process perf overlay before assuming the engine itself is the hog.
    • Frame-rate cap fallback: a Last-schedule std::thread::sleep system capped at e.g. 60 FPS is a belt-and-suspenders defense when vsync + reactive mode somehow don't throttle
11. Perf diagnosis: ship an in-process perf overlay (sysinfo for CPU/RAM + Bevy's Time::delta() for FPS) inside the GUI itself — external ps sampling misses focused-window swings and requires keeping a terminal attached

Rules

• Do NOT create plans or issues.
• Do NOT create new files unless necessary.
• Commit when done (perf: or refactor: prefix).
• Use sigmoid, not softmax.

Optimization Skill

Hot-path Rust optimization patterns. Apply to any microsecond-sensitive code.

When to Optimize

1. Profile first — never optimize without numbers
2. Identify the top 3 bottlenecks (80% of time is in 20% of code)
3. Measure after each change — some "optimizations" make things worse
4. Run both debug (reveals algorithmic cost) and release (reveals compiler optimizations)

Do

Profiling

• Break down complex functions into per-component micro-benchmarks
• Use std::hint::black_box() to prevent dead-code elimination
• Warm up before measuring (100+ iterations) to prime CPU caches
• Run 10,000+ iterations for stable results
• Print component-level breakdowns with --nocapture test harness
• Compare same-commit, back-to-back runs to isolate feature impact from system noise

Data Structures

• Use fixed-size arrays [T; N] when domain is bounded
• Pre-compute lookup tables once, store in config/context — O(1) reads beat O(n) scans
• Track per-slot aggregates during insert/evict instead of scanning on read
• Cache allocations: Vec::with_capacity() once, clear() + reuse across calls
• Pass pre-allocated scratch buffers as &mut [T] parameters instead of allocating inside hot loops

Manifold / Cell-Complex Geometry

For code operating on cell complexes / meshes / grid manifolds (DEC, FEM, game maps):

• Boundary-vs-volume (Stokes / divergence theorem): to compute a region's total mass / energy / activation magnitude, integrate over the boundary ∂M (surface area, O(n^{(d-1)/d}) cells) instead of the interior M (volume, O(n) cells). Valid when the field is curl-free / exact; reconstruction error is bounded by the harmonic component (compute via Hodge decomposition). Win shrinks fast as dimension d grows — practical only for d ≤ 3 (2D game maps, 3D belief regions, KG embeddings). For d ≥ 8 (HLA state) or d ≥ 64 (style weights) the boundary is larger than the interior, so boundary-only is a loss.
• Conservation-by-construction: identity curl(grad)=0 / div(curl)=0 enforced by DEC operator construction (not a soft penalty) gives mass-conservation invariants for free. Use as a modelless validator: if div(flow) > τ, mass leaked/created = anomaly.
• Pre-compute incidence / Hodge on topology change only: DEC operators (exterior_derivative, codifferential, hodge_decompose) depend only on the cell complex topology, not on the field values. Compute once on map/complex load, cache, invalidate only when topology changes — zero per-tick DEC op cost on a stable map.
• Cache the Hodge spectrum / Betti numbers alongside the operators — they are topology invariants reused across every field query.

SIMD / Auto-vectorization

Auto-vectorization (let LLVM do the work):

• Write chunked loops (4 or 8 elements at a time) to help LLVM auto-vectorize
• Cast usize → u64 slices (same layout on 64-bit) for wider SIMD lanes
• Use u64 equality comparison — compiler maps to _mm256_cmpeq_epi64 on AVX2
• Keep inner loops branch-free (use bool as usize instead of if)
• Verify with release build — SIMD benefits only appear with optimizations enabled

Portable std::simd recipes (when auto-vec isn't enough):

Reach for std::simd only after profiling shows auto-vectorization failing. Patterns below are distilled from mcyoung's vb64 writeup (https://mcyoung.xyz/2023/11/27/simd-base64/). Full skeleton in recipes/swizzle_lookup.rs.

• Branchless range dispatch: replace match on byte ranges with simd_ge/simd_le masks + mask.select(splat_a, splat_b). 1 select beats N branches.
• Perfect-hash lookup via swizzle_dyn: if (byte >> 4) - (byte == c) distinguishes all ranges, build an 8-entry offset table and do 1 shuffle instead of N compares. Index vector must be same width as lookup table.
• Widening cast for sub-byte packing: sextets.cast::<u16>() << Simd::from([2,4,6,8]), then split into lo = v.cast::<u8>() and hi = (v >> 8).cast::<u8>(), OR them after rotating hi by 1 lane. Lets bits cross byte boundaries without per-bit ops.
• Lane-deletion swizzle: when every k-th lane is garbage, use a const swizzle |i| i + i/(k-1) to skip those lanes. Compile-time indices = single vpshufb.
• Slop-buffer commit: out.reserve(final_len + N/4), write full SIMD vectors via ptr.cast::<Simd<u8,N>>().write_unaligned(), only call set_len() after success. On error, never commit — garbage writes vanish.
• Delayed failure: accumulate error |= !ok from each iteration, return Err once after the loop. Errors are rare; don't pay branch cost per chunk.
• Unroll-and-jam with overlapping loads: use chunks_exact(N) for the hot path + Simd::from_slice(). For the remainder, load u64 from p and p+len-8 (overlap by 1 byte), OR them — 2 loads cover any 8–15 byte tail.

Decision rules:

• SIMD wins: lane count ≥ 8, branch-heavy parse/codec, no allocator in loop, input ≥ 16 bytes
• Scalar wins: input < 16 bytes, branch predicts well (profile says so), cold path, or auto-vec already covers it
• swizzle_dyn requires index vector length == lookup table length — pad the table if needed
• Bound all generic SIMD fns with LaneCount<N>: SupportedLaneCount
• Tune N by benchmark; on x86-64 with AVX2, N = 32 (one YMM) is usually optimal

Parallelism / Rayon

• Only parallelize when per-task work exceeds thread-pool overhead (~5μs for rayon)
• Benchmark serial vs parallel at actual workload size before committing
• Rule of thumb: parallelism wins only when per-iteration work > 10μs or count > 1000
• Use rayon::join(|| left(), || right()) for recursive divide-and-conquer — the primitive that powers Rayon; work-stealing ensures threads don't sit idle
• Use .par_sort() and .par_extend() instead of manual .par_iter().collect() — Rayon provides optimized parallel versions of stdlib algorithms
• Use custom ThreadPool to isolate core usage (e.g., reserve CPU for a web server):

let pool = rayon::ThreadPoolBuilder::new().num_threads(4).build().unwrap();
pool.install(|| { /* parallel code here */ });

• Prefer contiguous data (Vec, slices) — Rayon splits chunks efficiently; LinkedList forces traversal before splitting
• Profile before and after with criterion — warm-up cost and orchestration overhead may negate gains

Parallelism: When to Use What

Allocation

• Pre-build lookup tables and cached data in config structs via builder pattern
• Reuse scratch buffers across loop iterations instead of allocating per-iteration
• Pre-allocate output arrays upfront, write in-place instead of collecting per-iteration
• Reorder struct fields to eliminate padding (group by alignment: u64 → u32 → u8)
• Use #[repr(u8)] on field-less enums to guarantee 1-byte size

WASM FFI / Sandboxed Execution

• Batch API: Serialize shared state once, validate all N×M combinations in one FFI call (amortize ~250ns FFI floor across 24 pairs → 5–6× speedup)
• Zero-copy serialization: Use fixed-size stack buffers ([u8; 1024]) instead of Vec::with_capacity() — eliminates allocator overhead in tight loops (~3.6× faster)
• Fuel budgeting: Set WASM fuel proportional to worst-case algorithmic complexity, not average case. BFS on bounded grids with N entities can spike 4–5× above typical. Fuzz-test with max inputs to find the ceiling.
• Lock-free instance pools: Use papaya::HashMap<ThreadId, T> for per-thread WASM stores — lock-free reads on existing entries, uncontended Mutex per thread. Better than a single global Mutex for multi-threaded servers.
• Batch state layout: Omit per-item data from shared state; pass player/entity arrays separately. Grid(169) + bombs(N×4) shared once, then per-entity (id, x, y) array alongside action indices and output results buffer.
• TypedFunc clone: wasmtime::TypedFunc is cheap to clone (handle index). Clone it to release &self borrow before calling mutable Store methods — avoids borrow-checker conflicts with zero cost.

Caching

• Compute once per position/context, not per-sample-per-position (N×M → M calls)
• Pre-compute values that don't change across samples (entropy, base path, threshold)

Bevy / Real-time Loop

Real-time render loops fail in ways the standard CPU profile doesn't catch. The hot CPU path can be 0% algorithmic work — it can be the event loop itself spinning between frames. Patterns below are distilled from the bevy_egui_orchard_demo 100%-CPU saga (commits d6fb415 → 565524f → 01b4687 in riir-game-sdk).