1# Memory Management
2 
3Use this when:
4 
5- A task or async sequence is keeping objects alive longer than expected.
6- You suspect a retain cycle between a task and its owner.
7- You need to verify deallocation behavior or use `isolated deinit`.
8 
9Skip this file if:
10 
11- You mainly need to protect mutable state from races. Use `actors.md`.
12- You are debugging slow async code. Use `performance.md`.
13 
14Jump to:
15 
16- Core Concepts (Task Capture)
17- Retain Cycles
18- One-Way Retention
19- Async Sequences and Retention
20- Isolated Deinit (Swift 6.2+)
21- Detection and Testing
22- Common Patterns
23 
24## Core Concepts
25 
26### Tasks capture like closures
27 
28Tasks capture variables and references just like regular closures. Swift doesn't automatically prevent retain cycles in concurrent code.
29 
30```swift
31Task {
32    self.doWork() // ⚠️ Strong capture of self
33}
34```
35 
36### Why concurrency hides memory issues
37 
38- Tasks may live longer than expected
39- Async operations delay execution
40- Harder to track when memory should be released
41- Long-running tasks can hold references indefinitely
42 
43> **Course Deep Dive**: This topic is covered in detail in [Lesson 8.1: Overview of memory management in Swift Concurrency](https://www.swiftconcurrencycourse.com?utm_source=github&utm_medium=agent-skill&utm_campaign=lesson-reference)
44 
45## Retain Cycles
46 
47### What is a retain cycle?
48 
49Two or more objects hold strong references to each other, preventing deallocation.
50 
51```swift
52class A {
53    var b: B?
54}
55 
56class B {
57    var a: A?
58}
59 
60let a = A()
61let b = B()
62a.b = b
63b.a = a // Retain cycle - neither can be deallocated
64```
65 
66### Retain cycles with Tasks
67 
68When task captures `self` strongly and `self` owns the task:
69 
70```swift
71@MainActor
72final class ImageLoader {
73    var task: Task<Void, Never>?
74    
75    func startPolling() {
76        task = Task {
77            while true {
78                self.pollImages() // ⚠️ Strong capture
79                try? await Task.sleep(for: .seconds(1))
80            }
81        }
82    }
83}
84 
85var loader: ImageLoader? = .init()
86loader?.startPolling()
87loader = nil // ⚠️ Loader never deallocated - retain cycle!
88```
89 
90**Problem**: Task holds `self`, `self` holds task → neither released.
91 
92## Breaking Retain Cycles
93 
94### Use weak self
95 
96```swift
97func startPolling() {
98    task = Task { [weak self] in
99        while let self = self {
100            self.pollImages()
101            try? await Task.sleep(for: .seconds(1))
102        }
103    }
104}
105 
106var loader: ImageLoader? = .init()
107loader?.startPolling()
108loader = nil // ✅ Loader deallocated, task stops
109```
110 
111### Pattern for long-running tasks
112 
113```swift
114task = Task { [weak self] in
115    while let self = self {
116        await self.doWork()
117        try? await Task.sleep(for: interval)
118    }
119}
120```
121 
122> **Course Deep Dive**: This topic is covered in detail in [Lesson 8.2: Preventing retain cycles when using Tasks](https://www.swiftconcurrencycourse.com?utm_source=github&utm_medium=agent-skill&utm_campaign=lesson-reference)
123 
124Loop exits when `self` becomes `nil`.
125 
126## One-Way Retention
127 
128Task retains `self`, but `self` doesn't retain task. Object stays alive until task completes.
129 
130```swift
131@MainActor
132final class ViewModel {
133    func fetchData() {
134        Task {
135            await performRequest()
136            updateUI() // ⚠️ Strong capture
137        }
138    }
139}
140 
141var viewModel: ViewModel? = .init()
142viewModel?.fetchData()
143viewModel = nil // ViewModel stays alive until task completes
144```
145 
146**Execution order**:
1471. Task starts
1482. `viewModel = nil` (but object not deallocated)
1493. Task completes
1504. ViewModel finally deallocated
151 
152### When one-way retention is acceptable
153 
154Short-lived tasks that complete quickly:
155 
156```swift
157func saveData() {
158    Task {
159        await database.save(self.data) // OK - completes quickly
160    }
161}
162```
163 
164### When to use weak self
165 
166Long-running or indefinite tasks:
167 
168```swift
169func startMonitoring() {
170    Task { [weak self] in
171        for await event in eventStream {
172            self?.handle(event)
173        }
174    }
175}
176```
177 
178## Async Sequences and Retention
179 
180### Problem: Infinite sequences
181 
182```swift
183@MainActor
184final class AppLifecycleViewModel {
185    private(set) var isActive = false
186    private var task: Task<Void, Never>?
187    
188    func startObserving() {
189        task = Task {
190            for await _ in NotificationCenter.default.notifications(
191                named: .didBecomeActive
192            ) {
193                isActive = true // ⚠️ Strong capture, never ends
194            }
195        }
196    }
197}
198 
199var viewModel: AppLifecycleViewModel? = .init()
200viewModel?.startObserving()
201viewModel = nil // ⚠️ Never deallocated - sequence continues
202```
203 
204**Problem**: Async sequence never finishes, task holds `self` indefinitely.
205 
206### Solution 1: Manual cancellation
207 
208```swift
209func startObserving() {
210    task = Task {
211        for await _ in NotificationCenter.default.notifications(
212            named: .didBecomeActive
213        ) {
214            isActive = true
215        }
216    }
217}
218 
219func stopObserving() {
220    task?.cancel()
221}
222 
223// Usage
224viewModel?.startObserving()
225viewModel?.stopObserving() // Must call before release
226viewModel = nil
227```
228 
229### Solution 2: Weak self with guard
230 
231```swift
232func startObserving() {
233    task = Task { [weak self] in
234        for await _ in NotificationCenter.default.notifications(
235            named: .didBecomeActive
236        ) {
237            guard let self = self else { return }
238            self.isActive = true
239        }
240    }
241}
242```
243 
244Task exits when `self` deallocates.
245 
246## Isolated deinit (Swift 6.2+)
247 
248Clean up actor-isolated state in deinit:
249 
250```swift
251@MainActor
252final class ViewModel {
253    private var task: Task<Void, Never>?
254    
255    isolated deinit {
256        task?.cancel()
257    }
258}
259```
260 
261**Limitation**: Won't break retain cycles (deinit never called if cycle exists).
262 
263**Use for**: Cleanup when object is being deallocated normally.
264 
265## Common Patterns
266 
267### Short-lived task (strong capture OK)
268 
269```swift
270func saveData() {
271    Task {
272        await database.save(self.data)
273        self.updateUI()
274    }
275}
276```
277 
278**When safe**: Task completes quickly, acceptable for object to live until done.
279 
280### Long-running task (weak self required)
281 
282```swift
283func startPolling() {
284    task = Task { [weak self] in
285        while let self = self {
286            await self.fetchUpdates()
287            try? await Task.sleep(for: .seconds(5))
288        }
289    }
290}
291```
292 
293### Async sequence monitoring (weak self + guard)
294 
295```swift
296func startMonitoring() {
297    task = Task { [weak self] in
298        for await event in eventStream {
299            guard let self = self else { return }
300            self.handle(event)
301        }
302    }
303}
304```
305 
306### Cancellable work with cleanup
307 
308```swift
309func startWork() {
310    task = Task { [weak self] in
311        defer { self?.cleanup() }
312        
313        while let self = self {
314            await self.doWork()
315            try? await Task.sleep(for: .seconds(1))
316        }
317    }
318}
319```
320 
321## Detection Strategies
322 
323### Add deinit logging
324 
325```swift
326deinit {
327    print("✅ \(type(of: self)) deallocated")
328}
329```
330 
331If deinit never prints → likely retain cycle.
332 
333### Memory graph debugger
334 
3351. Run app in Xcode
3362. Debug → Debug Memory Graph
3373. Look for cycles in object graph
338 
339### Instruments
340 
341Use Leaks instrument to detect retain cycles at runtime.
342 
343## Decision Tree
344 
345```
346Task captures self?
347├─ Task completes quickly?
348│  └─ Strong capture OK
349│
350├─ Long-running or infinite?
351│  ├─ Can use weak self? → Use [weak self]
352│  ├─ Need manual control? → Store task, cancel explicitly
353│  └─ Async sequence? → [weak self] + guard
354│
355└─ Self owns task?
356   ├─ Yes → High risk of retain cycle
357   └─ No → Lower risk, but check lifetime
358```
359 
360## Best Practices
361 
3621. **Default to weak self** for long-running tasks
3632. **Use guard let self** in async sequences
3643. **Cancel tasks explicitly** when possible
3654. **Add deinit logging** during development
3665. **Test object deallocation** in unit tests
3676. **Use Memory Graph** to verify no cycles
3687. **Document lifetime expectations** in comments
3698. **Prefer cancellation** over weak self when possible
3709. **Avoid nested strong captures** in task closures
37110. **Use isolated deinit** for cleanup (Swift 6.2+)
372 
373## Testing for Leaks
374 
375### Unit test pattern
376 
377```swift
378func testViewModelDeallocates() async {
379    var viewModel: ViewModel? = ViewModel()
380    weak var weakViewModel = viewModel
381    
382    viewModel?.startWork()
383    viewModel = nil
384    
385    // Give tasks time to complete
386    try? await Task.sleep(for: .milliseconds(100))
387    
388    XCTAssertNil(weakViewModel, "ViewModel should be deallocated")
389}
390```
391 
392### SwiftUI view test
393 
394```swift
395func testViewDeallocates() {
396    var view: MyView? = MyView()
397    weak var weakView = view
398    
399    view = nil
400    
401    XCTAssertNil(weakView)
402}
403```
404 
405## Common Mistakes
406 
407### ❌ Forgetting weak self in loops
408 
409```swift
410Task {
411    while true {
412        self.poll() // Retain cycle
413        try? await Task.sleep(for: .seconds(1))
414    }
415}
416```
417 
418### ❌ Strong capture in async sequences
419 
420```swift
421Task {
422    for await item in stream {
423        self.process(item) // May never release
424    }
425}
426```
427 
428### ❌ Not canceling stored tasks
429 
430```swift
431class Manager {
432    var task: Task<Void, Never>?
433    
434    func start() {
435        task = Task {
436            await self.work() // Retain cycle
437        }
438    }
439    
440    // Missing: deinit { task?.cancel() }
441}
442```
443 
444### ❌ Assuming deinit breaks cycles
445 
446```swift
447deinit {
448    task?.cancel() // Never called if retain cycle exists
449}
450```
451 
452## Examples by Use Case
453 
454### Polling service
455 
456```swift
457final class PollingService {
458    private var task: Task<Void, Never>?
459    
460    func start() {
461        task = Task { [weak self] in
462            while let self = self {
463                await self.poll()
464                try? await Task.sleep(for: .seconds(5))
465            }
466        }
467    }
468    
469    func stop() {
470        task?.cancel()
471    }
472}
473```
474 
475### Notification observer
476 
477```swift
478@MainActor
479final class NotificationObserver {
480    private var task: Task<Void, Never>?
481    
482    func startObserving() {
483        task = Task { [weak self] in
484            for await notification in NotificationCenter.default.notifications(
485                named: .someNotification
486            ) {
487                guard let self = self else { return }
488                self.handle(notification)
489            }
490        }
491    }
492    
493    isolated deinit {
494        task?.cancel()
495    }
496}
497```
498 
499### Download manager
500 
501```swift
502final class DownloadManager {
503    private var tasks: [URL: Task<Data, Error>] = [:]
504    
505    func download(_ url: URL) async throws -> Data {
506        let task = Task { [weak self] in
507            defer { self?.tasks.removeValue(forKey: url) }
508            return try await URLSession.shared.data(from: url).0
509        }
510        
511        tasks[url] = task
512        return try await task.value
513    }
514    
515    func cancelAll() {
516        tasks.values.forEach { $0.cancel() }
517        tasks.removeAll()
518    }
519}
520```
521 
522### Timer
523 
524```swift
525actor Timer {
526    private var task: Task<Void, Never>?
527    
528    func start(interval: Duration, action: @Sendable () async -> Void) {
529        task = Task {
530            while !Task.isCancelled {
531                await action()
532                try? await Task.sleep(for: interval)
533            }
534        }
535    }
536    
537    func stop() {
538        task?.cancel()
539    }
540}
541```
542 
543## Common Mistakes Agents Make
544 
545- **Forgetting `[weak self]` in stored tasks**: When `self` owns the task and the task captures `self`, a retain cycle prevents deallocation.
546- **Strong capture in infinite `AsyncSequence` loops**: `for await` over an infinite sequence with a strong `self` capture keeps the object alive forever.
547- **Not cancelling stored tasks on cleanup**: If the task outlives its owner, it retains captured objects indefinitely.
548- **Assuming `isolated deinit` breaks retain cycles**: `isolated deinit` runs cleanup on the correct actor, but if a cycle prevents `deinit` from being called at all, the cleanup never executes.
549- **Using `try?` in loops with `Task.sleep`**: `try?` can swallow `CancellationError`, causing the loop to continue running after cancellation. Always check `Task.isCancelled` explicitly.
550 
551## Debugging Checklist
552 
553When object won't deallocate:
554 
555- [ ] Check for strong self captures in tasks
556- [ ] Verify tasks are canceled or complete
557- [ ] Look for infinite loops or sequences
558- [ ] Check if self owns the task
559- [ ] Use Memory Graph to find cycles
560- [ ] Add deinit logging to verify
561- [ ] Test with weak references
562- [ ] Review async sequence usage
563- [ ] Check nested task captures
564- [ ] Verify cleanup in deinit
565 
566## Further Learning
567 
568For migration strategies, real-world examples, and advanced memory patterns, see [Swift Concurrency Course](https://www.swiftconcurrencycourse.com).
569 
570