1# Performance
2 
3Use this when:
4 
5- Async code is slower than expected or causing UI hangs.
6- You need to choose between synchronous, asynchronous, and parallel execution.
7- You are profiling concurrency overhead with Instruments.
8 
9Skip this file if:
10 
11- The issue is a compiler diagnostic about isolation or Sendable. Use `actors.md` or `sendable.md`.
12- You mainly need to fix a memory leak. Use `memory-management.md`.
13 
14Jump to:
15 
16- Core Principles
17- Common Performance Issues
18- Using Xcode Instruments
19- Suspension Points / Reducing Suspensions
20- Choosing Execution Style
21- Parallelism Costs
22- Optimization Checklist
23 
24## Core Principles
25 
26### Measurement is essential
27 
28Can't improve what you don't measure. Establish baseline before optimizing.
29 
30### Start simple, optimize later
31 
32```
33Synchronous → Asynchronous → Parallel
34```
35 
36Move right only when proven necessary.
37 
38### Three phases of concurrency
39 
401. **No concurrency** - Synchronous method
412. **Suspend without parallelism** - Asynchronous method
423. **Advanced concurrency** - Parallel execution
43 
44## Common Performance Issues
45 
46### UI hangs
47 
48Too much work on main thread causes interface freezes.
49 
50### Poor parallelization
51 
52Heavy work funneled into single task instead of parallel execution.
53 
54### Actor contention
55 
56Tasks waiting on busy actor, causing unnecessary suspensions.
57 
58## Using Xcode Instruments
59 
60### Swift Concurrency template
61 
62Profile with CMD + I → Select "Swift Concurrency" template.
63 
64**Instruments included**:
65- **Swift Tasks**: Track running, alive, total tasks
66- **Swift Actors**: Show actor execution and queue size
67 
68### Key metrics
69 
70```
71Tasks:
72- Total count
73- Running vs suspended
74- Task states (Creating, Running, Suspended, Ending)
75 
76Actors:
77- Queue size
78- Execution time
79- Contention points
80 
81Main Thread:
82- Hangs
83- Blocked time
84```
85 
86### Task states
87 
88- **Creating**: Task being initialized
89- **Running**: Actively executing
90- **Suspended**: Waiting (at await)
91- **Ending**: Completing
92 
93> **Course Deep Dive**: This topic is covered in detail in [Lesson 10.1: Using Xcode Instruments to find performance bottlenecks](https://www.swiftconcurrencycourse.com?utm_source=github&utm_medium=agent-skill&utm_campaign=lesson-reference)
94 
95## Identifying Issues
96 
97### Main thread blocked
98 
99```swift
100// ❌ All work on main thread
101@MainActor
102func generateWallpapers() {
103    Task {
104        for _ in 0..<100 {
105            let image = generator.generate() // Blocks main thread
106            wallpapers.append(image)
107        }
108    }
109}
110```
111 
112**Instruments shows**: Long main thread hang, no parallelism.
113 
114### Solution: Move to background
115 
116```swift
117@MainActor
118func generateWallpapers() {
119    Task {
120        for _ in 0..<100 {
121            let image = await backgroundGenerator.generate()
122            wallpapers.append(image)
123        }
124    }
125}
126 
127actor BackgroundGenerator {
128    func generate() -> Image {
129        // Heavy work in background
130    }
131}
132```
133 
134### Actor contention
135 
136```swift
137actor Generator {
138    func generate() -> Image {
139        // Heavy work
140    }
141}
142 
143// ❌ Sequential through actor
144for _ in 0..<100 {
145    let image = await generator.generate() // Queue size = 1
146}
147```
148 
149**Instruments shows**: Actor queue never exceeds 1, no parallelism.
150 
151### Solution: Remove unnecessary actor
152 
153```swift
154struct Generator {
155    @concurrent
156    static func generate() async -> Image {
157        // Heavy work, no shared state
158    }
159}
160 
161// ✅ Parallel execution
162for i in 0..<100 {
163    Task(name: "Image \(i)") {
164        let image = await Generator.generate()
165        await addToCollection(image)
166    }
167}
168```
169 
170## Suspension Points
171 
172### What creates suspension
173 
174Every `await` is potential suspension point:
175 
176```swift
177let data = await fetchData() // May suspend
178```
179 
180**Not guaranteed** - if isolation matches, may not suspend.
181 
182### Suspension surface area
183 
184Code between suspension points. Larger = harder to reason about:
185- Actor invariants
186- Performance
187- Thread hops
188- Reentrancy
189- State consistency
190 
191### Goal
192 
193- Do work before crossing isolation
194- Cross once
195- Finish job
196- Only cross again when necessary
197 
198## Reducing Suspensions
199 
200### 1. Use synchronous methods
201 
202```swift
203// ❌ Unnecessary async
204private func scale(_ image: CGImage) async { }
205 
206func process(_ image: CGImage) async {
207    let scaled = await scale(image) // Suspension point
208}
209 
210// ✅ Synchronous helper
211private func scale(_ image: CGImage) { }
212 
213func process(_ image: CGImage) async {
214    let scaled = scale(image) // No suspension
215}
216```
217 
218**Rule**: If method doesn't need to suspend, don't mark async.
219 
220### 2. Prevent actor reentrancy
221 
222```swift
223// ❌ Reenters actor
224actor BankAccount {
225    func deposit(_ amount: Int) async {
226        balance += amount
227        await logTransaction() // Leaves actor
228        balance += bonus // Reenters - state may have changed
229    }
230}
231 
232// ✅ Complete work before leaving
233actor BankAccount {
234    func deposit(_ amount: Int) async {
235        balance += amount
236        balance += bonus
237        await logTransaction() // Leave after state changes
238    }
239}
240```
241 
242### 3. Inherit isolation
243 
244```swift
245// ❌ Switches isolation
246@MainActor
247func update() async {
248    await process() // Switches away from main actor
249}
250 
251// ✅ Inherits isolation (still requires await -- but no executor hop)
252@MainActor
253func update() async {
254    await process() // Stays on main actor when nonisolated(nonsending)
255}
256 
257nonisolated(nonsending) func process() async { }
258```
259 
260> **Course Deep Dive**: This topic is covered in detail in [Lesson 10.2: Reducing suspension points by managing isolation effectively](https://www.swiftconcurrencycourse.com?utm_source=github&utm_medium=agent-skill&utm_campaign=lesson-reference)
261 
262### 4. Use non-suspending APIs
263 
264```swift
265// ❌ May suspend
266try await Task.checkCancellation()
267 
268// ✅ No suspension
269if Task.isCancelled {
270    return
271}
272```
273 
274### 5. Match Task entry isolation to its synchronous prefix
275 
276For unstructured `Task { ... }`, decide startup isolation from the synchronous prefix (everything before the first `await`). If that prefix needs main-actor access, keep inherited `@MainActor` entry. If the prefix does not need main actor, use `Task { @concurrent in ... }` and hop back with `MainActor.run` only when UI-owned mutation is required. A trivial non-main line (such as `print`) does **not** justify `@concurrent` when main-actor work already exists in the same prefix.
277 
278```swift
279// ❌ Synchronous prefix is empty; first work hops away
280Task {
281    await hopToOtherIsolationDomain()
282}
283 
284// ❌ Synchronous prefix is only `print` (trivial, non-main); first await hops away
285Task {
286    print("Also not main-thread-bound")
287    await hopToOtherIsolationDomain()
288}
289 
290// ✅ Start off the main actor, hop back only for UI work
291Task { @concurrent in
292    await hopToOtherIsolationDomain()
293    await MainActor.run { updateUI() }
294}
295 
296// ✅ Synchronous prefix DOES contain main-actor work — keep inheritance
297Task {
298    print("debug")              // trivial, non-main — rides along
299    self.isLoading = true       // needs @MainActor, before any await
300    await fetchData()
301}
302```
303 
304Delayed retry is one specialization of this rule:
305 
306```swift
307// ❌ Can wait for MainActor, then suspend immediately
308registrationRetryTask = Task { @MainActor [weak self] in
309    try? await Task.sleep(for: .milliseconds(100))
310    guard let self else { return }
311    self.registrationRetryTask = nil
312    self.updateConnectedTargetWindow()
313}
314```
315 
316The delay itself is not UI work. Starting on `@MainActor` can add an avoidable executor wait before reaching `Task.sleep`, especially when scheduled from another executor or while the main actor is busy.
317 
318```swift
319// ✅ Sleep off-main, hop back only for the UI-owned work
320registrationRetryTask = Task { @concurrent [weak self] in
321    do {
322        try await Task.sleep(for: .milliseconds(100))
323    } catch is CancellationError {
324        return
325    }
326    guard let self else { return }
327 
328    await MainActor.run {
329        self.registrationRetryTask = nil
330        self.updateConnectedTargetWindow()
331    }
332}
333```
334 
335Use this rule for any unstructured task: delayed retries, backoff, timer-like work, off-main computation, and actor hops. The key check is always “what runs before the first `await`?”, not “what does the task eventually do?”.
336 
337### 6. Embrace parallelism
338 
339```swift
340// ❌ Sequential
341for url in urls {
342    let image = await download(url)
343    images.append(image)
344}
345 
346// ✅ Parallel
347await withTaskGroup(of: Image.self) { group in
348    for url in urls {
349        group.addTask { await download(url) }
350    }
351    for await image in group {
352        images.append(image)
353    }
354}
355```
356 
357## Analyzing Suspensions in Instruments
358 
359### View task states
360 
3611. Select Swift Tasks instrument
3622. Switch to "Task States" view
3633. Look for Suspended states
3644. Check suspension duration
365 
366### Navigate to code
367 
3681. Click task state (Running/Suspended)
3692. Open Extended Detail
3703. Click related method
3714. Use "Open in Source Viewer"
372 
373### Predict suspensions
374 
375```swift
376Task {
377    // State 1: Running
378    // State 2: Suspended (switch to background)
379    let data = await backgroundWork()
380    // State 3: Running (in background)
381    // State 4: Suspended (switch to main actor)
382    // State 5: Running (on main actor)
383    await MainActor.run {
384        updateUI(data)
385    }
386}
387```
388 
389### Optimization example
390 
391```swift
392// Before: Two suspensions
393Task {
394    let data = await generate() // Suspension 1
395    self.items.append(data) // Suspension 2 (back to main)
396}
397 
398> **Course Deep Dive**: This topic is covered in detail in [Lesson 10.3: Using Xcode Instruments to detect and remove suspension points](https://www.swiftconcurrencycourse.com?utm_source=github&utm_medium=agent-skill&utm_campaign=lesson-reference)
399 
400// After: One suspension
401Task { @concurrent in
402    let data = generate() // No suspension (synchronous)
403    await MainActor.run {
404        self.items.append(data) // Suspension 1 (to main)
405    }
406}
407```
408 
409## Choosing Execution Style
410 
411### Decision checklist
412 
413**Use async/parallel if**:
414- [ ] Blocks main actor visibly (>16ms)
415- [ ] Scales with data (N items → N cost)
416- [ ] Involves I/O (network, disk)
417- [ ] Benefits from combining operations
418- [ ] Called frequently
419 
420**2+ checks** → async/parallel justified.
421 
422### Start synchronous
423 
424```swift
425// Start here
426func processData(_ data: Data) -> Result {
427    // Fast, in-memory work
428}
429```
430 
431**Only move to async if**:
432- Instruments show main thread hang
433- User reports sluggishness
434- Work scales with input size
435 
436### When to use async
437 
438```swift
439func processData(_ data: Data) async -> Result {
440    // Use when:
441    // - Touches persistent storage
442    // - Parses large datasets
443    // - Network communication
444    // - Proven slow by profiling
445}
446```
447 
448### When to use parallel
449 
450```swift
451await withTaskGroup(of: Result.self) { group in
452    for item in items {
453        group.addTask { await process(item) }
454    }
455}
456 
457// Use when:
458// - Multiple independent operations
459// - Time-to-first-result matters
460 
461> **Course Deep Dive**: This topic is covered in detail in [Lesson 10.4: How to choose between serialized, asynchronous, and parallel execution](https://www.swiftconcurrencycourse.com?utm_source=github&utm_medium=agent-skill&utm_campaign=lesson-reference)
462// - Work scales with collection size
463// - Proven beneficial by profiling
464```
465 
466## Parallelism Costs
467 
468### Tradeoffs
469 
470**Benefits**:
471- Faster completion (if CPU-bound)
472- Better resource utilization
473- Improved responsiveness
474 
475**Costs**:
476- Increased memory pressure
477- CPU scheduling overhead
478- System resource saturation
479- Battery drain
480- Thermal impact
481 
482### When parallelism hurts
483 
484```swift
485// ❌ Over-parallelization
486for i in 0..<1000 {
487    Task { await lightWork(i) }
488}
489// Creates 1000 tasks for trivial work
490```
491 
492**Better**: Batch work or use fewer tasks.
493 
494## UX-Driven Decisions
495 
496### Smooth animations > raw speed
497 
498```swift
499// 80ms on main thread, but animation stutters
500@MainActor
501func process() {
502    heavyWork() // Freezes UI for 1 frame
503}
504 
505// 100ms total, but smooth UI
506@MainActor
507func process() async {
508    await backgroundWork() // UI stays responsive
509}
510```
511 
512**Perception**: Smooth feels faster than raw speed.
513 
514### Progress indication
515 
516```swift
517@MainActor
518func loadItems() async {
519    isLoading = true
520    
521    for i in 0..<100 {
522        let item = await fetchItem(i)
523        items.append(item)
524        progress = Double(i) / 100 // Incremental updates
525    }
526    
527    isLoading = false
528}
529```
530 
531Background work + progress = feels faster.
532 
533## Optimization Checklist
534 
535Before optimizing, ask:
536 
537- [ ] Have I profiled with Instruments?
538- [ ] Is main thread actually blocked?
539- [ ] Can this be synchronous?
540- [ ] Am I over-parallelizing?
541- [ ] Is actor contention the issue?
542- [ ] Are suspensions necessary?
543- [ ] Does UX require background work?
544- [ ] Will this scale with data?
545 
546Anti-patterns to avoid with unstructured tasks:
547- Starting on inherited `@MainActor` when nothing in the synchronous prefix (before first `await`) needs main actor.
548- Moving trivial non-main lines off `@MainActor` when the same synchronous prefix already includes required main-actor mutation.
549 
550## Common Patterns
551 
552### Move heavy work to background
553 
554```swift
555// Before
556@MainActor
557func generate() {
558    for _ in 0..<100 {
559        let item = heavyGeneration()
560        items.append(item)
561    }
562}
563 
564// After
565@MainActor
566func generate() async {
567    for _ in 0..<100 {
568        let item = await backgroundGenerate()
569        items.append(item)
570    }
571}
572 
573@concurrent
574func backgroundGenerate() async -> Item {
575    // Heavy work off main thread
576}
577```
578 
579### Parallelize independent work
580 
581```swift
582// Before: Sequential
583for url in urls {
584    let image = await download(url)
585    images.append(image)
586}
587 
588// After: Parallel
589await withTaskGroup(of: Image.self) { group in
590    for url in urls {
591        group.addTask { await download(url) }
592    }
593    for await image in group {
594        images.append(image)
595    }
596}
597```
598 
599### Reduce actor hops
600 
601```swift
602// Before: Multiple hops
603actor Store {
604    func process() async {
605        let a = await fetch1() // Hop 1
606        let b = await fetch2() // Hop 2
607        let c = await fetch3() // Hop 3
608        combine(a, b, c)
609    }
610}
611 
612// After: Batch fetches
613actor Store {
614    func process() async {
615        async let a = fetch1()
616        async let b = fetch2()
617        async let c = fetch3()
618        combine(await a, await b, await c) // One hop
619    }
620}
621```
622 
623## Best Practices
624 
6251. **Profile before optimizing** - measure baseline
6262. **Start synchronous** - add async only when needed
6273. **Use Instruments regularly** - catch issues early
6284. **Name tasks** - easier debugging in Instruments
6295. **Check suspension count** - reduce unnecessary awaits
6306. **Avoid premature parallelism** - has costs
6317. **Consider UX** - smooth > fast
6328. **Batch actor work** - reduce contention
6339. **Test on real devices** - simulators lie
63410. **Monitor in production** - real usage patterns differ
635 
636## Debugging Performance
637 
638### Instruments workflow
639 
6401. Profile with Swift Concurrency template
6412. Identify main thread hangs
6423. Check task parallelism
6434. Analyze actor queue sizes
6445. Review suspension points
6456. Navigate to problematic code
6467. Apply optimizations
6478. Re-profile to verify
648 
649### Red flags in Instruments
650 
651- Main thread blocked >16ms
652- Actor queue size always 1
653- High suspension count
654- Tasks created but not running
655- Excessive task creation (1000+)
656 
657## Further Learning
658 
659For real-world optimization examples, profiling techniques, and advanced performance patterns, see [Swift Concurrency Course](https://www.swiftconcurrencycourse.com).
660 
661