ios-performance

name	ios-performance
description	Diagnose and fix iOS app performance — slow launch, jank, hangs, memory leaks, battery drain, slow Xcode builds, large app size. Covers Instruments/xctrace, Memory Graph Debugger, MetricKit, XCTest perf gates, Swift 6.2 perf (ARC, COW, InlineArray, Span), SwiftUI render perf (@Observable, LazyVStack), ProMotion frame pacing, app-launch phases, build settings, binary-size reduction. Use when an app feels slow, freezes, hangs, leaks memory, drains battery, drops frames or is stuck at 60 Hz, launches or compiles slowly, or downloads too large. Trigger phrases: "performance", "memory leak", "retain cycle", "Time Profiler", "FPS", "ProMotion", "launch time", "app size", "build time", "optimize".
license	MIT

iOS Performance

Measure first, optimize second. Guessing where a bottleneck is wastes more time than profiling it. Every section below tells you which tool produces the evidence, then how to act on that evidence.

Authored against iOS 26 / Swift 6.2 / Xcode 26. Performance numbers quoted here are starting expectations — always re-measure on your oldest supported device with a Release build.

What this skill covers (and where to go)

Performance is six distinct problems. Route by symptom:

Symptom	Go to
App feels slow / laggy during use	Profiling workflow → Time Profiler
UI freezes, unresponsive to taps (>1 s)	Hangs
Memory grows over time / crashes after prolonged use	Memory & leaks
Slow cold launch / slow first frame	App launch
Battery drains / device gets hot	Energy
Slow scrolling, dropped frames in SwiftUI	SwiftUI render performance
Dropped frames in a Metal/Core Animation render loop, stuck at 60 Hz on ProMotion, animation jitter	SwiftUI render performance → references/display-promotion.md
Hot path in Swift code (Time Profiler points at your code)	Swift performance
Slow Xcode builds / long compile times	Build performance
App download too large	App-size reduction

Two golden rules apply to all of them:

1. Profile on a real device with a Release build. The Simulator's CPU, memory, and energy characteristics are not your users'. Debug builds carry optimization-off overhead that distorts every number.
2. Reproduce the specific slow operation, not the whole app. "Scrolling is slow" → profile only scrolling. Isolate before you measure.

Related skills in this collection: ios-debugging (LLDB, crash symbolication, Memory Graph deep-dives), swift-concurrency (correctness-focused actor/async patterns), swiftui-ui (general SwiftUI), ios-testing (XCTest setup).

---

1. Profiling workflow (the evidence step)

Before opening Instruments, narrow what you're investigating, then pick the template. See references/instruments-tools.md for the per-instrument deep dives (Time Profiler call-tree reading, Allocations, Core Data, System Trace, OSSignposter, the CLI tools).

App performance problem?
├─ Feels slow / laggy (UI stalls, scroll stutters)  → Time Profiler   (CPU)
├─ Memory grows over time                            → Allocations     (object growth)
├─ Specific memory leak / retain cycle               → Memory Graph Debugger
├─ UI frozen, unresponsive >1 s                      → Time Profiler + System Trace
├─ Slow data loading (Core Data / SQLite)            → Core Data instrument / EXPLAIN
└─ Battery drains, device hot                         → Energy / Power Profiler

Time Profiler — the #1 mistake

Time Profiler shows CPU time per function. The mistake that wastes hours: blaming the function with high Total Time.

• Self Time = time spent in that function's own code.
• Total Time = Self Time + everything it calls.

A function with 80% Total Time but 5% Self Time is calling slow code — drill down to find the leaf with high Self Time. Always set Invert Call Tree, Separate by Thread, and Hide System Libraries so the heaviest leaf functions surface first and you can isolate main-thread work.

Quick patterns — full code in instruments-tools.md:

• CLI quick checks before a full session: xcrun sample, xcrun leaks, xcrun xctrace record.
• OSSignposter measures specific operations you define (Points of Interest instrument; bridges to automated regression tests).
• Regression-proof every fix — three stages: OSSignposter (dev) → XCTest measure with a baseline (CI — a baseline-less measure {} test always passes, it's theater) → MetricKit (production; references/metrickit.md). XCTHitchMetric and XCTOSSignpostMetric cover hitches and your own signposts.

---

2. Memory & leaks

90% of memory leaks follow 3 patterns: un-invalidated timers, un-removed observers, and closures captured strongly in collections. Diagnose systematically — never guess. Full pattern catalogue (6 leak patterns with fixes, PhotoKit/AVFoundation request cancellation, the CLI memory toolkit) is in references/memory-leaks.md.

Leak vs normal growth

Climbs-then-plateaus (or drops under pressure) = cache, normal; linear unbounded growth on a repeated operation = leak. Verify with Xcode → Debug → Simulate Memory Warning — full tell-tales in memory-leaks.md.

Mandatory first steps (before reading any code)

1. Memory Graph Debugger (Debug → Memory Graph, or toolbar icon): look for purple/red ⚠ circles → click → read the retain-cycle chain. Fastest path.
2. deinit logging on suspect classes — the cheapest leak detector:

   final class DetailViewModel { deinit { print("✅ DetailViewModel deallocated") } }
   

   Navigate in, navigate away. No "✅"? It's retained somewhere.
3. Instruments → Leaks / Allocations: repeat the action 10×. Flat line = not a leak (stop). Steady climb = leak (continue).

Core rules — full code + rationale in memory-leaks.md:

• Timers (the #1 leak): [weak self] alone does not fix a timer leak — the RunLoop retains a scheduled Timer; you must invalidate() it (or use Combine's Timer.publish().autoconnect(), whose cancellable auto-cleans).
• weak vs unowned: weak by default in escaping closures/delegates; unowned (~2× faster) only when lifetime is guaranteed. Non-escaping closures (map/filter/forEach…) need neither — [weak self] there is noise.
• Jetsam is not a crash: memory growing while in use = real leak; killed while in the background = Jetsam — reduce background footprint (<50 MB) and restore state so the user never notices.

---

3. Hangs (main thread blocked)

A hang is the main runloop failing to process events for >1 s — the user taps and nothing happens. Distinct from a hitch (1–3 dropped frames during animation) and general lag (sluggish but responsive). Every hang has exactly one of two causes:

1. Main thread BUSY — doing work it shouldn't (proactive computation, unfiltered notification handling, a blocking API where an async one exists). → Time Profiler shows your code with high Self Time on the main thread.
2. Main thread BLOCKED — waiting on something (sync file I/O, sync network, a lock held by a background thread, dispatch_sync/semaphore). → System Trace shows the main thread in a red (blocked) state.

Tool selection: reproducible → Time Profiler first (BUSY) then System Trace if CPU is low but the thread is stalled (BLOCKED). Field-only → Xcode Organizer → Hangs, or adopt MetricKit (MXHangDiagnostic).

The most common fixes (full code in hangs.md): sync file I/O off-main via Task.detached / @concurrent (a plain Task {} inherits @MainActor and stays on main); cache expensive formatters; never semaphore-block to fake sync; replace main-thread lock contention with an actor; filter notification observers by object:; never DispatchQueue.main.sync from a background thread.

Also in hangs.md: watchdog terminations (the watchdog kills apps that hang during launch ~20 s / background ~5 s / foreground ~10 s — EXC_CRASH (SIGKILL), 0xDEAD10CC = held a file/SQLite lock while suspending; disabled in Simulator and under the debugger), the full hang decision tree, and the pre-ship hang prevention checklist.

---

4. App launch

Apple's target: first frame within ~400 ms, interactive by the time the launch animation finishes. iOS runs a watchdog that kills apps overrunning the budget. Launch has three phases — profile to learn which one dominates before changing anything. Full phase model, measurement hygiene, push-notification launch path, and the per-phase fix lists: references/app-launch.md.

Quick reference in app-launch.md: the launch vocabulary (cold / warm / hot — a resume is NOT a launch), the three launch phases (pre-main → first frame → interactive), DYLD_PRINT_STATISTICS=1 deadline triage, the XCTApplicationLaunchMetric regression test, and measurement hygiene (Release build, oldest device; profiling ≠ measuring).

---

5. Energy & battery

Battery drain spans subsystems — diagnose the actual cause, don't assume it's the network. Profile with the Energy Log / Power Profiler template; sustained red/orange usage is the problem (brief peaks are fine). The 8 anti-patterns and the WWDC-grade efficient-API reference (Timer/network/location coalescing, BGContinuedProcessingTask, MetricKit energy metrics) are in references/energy.md.

The recurring offenders (timers/polling, full-accuracy location, off-screen animations, chatty network, non-compliant background work) and the per-symptom diagnosis paths ("top of Battery Settings", "device gets hot", "background drain") are in energy.md.

---

6. SwiftUI render performance

Slow scrolling and dropped frames in SwiftUI almost always trace to too much body re-evaluation. The full reference (view identity, EquatableView, the LazyVStack/List decision matrix, image downsampling, .task cancellation, Self._printChanges(), the SwiftUI Instrument) is in references/swiftui-perf.md.

The four levers — full code and tables in swiftui-perf.md: @Observable over ObservableObject (per-property tracking — the single biggest SwiftUI perf win), extract subviews to localize invalidation, lazy containers for long lists (VStack <50 / LazyVStack / List), and stable ForEach identity (never an array index). Diagnose with Self._printChanges() + the Xcode 16+ SwiftUI Instrument; downsample images at decode time (a 4000×3000 photo decoded full-size costs ~48 MB even at 80×80 pt). Core Image / camera pipelines: coreimage-camera-perf.md; Metal render loop: metal-render-loop.md.

Display refresh, ProMotion & Metal frame timing

Stuck at 60 Hz on a ProMotion panel, animation jitter despite good average FPS, or a Metal/Core Animation loop missing its GPU deadline are frame-budget and frame-pacing problems, not SwiftUI-body problems — ProMotion enablement, CADisplayLink/CAMetalDisplayLink, commit-vs-render hitches, frame pacing, and the thermal/low-power caps are in display-promotion.md.

---

7. Swift language performance

When Time Profiler points at your Swift code in a hot path, the WWDC "four principles" tell you which lever to pull: function-call overhead, memory allocation, memory layout, value copying. The complete treatment (noncopyable types, COW internals & defensive copies, ARC closure-capture costs, generic specialization & existential containers, @inlinable, collection performance, memory layout/padding, exclusivity checks, typed throws, full Span API) is in references/swift-performance.md. The highest-leverage points:

Its "Highest-leverage points" section condenses them: value-vs-reference & COW defensive copies, ARC/closure costs (non-escaping = zero ARC; unowned ~2× faster than weak), existential vs specialized generics (any P ~10× slower than some P), the Swift 6.2 tools (InlineArray, Span, @concurrent), and the anti-pattern table.

When source-level reasoning can't explain a Time-Profiler hotspot, inspect optimized SIL (swiftc -O -emit-sil) — see references/sil-inspection.md for instruction-search targets and false-conclusion guardrails. For C++-interop hot paths, custom sorted collections, and the Swift 6.2 strict-memory-safety audit gate, see references/swift-performance.md (Parts 12–13) and references/custom-collections.md.

---

8. Build-time performance

Slow Xcode builds are a productivity tax. Two fronts: build settings (often misconfigured after migrating across Xcode versions) and source-level compile-time hotspots (Swift type-checker blowups). Full settings reference, source-fix before/after patterns, compile-time diagnostic flags, and SPM graph analysis are in references/build-performance.md.

Its "Quick reference" section carries the essentials: measure the median of repeated builds (standard-clean / cached-clean / incremental), the highest-impact settings table (Debug singlefile+-Onone, Release wholemodule, compilation caching on), the compile-time hotspot flags (-warn-long-function-bodies=100) with the standard source fixes, and SPM-over-CocoaPods guidance (CocoaPods is deprecated).

---

9. App-size / binary-size reduction

Large download size loses installs (and >200 MB requires Wi-Fi to download). Reduce it tier by tier, re-measuring a clean Release archive after each pass and reverting any pass that gains less than your threshold or fails a gate. The full tiered catalogue (P1–P20 with per-technique risk/quality/perf trade-offs), the baseline-capture procedure, the validation gates, and the JSON report schema are in references/binary-size.md.

The guardrails (never -Ounchecked or -enforce-exclusivity=unchecked in production, never drop dSYMs, one risk tier at a time), the Tier 1→3 summary table, and the highest-ROI / highest-risk callouts are in binary-size.md alongside the full catalogue.

---

Performance targets & deadline pressure

The concrete-thresholds table (cold launch <400 ms to first frame, 16.67 ms / 8.33 ms frame budgets, memory/CPU/app-size limits) and the cross-cutting "make it faster, we ship tomorrow" playbook are at the end of instruments-tools.md. The math always favors profiling first: ~15–20 min to profile the critical path vs 2+ hours wasted optimizing the wrong function.

---

Reference index

File	Contents
references/instruments-tools.md	Time Profiler / Allocations / Core Data / System Trace deep dives, OSSignposter, CLI tools, LLDB-at-the-freeze-point
references/memory-leaks.md	6 leak patterns + fixes, PhotoKit/AVFoundation cancellation, CLI memory toolkit, intermittent-leak field diagnostics
references/hangs.md	Full hang decision tree, 8 patterns, Organizer/MetricKit hang reports, watchdog detail
references/app-launch.md	Launch phase model, hygiene, per-phase fixes, push-notification launch, commands
references/energy.md	8 energy anti-patterns, efficient-API reference, symptom routing, MetricKit energy metrics
references/swiftui-perf.md	View identity, EquatableView, list decision, image downsampling, .task, Self._printChanges()
references/display-promotion.md	ProMotion 120 Hz enablement, CADisplayLink/CAMetalDisplayLink, frame budgets, commit-vs-render hitches, frame pacing, GPU frame-time measurement, thermal/low-power caps, adaptive frame rate
references/swift-performance.md	Noncopyable, COW, ARC, generics/existentials (incl. protocol-extension static dispatch, any P usability), inlining, collections, memory layout, exclusivity, typed throws, full Span/InlineArray, C++ interop deep-copy, strict memory safety
references/sil-inspection.md	Optimized SIL as evidence — generation forms, grouped instruction-search targets, false-conclusion guardrails, before/after workflow
references/custom-collections.md	Implementing a sorted collection — structure selection, L1-tuned B-Tree order, unsafe-buffer nodes, COW traps
references/build-performance.md	Build-settings reference, zero-change/cached-clean methodology, critical-path triage, Debug post-processing & sanitizers, ccache, linker, Xcode IDE defaults, source fixes, SPM graph + cascades
references/binary-size.md	P1–P20 technique catalogue with trade-offs, baseline capture, validation gates, report schema
references/metal-render-loop.md	CPU↔GPU in-flight semaphore, Swift↔Metal uniform layout, setFragmentBytes, full-screen-triangle, ACES/PBR, MetalFX upscaling
references/coreimage-camera-perf.md	Long-lived CIContext, debounce live-edit re-encode, CGImageSource metadata reads, AVCaptureSession begin/commit
references/metrickit.md	MetricKit field-metric setup, payload parsing, cross-payload aggregation, ASC server-side diagnostics