微信扫一扫Rust Performance Best Practices
Expert-level performance optimization guide for Rust. Contains 45+ rules across 9 categories with real benchmarks, failure modes, and profiling workflows.
When to Apply
Reference these guidelines when:
- Investigating slow Rust programs or high latency
- Optimizing build times or binary size
- Reviewing allocation-heavy code
- Debugging lock contention or thread scaling issues
- Setting up release profiles for production
- Working with async runtimes (Tokio, async-std)
When NOT to Apply
Skip these optimizations when:
- Code isn't in a hot path (profile first!)
- Readability would suffer significantly
- You haven't measured a performance problem
- The optimization requires unsafe code you can't verify
- Premature optimization would delay shipping
The Optimization Workflow
CRITICAL: Most Rust code doesn't need optimization. Profile first, optimize second.
┌─────────────────────────────────────────────────────────────┐
│ OPTIMIZATION WORKFLOW │
├─────────────────────────────────────────────────────────────┤
│ │
│ 1. MEASURE FIRST │
│ └── Profile before changing anything │
│ └── Use cargo flamegraph, perf, or heaptrack │
│ └── Identify actual bottlenecks (don't guess!) │
│ │
│ 2. CHECK BUILD SETTINGS │
│ └── Release mode? (10-100x vs debug) │
│ └── LTO enabled? (5-20% improvement) │
│ └── Target CPU? (10-30% for SIMD) │
│ │
│ 3. FIX ALGORITHMIC ISSUES │
│ └── O(n²) → O(n log n) matters more than micro-opts │
│ └── Check data structure choices │
│ └── Avoid unnecessary work │
│ │
│ 4. REDUCE ALLOCATIONS │
│ └── Pre-size collections (with_capacity) │
│ └── Reuse buffers (clear + reuse) │
│ └── Avoid cloning (borrow instead) │
│ │
│ 5. OPTIMIZE HOT LOOPS │
│ └── Iterators over indices │
│ └── Reduce lock scope │
│ └── Batch I/O operations │
│ │
│ 6. MEASURE AGAIN │
│ └── Verify improvement with benchmarks │
│ └── Check for regressions elsewhere │
│ └── Document the optimization │
│ │
└─────────────────────────────────────────────────────────────┘
Quick Profiling Commands
# CPU profiling (Linux)
cargo flamegraph --bin myapp
perf record -g ./target/release/myapp && perf report
# Memory profiling
heaptrack ./target/release/myapp && heaptrack_gui heaptrack.myapp.*.gz
DHAT_LOG_FILE=dhat.out cargo run --release && dh_view.py dhat.out
# Benchmark
cargo bench # All benchmarks
cargo bench hot_function # Specific benchmark
# Check allocations
MALLOC_TRACE=/tmp/mtrace.log ./target/release/myapp
mtrace ./target/release/myapp /tmp/mtrace.log
# Assembly inspection
cargo asm my_crate::hot_function --rust
# syscall count
strace -c ./target/release/myapp 2>&1 | head -20
Common Scenarios → Rules
"My Rust program is slow"
Is it running in debug mode?
├── YES → build-release-profile (10-100x speedup)
└── NO
│
Where does flamegraph show time?
├── malloc/free → alloc-* rules (with_capacity, reuse buffers)
├── Mutex::lock → sync-* rules (RwLock, atomics, shorter scope)
├── read/write syscalls → io-* rules (BufReader/BufWriter)
├── clone/drop → alloc-avoid-clone, use references
└── Your code → iter-* rules, algorithm improvements
"My binary is too large"
1. Enable LTO: build-enable-lto (10-20% smaller)
2. Set opt-level = 'z': build-opt-level (optimizes for size)
3. panic = 'abort': build-panic-abort (removes unwinding code)
4. Strip symbols: strip = true in Cargo.toml
5. Remove debug info: debug = 0
"High memory usage"
1. Pre-size collections: alloc-*-with-capacity
2. Reuse allocations: alloc-reuse-buffers
3. Avoid cloning: alloc-avoid-clone
4. Use slices in APIs: alloc-use-slices-in-apis
5. Consider arena allocators: bumpalo crate
"Lock contention / thread scaling"
1. Profile: lock_api::ReentrantMutex or parking_lot profiling
2. Reduce lock scope: sync-keep-lock-scope-short
3. Read-heavy? → sync-use-rwlock
4. Simple counters? → sync-use-atomics
5. Message passing? → sync-use-channels
6. Thread-local + periodic flush for stats
"Slow file I/O"
1. Wrap in BufReader/BufWriter: io-use-bufreader, io-use-bufwriter
2. Flush before returning: io-flush-bufwriter (data loss prevention!)
3. Reuse line buffer: io-read-line-with-bufread
4. Consider mmap for random access: memmap2 crate
Rule Categories
| Priority | Category | Typical Impact | Prefix |
| -------- | --------------- | ----------------------------------- | --------- |
| 1 | Build Profiles | 10-100x (debug→release) | build- |
| 2 | Benchmarking | Enables measurement | bench- |
| 3 | Allocation | 2-50x for allocation-heavy code | alloc- |
| 4 | Data Structures | 2-10x for hot paths | data- |
| 5 | Iteration | 2-5x for loop-heavy code | iter- |
| 6 | Synchronization | 5-100x for contended code | sync- |
| 7 | I/O | 10-100x for I/O-bound code | io- |
| 8 | Unsafe | 5-30% in tight loops (experts only) | unsafe- |
1. Build Profiles (CRITICAL)
These apply to ALL Rust code. Check these first.
| Rule | Impact | One-liner |
| ----------------------- | ----------- | ------------------------------------ |
| build-release-profile | 10-100x | Always ship release builds |
| build-opt-level | 2-5x | opt-level=3 for speed, 'z' for size |
| build-enable-lto | 5-20% | LTO enables cross-crate optimization |
| build-codegen-units | 5-15% | codegen-units=1 for max optimization |
| build-panic-abort | Binary size | panic='abort' removes unwinding |
| build-target-cpu | 10-30% | target-cpu=native for SIMD |
| build-pgo | 5-20% | Profile-guided optimization |
| build-incremental-off | 5-10% | Disable for release builds |
2. Benchmarking (REQUIRED)
You can't optimize what you don't measure.
| Rule | Purpose |
| --------------------- | ----------------------------------- |
| bench-cargo-bench | Use cargo bench with criterion |
| bench-bench-profile | Bench profile enables optimizations |
| bench-black-box | Prevent dead code elimination |
| bench-avoid-io | I/O variance destroys measurements |
3. Allocation
Every allocation is a syscall. Reduce them.
| Rule | Impact | Pattern |
| ----------------------------- | ----------- | ----------------------------------------------------------------- |
| alloc-vec-with-capacity | 2-10x | Vec::with_capacity(n) not Vec::new() |
| alloc-string-with-capacity | 2-5x | String::with_capacity(n) |
| alloc-hashmap-with-capacity | 2-5x | HashMap::with_capacity(n) |
| alloc-reuse-buffers | 2-10x | .clear() and reuse, don't reallocate (up to 50x in tight loops) |
| alloc-use-slices-in-apis | Flexibility | &[T] not Vec<T> in parameters |
| alloc-avoid-clone | 2-10x | Borrow &T instead of clone() (benefits scale with data size) |
4. Data Structures
The right data structure beats micro-optimization.
| Rule | When |
| -------------------------------- | ----------------------------- |
| data-avoid-linkedlist | Almost always (Vec wins) |
| data-choose-vecdeque-for-queue | FIFO queues |
| data-choose-map-type | HashMap=O(1), BTreeMap=sorted |
| data-use-entry-api | Insert-or-update patterns |
| data-repr-transparent | FFI newtypes |
5. Iteration
Iterators are as fast as loops and safer.
| Rule | Impact | Pattern |
| ------------------------------ | ------------- | --------------------------------------- |
| iter-avoid-collect-then-loop | 2-3x | Chain iterators, don't collect |
| iter-use-lazy-iterators | 2-3x | .filter().map() not intermediate vecs |
| iter-use-any-find | Short-circuit | .any() not .filter().count() > 0 |
| iter-use-retain | In-place | .retain() not .filter().collect() |
| iter-use-binary-search | O(log n) | .binary_search() on sorted data |
6. Synchronization
Locks are expensive. Minimize contention.
| Rule | Impact | When |
| ---------------------------- | -------------- | --------------------------------------------- |
| sync-share-with-arc | Avoids copying | Share large (>64B) data across threads |
| sync-use-rwlock | 2-8x for reads | >80% reads, few writes; consider parking_lot |
| sync-keep-lock-scope-short | 4x | Minimize code under lock |
| sync-use-channels | 3-4x | Message passing vs shared state |
| sync-use-atomics | 20x | Simple counters, flags |
| sync-use-parking-lot | 1.5-5x | Prefer parking_lot over std sync primitives |
7. I/O
Every syscall costs. Buffer them.
| Rule | Impact | Pattern |
| --------------------------- | -------- | ------------------------------------ |
| io-use-bufreader | 50x | Wrap File in BufReader |
| io-use-bufwriter | 18x | Wrap File in BufWriter |
| io-flush-bufwriter | CRITICAL | Must flush or lose data! |
| io-read-line-with-bufread | 53x | Reuse String buffer with read_line |
8. Async/Await (HIGH)
Critical for Tokio and async-std applications.
| Rule | Impact | Pattern |
| ------------------------- | ------------- | -------------------------------------------- |
| async-spawn-blocking | Prevents hang | Use spawn_blocking for CPU-bound work |
| async-cooperative | Latency | Yield periodically in long computations |
| async-mutex-choice | Correctness | tokio::sync::Mutex across .await points |
| async-avoid-blocking-io | Throughput | Use async I/O, not std::fs in async contexts |
| async-bounded-channels | Backpressure | Prefer bounded channels for flow control |
Key insight: The async runtime is cooperative. Blocking the executor thread starves all other tasks.
// BAD: Blocks the async runtime
async fn process(data: &[u8]) -> Result<Hash> {
let hash = expensive_hash(data); // CPU-bound, blocks executor!
Ok(hash)
}
// GOOD: Offload to blocking thread pool
async fn process(data: Vec<u8>) -> Result<Hash> {
tokio::task::spawn_blocking(move || expensive_hash(&data)).await?
}
9. Unsafe (Expert Only)
Only after profiling proves these matter.
| Rule | Impact | Risk |
| ------------------------- | ------------- | ------------------------- |
| unsafe-get-unchecked | 5-30% | UB if bounds wrong |
| unsafe-use-maybeuninit | 20-100x alloc | UB if read before write |
| unsafe-avoid-transmute | Correctness | Prefer safe alternatives |
| unsafe-repr-transparent | Zero-cost | Required for FFI newtypes |
Decision Trees
When to use with_capacity?
Do you know the size?
├── YES, exact → with_capacity(exact)
├── YES, approximate → with_capacity(estimate)
└── NO
│
Will it grow frequently?
├── YES → Start bigger or use reserve()
└── NO → Vec::new() is fine
Mutex vs RwLock vs Atomics?
Is it a simple counter/flag?
├── YES → Atomics (20x faster)
└── NO
│
What's the read/write ratio?
├── Mostly reads (>90%) → RwLock
├── Mostly writes → Mutex
└── Mixed → Mutex (simpler)
Consider: parking_lot > std for all of these
When is unsafe get_unchecked worth it?
Did you profile and find bounds checks are the bottleneck?
├── NO → Don't use it
└── YES
│
Did you check if LLVM already removed the bounds check?
├── NO → Check assembly first (cargo asm)
└── YES, still there
│
Can you use iterators instead?
├── YES → Use iterators (same speed, safe)
└── NO → get_unchecked with documented invariants
Reading Rules
Each rule file in rules/ contains:
- Quantified impact with real benchmark numbers
- Visual explanations of how the optimization works
- Incorrect examples showing common mistakes
- Correct examples with best practices
- When NOT to apply - trade-offs and edge cases
- Common mistakes to avoid
- Profiling commands to identify the issue
- References to official docs
Full Compiled Document
For all rules in a single file: AGENTS.md