ios-performance

name

ios-performance

description

iOS performance optimization expert skill covering memory management (ARC, retain cycles, weak/unowned, value vs reference types, copy-on-write), SwiftUI performance (view identity, @Observable vs ObservableObject, lazy containers, EquatableView, image caching), Instruments profiling (Time Profiler, Allocations, Leaks, Energy Log, Core Animation, SwiftUI instrument), app launch optimization, network performance, battery optimization, build performance, and common anti-patterns. Use this skill whenever the user optimizes iOS app performance, investigates memory leaks, profiles with Instruments, improves launch time, or fixes frame drops. Triggers on: performance, memory leak, retain cycle, ARC, weak self, profiling, Instruments, Time Profiler, Allocations, frame rate, FPS, launch time, battery, energy, optimization, slow, lag, freeze, hang, jank, memory pressure, CPU usage, build time, compile time, app size, or any iOS performance question.

iOS Performance Optimization Skill

Core Rules

1. Use [weak self] in escaping closures by default — use [unowned self] only when the closure's lifetime is strictly shorter than the captured object (e.g., parent owns child, child's closure references parent).
2. Non-escaping closures do NOT need [weak self] — map, filter, forEach, reduce, compactMap, sorted(by:) are non-escaping. The closure executes synchronously and releases captures immediately.
3. Delegates must be weak var — the delegate protocol must conform to AnyObject (or be marked @objc). Strong delegates create retain cycles between owner and delegate.
4. Use @Observable over ObservableObject (iOS 17+) — @Observable tracks property access per-view, so only views reading a changed property re-evaluate. ObservableObject with @Published invalidates ALL observing views on ANY published property change.
5. Break SwiftUI views into small subviews — each subview localizes its state dependency, so changes only re-evaluate the subview, not the entire parent body.
6. Use LazyVStack/LazyHStack inside ScrollView for large collections — VStack evaluates ALL children upfront. Use List for very large datasets (10,000+) since it reuses cells.
7. Use .task modifier instead of .onAppear + Task {} — .task automatically cancels when the view disappears. Use .task(id:) to restart when a dependency changes.
8. Profile with Instruments BEFORE optimizing — measure first, optimize second. Never guess where the bottleneck is.
9. Never block the main thread — all file I/O, network calls, JSON decoding of large payloads, image processing, and database queries must run off the main thread.
10. Reuse expensive objects — URLSession, DateFormatter, JSONDecoder, NumberFormatter, NSRegularExpression are expensive to create. Use shared instances or caches.

Performance Targets

Metric	Target	Critical Threshold
Cold launch	<400ms to first frame	>2s triggers watchdog kill
Warm launch	<200ms	>1s feels broken
Frame rate	60 FPS (120 on ProMotion)	<45 FPS is noticeable jank
Frame budget	16.67ms (8.33ms at 120Hz)	>33ms = visible dropped frame
Memory (typical)	<100MB resident	>500MB risks jetsam on older devices
Memory (spike)	<200MB peak	Varies by device class
CPU idle	<3%	>5% drains battery
CPU active task	<80% sustained	100% = thermal throttling
API response (perceived)	<200ms	>1s needs loading indicator
App size (download)	<50MB (OTA limit: 200MB)	>200MB requires Wi-Fi
Disk writes	<1MB/min sustained	Excessive writes degrade flash

Quick Diagnosis Guide

Symptom	Instrument / Tool	Likely Cause	First Action
UI freezes / hangs	Time Profiler	Main thread blocking (sync I/O, heavy computation)	Check main thread call stack
Memory grows over time	Allocations + Memory Graph	Retain cycle or unbounded cache	Take heap snapshots, compare generations
Sudden memory spike	Allocations (VM Tracker)	Large image decode, bulk data load	Check transient allocations
Purple "memory" warning	Memory Graph Debugger	Retain cycle between objects	Trace reference chains
Dropped frames	Core Animation instrument	Offscreen rendering, layer blending	Enable "Color Blended Layers"
Battery drain	Energy Log	Excessive CPU, location, network polling	Check CPU/network wake frequency
Slow cold launch	App Launch instrument	Too many dylibs, heavy +load/init, sync main	Profile pre-main vs post-main
Slow scrolling (SwiftUI)	SwiftUI instrument	Non-lazy stacks, excessive redraws	Check body evaluation count
Slow scrolling (UIKit)	Time Profiler + Core Animation	Cell height calculation, offscreen rendering	Profile cellForRow time
Network slow	Network instrument	No HTTP/2 reuse, large payloads, no compression	Check connection count and sizes
Build slow	Xcode build timeline	Type inference, large files, no parallelism	Add -warn-long-function-bodies

Memory Management Quick Reference

// CORRECT: [weak self] in escaping closure
func fetchData() {
    networkService.fetch { [weak self] result in
        guard let self else { return }
        self.update(with: result)
    }
}

// CORRECT: [unowned self] ONLY when lifetime is guaranteed
class Parent {
    lazy var handler: () -> Void = { [unowned self] in
        self.doSomething()  // Parent always outlives its own lazy property
    }
}

// NOT NEEDED: Non-escaping closure — no capture cycle possible
let names = users.map { $0.name }          // map is non-escaping
let adults = users.filter { $0.age >= 18 } // filter is non-escaping
items.forEach { print($0) }                // forEach is non-escaping

// CORRECT: Weak delegate
protocol DataServiceDelegate: AnyObject {
    func didUpdate(_ data: Data)
}

class DataService {
    weak var delegate: DataServiceDelegate?
}

SwiftUI Performance Quick Reference

// BAD: One large view — any state change re-evaluates entire body
struct ProfileView: View {
    @State private var name = ""
    @State private var bio = ""
    @State private var avatarURL: URL?
    @State private var posts: [Post] = []

    var body: some View {
        ScrollView {
            avatarSection     // Change to name re-evaluates avatar too
            bioSection
            postsSection      // All 500 post cells re-evaluated
        }
    }
}

// GOOD: Extracted subviews — state changes localized
struct ProfileView: View {
    var body: some View {
        ScrollView {
            AvatarSection()   // Only re-evaluates when avatar changes
            BioSection()      // Only re-evaluates when bio changes
            PostsSection()    // Only re-evaluates when posts change
        }
    }
}

// GOOD: LazyVStack for scrollable content
struct PostsSection: View {
    let posts: [Post]

    var body: some View {
        LazyVStack {  // Only creates visible cells + prefetch buffer
            ForEach(posts) { post in
                PostRow(post: post)
            }
        }
    }
}

// GOOD: .task with auto-cancellation
struct UserDetailView: View {
    let userID: String
    @State private var user: User?

    var body: some View {
        content
            .task(id: userID) {  // Cancels & restarts if userID changes
                user = try? await api.fetchUser(userID)
            }
    }
}

@Observable vs ObservableObject

// OLD (iOS 14+): ObservableObject — ALL views re-evaluate on ANY change
class UserViewModel: ObservableObject {
    @Published var name = ""       // Change triggers ALL observers
    @Published var email = ""      // Change triggers ALL observers
    @Published var avatarURL: URL? // Change triggers ALL observers
}

// NEW (iOS 17+): @Observable — only views reading changed property re-evaluate
@Observable
class UserViewModel {
    var name = ""       // Only views reading `name` re-evaluate
    var email = ""      // Only views reading `email` re-evaluate
    var avatarURL: URL? // Only views reading `avatarURL` re-evaluate
}

Instruments Workflow

Step 1: Profile, Don't Debug

Always profile on a real device (not Simulator). Use Release configuration for accurate measurements.

Step 2: Choose the Right Instrument

• Time Profiler — CPU bottlenecks, main thread blocking
• Allocations — memory growth, leaks, allocation hotspots
• Leaks — automatic retain cycle detection (periodic snapshots)
• Memory Graph Debugger (Xcode, not Instruments) — visual reference chains
• Core Animation — rendering performance, blended layers, offscreen rendering
• Energy Log — battery drain causes (CPU, network, GPS, Bluetooth)
• Network — HTTP request/response analysis
• App Launch — cold/warm launch breakdown
• SwiftUI (Xcode 16+) — view body evaluations, cause & effect graph

Step 3: Time Profiler Settings (Always Set These)

1. Invert Call Tree — shows heaviest leaf functions first
2. Separate by Thread — isolates main thread work
3. Hide System Libraries — focuses on your code
4. Separate by State — shows running vs blocked time

Step 4: Record, Reproduce, Analyze

1. Record for 10-30 seconds covering the problematic interaction
2. Select the time range of interest
3. Look at the heaviest stack traces
4. Focus on main thread first (Thread 1)

App Launch Optimization Checklist

Pre-main Phase (<200ms target)

• Max 6 non-system dynamic frameworks (each adds ~10-20ms)
• No +load methods in ObjC code (move to +initialize or lazy init)
• Minimize static initializers (C++ globals, __attribute__((constructor)))
• Use static linking where possible (SPM default)

Post-main Phase (<200ms target)

• Defer non-essential initialization (analytics, logging, feature flags)
• Use lazy var for expensive properties
• Load first screen data from cache, then refresh from network
• Avoid synchronous network calls at launch
• Minimize work in application(_:didFinishLaunchingWithOptions:)
• Use Scene phase detection instead of heavy AppDelegate setup

Common Anti-Patterns

1. Main Thread Blocking

// BAD: Synchronous file read on main thread
let data = try! Data(contentsOf: largeFileURL)

// GOOD: Async file read
let data = try await Task.detached {
    try Data(contentsOf: largeFileURL)
}.value

2. Excessive Allocations in Loops

// BAD: Creates new DateFormatter per iteration (expensive!)
for event in events {
    let formatter = DateFormatter()
    formatter.dateFormat = "yyyy-MM-dd"
    labels.append(formatter.string(from: event.date))
}

// GOOD: Reuse formatter
let formatter = DateFormatter()
formatter.dateFormat = "yyyy-MM-dd"
for event in events {
    labels.append(formatter.string(from: event.date))
}

3. VStack for Large Collections

// BAD: Creates ALL 10,000 views upfront
ScrollView {
    VStack {
        ForEach(items) { item in  // 10,000 items = 10,000 views in memory
            ItemRow(item: item)
        }
    }
}

// GOOD: Only creates visible views
ScrollView {
    LazyVStack {
        ForEach(items) { item in  // ~20 views in memory at a time
            ItemRow(item: item)
        }
    }
}

4. Retaining Self in Timers

// BAD: Timer retains self, self retains timer → cycle
class PollingService {
    var timer: Timer?

    func start() {
        timer = Timer.scheduledTimer(withTimeInterval: 5, repeats: true) { _ in
            self.poll()  // Strong capture → retain cycle
        }
    }
}

// GOOD: Weak capture
func start() {
    timer = Timer.scheduledTimer(withTimeInterval: 5, repeats: true) { [weak self] _ in
        self?.poll()
    }
}

5. Not Cancelling Tasks

// BAD: Task keeps running after view disappears
.onAppear {
    Task {
        while !Task.isCancelled {
            await refresh()
            try await Task.sleep(for: .seconds(30))
        }
    }
}

// GOOD: .task auto-cancels on disappear
.task {
    while !Task.isCancelled {
        await refresh()
        try? await Task.sleep(for: .seconds(30))
    }
}

Reference Files

For deep dives, see:

• references/memory.md — ARC, retain cycles, value vs reference types, copy-on-write, debugging
• references/swiftui-perf.md — View identity, @Observable, lazy containers, images, .task
• references/instruments.md — Time Profiler, Allocations, Leaks, Energy, Core Animation, SwiftUI instrument
• references/optimization.md — App launch, network, battery, build performance, anti-patterns