repositories / dotfiles

dotfiles

bugabingas dorkfiles

owned by bugabinga

opencode/skills/performance-optimization/performance-rust.md

Raw

Rust Performance Optimization

Build Configuration

The fastest wins come from build config changes, not code changes.

Release Build

cargo build --release

10-100x faster than dev builds. Dev builds are unoptimized.

Codegen Units

[profile.release]
codegen-units = 1

Default is 16. Setting to 1 improves runtime speed and reduces binary size at the cost of longer compile times. Enables more cross-function optimizations.

Link-Time Optimization (LTO)

[profile.release]
lto = "thin"    # Lightweight, good results
lto = "fat"     # Aggressive, best results, slower builds

10-20% runtime speedup, smaller binaries. Fat LTO can be significantly slower to compile.

Target CPU

RUSTFLAGS="-C target-cpu=native" cargo build --release

Generates CPU-specific instructions (AVX, etc.). Large speedup if your binaries run on known hardware. Don't use for distributed binaries.

Profile-Guided Optimization (PGO)

# 1. Instrument
cargo pgo instrument
# 2. Run with representative data
./target/release/myapp
# 3. Optimize
cargo pgo optimize

10%+ speedup. Use cargo-pgo tool. Requires representative training data.

Binary Size

[profile.release]
opt-level = "z"      # Minimize size (vs "s" or "3")
panic = "abort"     # No unwinding
strip = "symbols"   # Remove debug symbols

Compile Times

[profile.dev]
debug = false        # Disable debug info for 20-40% faster dev builds

Use faster linkers:

RUSTFLAGS="-C link-arg=-fuse-ld=lld" cargo build  # lld (default on Linux 1.90+)
RUSTFLAGS="-C link-arg=-fuse-ld=mold" cargo build  # mold (faster)

Memory Types

Static Memory

static COUNTER: i64 = 0;
static mut COUNTER_MUT: i64 = 0;  // Unsafe: data races

Stack Memory

fn foo() {
    let x = [0u8; 1024];  // Stack allocated
}

Heap Memory

let v = vec![1, 2, 3];
let s = String::from("hello");
let b = Box::new(42);

Allocator Selection

Benchmark Results

Allocator Performance
System (malloc) baseline
jemalloc ~3x faster
mimalloc ~10x faster
Bump Fastest for short-lived allocs

Practical Advice

// Bump allocator (bumpalo crate)
use bumpalo::Bump;

fn process() {
    let arena = Bump::new();
    let data = arena.alloc(vec![1, 2, 3]);
    // Single deallocation when arena drops
}

Heap Allocations

Each allocation involves: global lock, data structure manipulation, possible syscall.

Profiling Allocations

Use DHAT (Valgrind) to find hot allocation sites:

valgrind --tool=dhat ./target/release/myapp

DHAT shows: allocation frequency, sizes, lifetimes, access patterns.

Reducing Allocations

Vec Growth

Default Vec growth: 0 → 4 → 8 → 16 → 32 → ...

// BAD: Multiple reallocations
let mut v = Vec::new();
for item in items { v.push(item); }

// GOOD: Pre-allocate
let mut v = Vec::with_capacity(items.len());
for item in items { v.push(item); }

Short Vecs

Use SmallVec for short vectors:

use smallvec::SmallVec;

let v: SmallVec<[i32; 16]> = SmallVec::new();
v.push(1);  // Stack until > 16 elements

Strings

// Use with_capacity
let mut s = String::with_capacity(1024);

// smartstring: no alloc for <24 bytes
use smartstring::SmartString;
let s: SmartString = "short".into();

Cow: Clone-on-Write

Avoid allocations for mixed borrowed/owned data:

use std::borrow::Cow;

fn process(s: &str) -> Cow<'static, str> {
    if s.contains("error") {
        Cow::Owned(format!("ERROR: {}", s))
    } else {
        Cow::Borrowed(s)
    }
}

Avoid Unnecessary Clones

Profile first, then check for hot clone calls:

// clone_from reuses allocation
let mut v1: Vec<u32> = Vec::with_capacity(99);
let v2 = vec![1, 2, 3];
v1.clone_from(&v2);  // Reuses v1's allocation

Inlining

Inline Attributes

#[inline]           // Suggest inlining
#[inline(always)]    // Force inlining
#[inline(never)]    // Prevent inlining
#[cold]             // Rarely called - move out of hot path

Split Hot/Cold

For large functions with one hot call site:

#[inline(always)]
fn hot_impl() { /* hot code */ }

#[inline(never)]
fn cold_impl() { /* cold code */ }

fn my_func(hot: bool) {
    if hot { hot_impl(); } else { cold_impl(); }
}

Iterators

Collect/Extend

Avoid collect if you're just iterating again:

// Return iterator instead of Vec
fn items() -> impl Iterator<Item = i32> { ... }

// Use extend instead of collect + append
target.extend(source);

Chain

chain can be slower - avoid for hot iterators.

Chunks

Use chunks_exact instead of chunks when size divides evenly:

// Faster
for chunk in data.chunks_exact(CHUNK_SIZE) {
    // ...
}

Copied

For small types (integers), use copied():

// Better: gives value instead of reference
for &x in v.iter().copied() { ... }

Type Sizes

Types >128 bytes are copied with memcpy. Shrinking types reduces memory traffic and cache pressure.

Measuring Sizes

RUSTFLAGS=-Zprint-type-sizes cargo +nightly build --release

Shows: size, alignment, field ordering, padding.

Shrinking Types

Smaller Enums

Box large variants:

// Before
enum A { X, Y(i32, [u8; 100]) }

// After
enum A { X, Y(Box<(i32, [u8; 100])>) }

Smaller Integers

Use u32/u16 instead of usize where possible:

struct Index(u32);  // Instead of usize

Boxed Slices

Convert Vec to boxed slice when not growing:

let bs: Box<[u32]> = vec![1, 2, 3].into_boxed_slice();
// 3 words -> 2 words

ThinVec

ThinVec<T> is one word instead of three:

use thin_vec::ThinVec;
let v: ThinVec<i32> = ThinVec::new();

SIMD and Vectorization

Auto-Vectorization

Compilers vectorize when:

  1. Code processes chunks identically
  2. No branching inside chunks

Manual Vectorization

// BAD: Byte-by-byte (slow)
for (x, y) in xs.iter().zip(ys) {
    if x != y { break; }
}

// GOOD: Chunk-based (vectorizes)
for chunk in xs.chunks_exact(16).zip(ys.chunks_exact(16)) {
    all_equal &= (chunk.0 == chunk.1);  // No early break
}

Key rules:


Practical Checklist


Quick Reference

Pattern Use
Fast release build codegen-units = 1, lto = fat
Hot small allocations bump allocator
Many similar allocs mimalloc
Small container SmallVec
Known max size Vec::with_capacity()
SIMD Chunk-based, no branching
Type >128B Box fields, use smaller ints
Markdown source
# Rust Performance Optimization

## Build Configuration

The fastest wins come from build config changes, not code changes.

### Release Build

```bash
cargo build --release
```

10-100x faster than dev builds. Dev builds are unoptimized.

### Codegen Units

```toml
[profile.release]
codegen-units = 1
```

Default is 16. Setting to 1 improves runtime speed and reduces binary size at
the cost of longer compile times. Enables more cross-function optimizations.

### Link-Time Optimization (LTO)

```toml
[profile.release]
lto = "thin"    # Lightweight, good results
lto = "fat"     # Aggressive, best results, slower builds
```

10-20% runtime speedup, smaller binaries. Fat LTO can be significantly slower to
compile.

### Target CPU

```bash
RUSTFLAGS="-C target-cpu=native" cargo build --release
```

Generates CPU-specific instructions (AVX, etc.). Large speedup if your binaries
run on known hardware. Don't use for distributed binaries.

### Profile-Guided Optimization (PGO)

```bash
# 1. Instrument
cargo pgo instrument
# 2. Run with representative data
./target/release/myapp
# 3. Optimize
cargo pgo optimize
```

10%+ speedup. Use `cargo-pgo` tool. Requires representative training data.

### Binary Size

```toml
[profile.release]
opt-level = "z"      # Minimize size (vs "s" or "3")
panic = "abort"     # No unwinding
strip = "symbols"   # Remove debug symbols
```

### Compile Times

```toml
[profile.dev]
debug = false        # Disable debug info for 20-40% faster dev builds
```

Use faster linkers:

```bash
RUSTFLAGS="-C link-arg=-fuse-ld=lld" cargo build  # lld (default on Linux 1.90+)
RUSTFLAGS="-C link-arg=-fuse-ld=mold" cargo build  # mold (faster)
```

---

## Memory Types

### Static Memory

```rust
static COUNTER: i64 = 0;
static mut COUNTER_MUT: i64 = 0;  // Unsafe: data races
```

- Allocated at compile time
- No runtime allocation cost
- Limited flexibility, cannot grow

### Stack Memory

```rust
fn foo() {
    let x = [0u8; 1024];  // Stack allocated
}
```

- Fast: just bump the stack pointer
- Limited size (typically 8MB)
- Good cache locality
- Must know size at compile time

### Heap Memory

```rust
let v = vec![1, 2, 3];
let s = String::from("hello");
let b = Box::new(42);
```

- Flexible size at runtime
- Allocation cost: bookkeeping, syscalls
- Pointer stored on stack

---

## Allocator Selection

### Benchmark Results

| Allocator       | Performance                    |
| --------------- | ------------------------------ |
| System (malloc) | baseline                       |
| jemalloc        | ~3x faster                     |
| mimalloc        | ~10x faster                    |
| Bump            | Fastest for short-lived allocs |

### Practical Advice

- **mimalloc**: Best default for performance
- **jemalloc**: Good for long-running services
- **bump allocator**: Game frames, batch processing, request handling

```rust
// Bump allocator (bumpalo crate)
use bumpalo::Bump;

fn process() {
    let arena = Bump::new();
    let data = arena.alloc(vec![1, 2, 3]);
    // Single deallocation when arena drops
}
```

---

## Heap Allocations

Each allocation involves: global lock, data structure manipulation, possible
syscall.

### Profiling Allocations

Use DHAT (Valgrind) to find hot allocation sites:

```bash
valgrind --tool=dhat ./target/release/myapp
```

DHAT shows: allocation frequency, sizes, lifetimes, access patterns.

### Reducing Allocations

#### Vec Growth

Default Vec growth: 0 → 4 → 8 → 16 → 32 → ...

```rust
// BAD: Multiple reallocations
let mut v = Vec::new();
for item in items { v.push(item); }

// GOOD: Pre-allocate
let mut v = Vec::with_capacity(items.len());
for item in items { v.push(item); }
```

#### Short Vecs

Use `SmallVec` for short vectors:

```rust
use smallvec::SmallVec;

let v: SmallVec<[i32; 16]> = SmallVec::new();
v.push(1);  // Stack until > 16 elements
```

#### Strings

```rust
// Use with_capacity
let mut s = String::with_capacity(1024);

// smartstring: no alloc for <24 bytes
use smartstring::SmartString;
let s: SmartString = "short".into();
```

#### Cow: Clone-on-Write

Avoid allocations for mixed borrowed/owned data:

```rust
use std::borrow::Cow;

fn process(s: &str) -> Cow<'static, str> {
    if s.contains("error") {
        Cow::Owned(format!("ERROR: {}", s))
    } else {
        Cow::Borrowed(s)
    }
}
```

#### Avoid Unnecessary Clones

Profile first, then check for hot clone calls:

```rust
// clone_from reuses allocation
let mut v1: Vec<u32> = Vec::with_capacity(99);
let v2 = vec![1, 2, 3];
v1.clone_from(&v2);  // Reuses v1's allocation
```

---

## Inlining

### Inline Attributes

```rust
#[inline]           // Suggest inlining
#[inline(always)]    // Force inlining
#[inline(never)]    // Prevent inlining
#[cold]             // Rarely called - move out of hot path
```

- `#[inline]`: Small functions, hot call sites
- `#[inline(never)]`: Large functions with few call sites
- `#[cold]`: Error handling, rare paths

### Split Hot/Cold

For large functions with one hot call site:

```rust
#[inline(always)]
fn hot_impl() { /* hot code */ }

#[inline(never)]
fn cold_impl() { /* cold code */ }

fn my_func(hot: bool) {
    if hot { hot_impl(); } else { cold_impl(); }
}
```

---

## Iterators

### Collect/Extend

Avoid `collect` if you're just iterating again:

```rust
// Return iterator instead of Vec
fn items() -> impl Iterator<Item = i32> { ... }

// Use extend instead of collect + append
target.extend(source);
```

### Chain

`chain` can be slower - avoid for hot iterators.

### Chunks

Use `chunks_exact` instead of `chunks` when size divides evenly:

```rust
// Faster
for chunk in data.chunks_exact(CHUNK_SIZE) {
    // ...
}
```

### Copied

For small types (integers), use `copied()`:

```rust
// Better: gives value instead of reference
for &x in v.iter().copied() { ... }
```

---

## Type Sizes

Types >128 bytes are copied with `memcpy`. Shrinking types reduces memory
traffic and cache pressure.

### Measuring Sizes

```bash
RUSTFLAGS=-Zprint-type-sizes cargo +nightly build --release
```

Shows: size, alignment, field ordering, padding.

### Shrinking Types

#### Smaller Enums

Box large variants:

```rust
// Before
enum A { X, Y(i32, [u8; 100]) }

// After
enum A { X, Y(Box<(i32, [u8; 100])>) }
```

#### Smaller Integers

Use u32/u16 instead of usize where possible:

```rust
struct Index(u32);  // Instead of usize
```

#### Boxed Slices

Convert Vec to boxed slice when not growing:

```rust
let bs: Box<[u32]> = vec![1, 2, 3].into_boxed_slice();
// 3 words -> 2 words
```

#### ThinVec

`ThinVec<T>` is one word instead of three:

```rust
use thin_vec::ThinVec;
let v: ThinVec<i32> = ThinVec::new();
```

---

## SIMD and Vectorization

### Auto-Vectorization

Compilers vectorize when:

1. Code processes chunks identically
2. No branching inside chunks

### Manual Vectorization

```rust
// BAD: Byte-by-byte (slow)
for (x, y) in xs.iter().zip(ys) {
    if x != y { break; }
}

// GOOD: Chunk-based (vectorizes)
for chunk in xs.chunks_exact(16).zip(ys.chunks_exact(16)) {
    all_equal &= (chunk.0 == chunk.1);  // No early break
}
```

Key rules:

- Process fixed-size chunks
- Avoid branching inside chunks
- Use `&` not `&&` for booleans

---

## Practical Checklist

- [ ] Use `cargo build --release` for performance
- [ ] Set `codegen-units = 1` and `lto = "thin"` in release
- [ ] Use `mimalloc` allocator
- [ ] Use `SmallVec` for small vectors
- [ ] Pre-allocate with `Vec::with_capacity()`
- [ ] Use `String::with_capacity()` for concatenation
- [ ] Profile with DHAT for allocation hotspots
- [ ] Use `#[inline]` on small hot functions
- [ ] Avoid trait objects in hot paths
- [ ] Use `chunks_exact` instead of `chunks`
- [ ] Shrink hot types to <128 bytes

---

## Quick Reference

| Pattern               | Use                              |
| --------------------- | -------------------------------- |
| Fast release build    | `codegen-units = 1`, `lto = fat` |
| Hot small allocations | bump allocator                   |
| Many similar allocs   | mimalloc                         |
| Small container       | SmallVec                         |
| Known max size        | Vec::with_capacity()             |
| SIMD                  | Chunk-based, no branching        |
| Type >128B            | Box fields, use smaller ints     |