swift-performance-engineering

name	swift-performance-engineering
description	Use when the task claims a latency, throughput, allocation, memory, startup, compilation, or energy improvement, or when optimizing hot Swift code. Do not make performance changes from intuition alone.

Swift performance engineering

Treat performance as a measured hypothesis with a reproducible baseline. Preserve semantics and report the measurement boundary.

Procedure

1. Define the workload, input distribution, correctness oracle, metric, variance budget, and target. Separate build time, startup, steady-state, tail latency, memory, and energy.
2. Establish a warmed baseline using identical inputs, compiler mode, hardware, and process conditions. Record index/setup cost separately from query or steady-state cost.
3. Profile before editing. Identify algorithmic complexity, allocations, copies/COW, ARC, dynamic dispatch, synchronization, I/O, cache locality, and compiler effects.
4. Make the smallest change that addresses the measured bottleneck. Consider concrete types/specialization, ownership, Span/contiguous views, batching, and data layout only where the evidence supports them.
5. Re-run correctness and benchmark suites. Use multiple iterations and report median plus spread; check for warm-up and dead-code elimination.
6. Compare the full workload and the isolated hot path. Revert changes that move cost to an unreported setup or make correctness/maintainability worse without a material gain.

Read references/benchmark-guide.md for the measurement protocol.

Guardrails

• Do not call a microbenchmark a product-level win without an end-to-end measurement.
• Do not use consuming, unsafe, @inline, @inlinable, or type erasure as a generic performance charm.
• Do not compare debug and release results as if they were equivalent.
• Do not optimize an unavailable hardware path or claim GPU/ANE behavior from a host-only test.

Completion contract

Report baseline, change, workload, configuration, measurements, variance, correctness proof, and costs excluded from the headline number.