1# Migration to Swift 6 and Strict Concurrency
2 
3Use this when:
4 
5- You are moving an existing codebase toward Swift 6 or stricter concurrency checking.
6- Compiler diagnostics depend on language mode, default isolation, or upcoming features.
7- You need the smallest safe migration sequence instead of a full architectural rewrite.
8 
9Skip this file if:
10 
11- You already know the exact diagnostic and only need a local fix. Start from `actors.md`, `sendable.md`, or `threading.md`.
12- You are looking for debounce, stream composition, or FRP operator replacements. Use `async-algorithms.md`.
13 
14Jump to:
15 
16- Project Settings
17- Six Migration Habits
18- Step-by-Step Migration
19- Migration Tooling
20- Rewriting Closures to Async/Await
21- Migrating from Combine/RxSwift
22- Concurrency-Safe Notifications (iOS 26+)
23- Anti-Patterns
24 
25---
26 
27## Why Migrate to Swift 6?
28 
29Swift 6 doesn't fundamentally change how Swift Concurrency works—it **enforces existing rules more strictly**:
30 
31- **Compile-time safety**: Catches data races and threading issues at compile time instead of runtime
32- **Warnings become errors**: Many Swift 5 warnings become hard errors in Swift 6 language mode
33- **Future-proofing**: New concurrency features will build on this stricter foundation
34- **Better maintainability**: Code becomes safer and easier to reason about
35 
36> **Important**: You can adopt strict concurrency checking gradually while still compiling under Swift 5. You don't need to flip the Swift 6 switch immediately.
37 
38> **Course Deep Dive**: This topic is covered in detail in [Lesson 12.2: The impact of Swift 6 on Swift Concurrency](https://www.swiftconcurrencycourse.com?utm_source=github&utm_medium=agent-skill&utm_campaign=lesson-reference)
39 
40---
41 
42## Project Settings That Change Concurrency Behavior
43 
44Before interpreting diagnostics or choosing a fix, confirm the target/module settings. These settings can materially change how code executes and what the compiler enforces.
45 
46### Quick matrix
47 
48| Setting / feature | Where to check | Why it matters |
49|---|---|---|
50| Swift language mode (Swift 5.x vs Swift 6) | Xcode build settings (`SWIFT_VERSION`) / SwiftPM `// swift-tools-version:` | Swift 6 turns many warnings into errors and enables stricter defaults. |
51| Strict concurrency checking | Xcode: Strict Concurrency Checking (`SWIFT_STRICT_CONCURRENCY`) / SwiftPM: strict concurrency flags | Controls how aggressively Sendable + isolation rules are enforced. |
52| Default actor isolation | Xcode: Default Actor Isolation (`SWIFT_DEFAULT_ACTOR_ISOLATION`) / SwiftPM: `.defaultIsolation(MainActor.self)` | Changes the default isolation of declarations; can reduce migration noise but changes behavior and requirements. |
53| `NonisolatedNonsendingByDefault` | Xcode upcoming feature / SwiftPM `.enableUpcomingFeature("NonisolatedNonsendingByDefault")` | Changes how nonisolated async functions execute (can inherit the caller’s actor unless explicitly marked `@concurrent`). |
54| Approachable Concurrency | Xcode build setting / SwiftPM enables the underlying upcoming features | Bundles multiple upcoming features; recommended to migrate feature-by-feature first. |
55 
56## The Concurrency Rabbit Hole
57 
58A common migration experience:
59 
601. Enable strict concurrency checking
612. See 50+ errors and warnings
623. Fix a bunch of them
634. Rebuild and see 80+ new errors appear
64 
65**Why this happens**: Fixing isolation in one place often exposes issues elsewhere. This is normal and manageable with the right strategy.
66 
67> **Course Deep Dive**: This topic is covered in detail in [Lesson 12.1: Challenges in migrating to Swift Concurrency](https://www.swiftconcurrencycourse.com?utm_source=github&utm_medium=agent-skill&utm_campaign=lesson-reference)
68 
69---
70 
71## Six Migration Habits for Success
72 
73### 1. Don't Panic—It's All About Iterations
74 
75Break migration into small, manageable chunks:
76 
77```swift
78// Day 1: Enable strict concurrency, fix a few warnings
79// Build Settings → Strict Concurrency Checking = Complete
80 
81// Day 2: Fix more warnings
82 
83// Day 3: Revert to minimal checking if needed
84// Build Settings → Strict Concurrency Checking = Minimal
85```
86 
87Allow yourself 30 minutes per day to migrate gradually. Don't expect completion in a few days for large projects.
88 
89### 2. Sendable by Default for New Code
90 
91When writing new types, make them `Sendable` from the start:
92 
93```swift
94// ✅ Good: New code prepared for Swift 6
95struct UserProfile: Sendable {
96    let id: UUID
97    let name: String
98}
99 
100// ❌ Avoid: Creating technical debt
101class UserProfile {  // Will need migration later
102    var id: UUID
103    var name: String
104}
105```
106 
107It's easier to design for concurrency upfront than to retrofit it later.
108 
109### 3. Use Swift 6 for New Projects and Packages
110 
111For new projects, packages, or files:
112- Enable Swift 6 language mode from the start
113- Use Swift Concurrency features (async/await, actors)
114- Reduce technical debt before it accumulates
115 
116You can enable Swift 6 for individual files in a Swift 5 project to prevent scope creep.
117 
118### 4. Resist the Urge to Refactor
119 
120**Focus solely on concurrency changes**. Don't combine migration with:
121- Architecture refactors
122- API modernization
123- Code style improvements
124 
125Create separate tickets for non-concurrency refactors and address them later.
126 
127### 5. Focus on Minimal Changes
128 
129- Make small, focused pull requests
130- Migrate one class or module at a time
131- Get changes merged quickly to create checkpoints
132- Avoid large PRs that are hard to review
133 
134### 6. Don't Just @MainActor All the Things
135 
136Don't blindly add `@MainActor` to fix warnings. Consider:
137- Should this actually run on the main actor?
138- Would a custom actor be more appropriate?
139- Is `nonisolated` the right choice?
140 
141**Exception**: For app projects (not frameworks), consider enabling **Default Actor Isolation** to `@MainActor`, since most app code needs main thread access.
142 
143> **Course Deep Dive**: This topic is covered in detail in [Lesson 12.3: The six migration habits for a successful migration](https://www.swiftconcurrencycourse.com?utm_source=github&utm_medium=agent-skill&utm_campaign=lesson-reference)
144 
145---
146 
147## Step-by-Step Migration Process
148 
149### 1. Find an Isolated Piece of Code
150 
151Start with:
152- Standalone packages with minimal dependencies
153- Individual Swift files within a package
154- Code that's not heavily used throughout the project
155 
156**Why**: Fewer dependencies = less risk of falling into the concurrency rabbit hole.
157 
158### 2. Update Related Dependencies
159 
160Before enabling strict concurrency:
161 
162```swift
163// Update third-party packages to latest versions
164// Example: Vapor, Alamofire, etc.
165```
166 
167Apply these updates in a separate PR before proceeding with concurrency changes.
168 
169### 3. Add Async Alternatives
170 
171Provide async/await wrappers for existing closure-based APIs:
172 
173```swift
174// Original closure-based API
175@available(*, deprecated, renamed: "fetchImage(urlRequest:)", 
176           message: "Consider using the async/await alternative.")
177func fetchImage(urlRequest: URLRequest, 
178                completion: @escaping @Sendable (Result<UIImage, Error>) -> Void) {
179    // ... existing implementation
180}
181 
182// New async wrapper
183func fetchImage(urlRequest: URLRequest) async throws -> UIImage {
184    return try await withCheckedThrowingContinuation { continuation in
185        fetchImage(urlRequest: urlRequest) { result in
186            continuation.resume(with: result)
187        }
188    }
189}
190```
191 
192**Benefits**:
193- Colleagues can start using async/await immediately
194- You can migrate callers before rewriting implementation
195- Tests can be updated to async/await first
196 
197**Tip**: Use Xcode's **Refactor → Add Async Wrapper** to generate these automatically.
198 
199### 4. Change Default Actor Isolation (Swift 6.2+)
200 
201For app projects, set default isolation to `@MainActor`:
202 
203**Xcode Build Settings**:
204```
205Swift Concurrency → Default Actor Isolation = MainActor
206```
207 
208**Swift Package Manager**:
209```swift
210.target(
211    name: "MyTarget",
212    swiftSettings: [
213        .defaultIsolation(MainActor.self)
214    ]
215)
216```
217 
218This drastically reduces warnings in app code where most types need main thread access.
219 
220### 5. Enable Strict Concurrency Checking
221 
222**Xcode Build Settings**: Search for "Strict Concurrency Checking"
223 
224Three levels available:
225 
226- **Minimal**: Only checks code that explicitly adopts concurrency (`@Sendable`, `@MainActor`)
227- **Targeted**: Checks all code that adopts concurrency, including `Sendable` conformances
228- **Complete**: Checks entire codebase (matches Swift 6 behavior)
229 
230**Swift Package Manager**:
231```swift
232.target(
233    name: "MyTarget",
234    swiftSettings: [
235        .enableExperimentalFeature("StrictConcurrency=targeted")
236    ]
237)
238```
239 
240**Strategy**: Start with Minimal → Targeted → Complete, fixing errors at each level.
241 
242### 6. Add Sendable Conformances
243 
244Even if the compiler doesn't complain, add `Sendable` to types that will cross isolation domains:
245 
246```swift
247// ✅ Prepare for future use
248struct Configuration: Sendable {
249    let apiKey: String
250    let timeout: TimeInterval
251}
252```
253 
254This prevents warnings when the type is used in concurrent contexts later.
255 
256### 7. Enable Approachable Concurrency (Swift 6.2+)
257 
258**Xcode Build Settings**: Search for "Approachable Concurrency"
259 
260Enables multiple upcoming features at once:
261- `DisableOutwardActorInference`
262- `GlobalActorIsolatedTypesUsability`
263- `InferIsolatedConformances`
264- `InferSendableFromCaptures`
265- `NonisolatedNonsendingByDefault`
266 
267**⚠️ Warning**: Don't just flip this switch for existing projects. Use migration tooling (see below) to migrate to each feature individually first.
268 
269> **Course Deep Dive**: This topic is covered in detail in [Lesson 12.5: The Approachable Concurrency build setting (Updated for Swift 6.2)](https://www.swiftconcurrencycourse.com?utm_source=github&utm_medium=agent-skill&utm_campaign=lesson-reference)
270 
271### 8. Enable Upcoming Features
272 
273**Xcode Build Settings**: Search for "Upcoming Feature"
274 
275Enable features individually:
276 
277**Swift Package Manager**:
278```swift
279.target(
280    name: "MyTarget",
281    swiftSettings: [
282        .enableUpcomingFeature("ExistentialAny"),
283        .enableUpcomingFeature("InferIsolatedConformances")
284    ]
285)
286```
287 
288Find feature keys in Swift Evolution proposals (e.g., SE-335 for `ExistentialAny`).
289 
290### 9. Change to Swift 6 Language Mode
291 
292**Xcode Build Settings**:
293```
294Swift Language Version = Swift 6
295```
296 
297**Swift Package Manager**:
298```swift
299// swift-tools-version: 6.0
300```
301 
302If you've completed all previous steps, you should have minimal new errors.
303 
304> **Course Deep Dive**: This topic is covered in detail in [Lesson 12.4: Steps to migrate existing code to Swift 6 and Strict Concurrency Checking](https://www.swiftconcurrencycourse.com?utm_source=github&utm_medium=agent-skill&utm_campaign=lesson-reference)
305 
306---
307 
308## Migration Tooling for Upcoming Features
309 
310Swift 6.2+ includes **semi-automatic migration** for upcoming features.
311 
312### Xcode Migration
313 
3141. Go to Build Settings → Find the upcoming feature (e.g., "Require Existential any")
3152. Set to **Migrate** (temporary setting)
3163. Build the project
3174. Warnings appear with **Apply** buttons
3185. Click Apply for each warning
319 
320**Example warning**:
321```swift
322// ⚠️ Use of protocol 'Error' as a type must be written 'any Error'
323func fetchData() throws -> Data  // Before
324func fetchData() throws -> any Data  // After applying fix
325```
326 
327### Package Migration
328 
329Use the `swift package migrate` command:
330 
331```bash
332# Migrate all targets
333swift package migrate --to-feature ExistentialAny
334 
335# Migrate specific target
336swift package migrate --target MyTarget --to-feature ExistentialAny
337```
338 
339**Output**:
340```
341> Applied 24 fix-its in 11 files (0.016s)
342> Updating manifest
343```
344 
345The tool automatically:
346- Applies all fix-its
347- Updates `Package.swift` to enable the feature
348 
349**Available migrations** (as of Swift 6.2):
350- `ExistentialAny` (SE-335)
351- `InferIsolatedConformances` (SE-470)
352- More features will add migration support over time
353 
354> **Course Deep Dive**: This topic is covered in detail in [Lesson 12.6: Migration tooling for upcoming Swift features](https://www.swiftconcurrencycourse.com?utm_source=github&utm_medium=agent-skill&utm_campaign=lesson-reference)
355 
356**Additional resource**: [Migration Tooling Video](https://youtu.be/FK9XFxSWZPg?si=2z_ybn1t1YCJow5k)
357 
358---
359 
360## Rewriting Closures to Async/Await
361 
362### Using Xcode Refactoring
363 
364Three refactoring options available:
365 
3661. **Add Async Wrapper**: Wraps existing closure-based method (recommended first step)
3672. **Add Async Alternative**: Rewrites method as async, keeps original
3683. **Convert Function to Async**: Replaces method entirely
369 
370**⚠️ Known Issue**: Refactoring can be unstable in Xcode. If you get "Connection interrupted" errors:
371- Clean build folder
372- Clear derived data
373- Restart Xcode
374- Simplify complex methods (shorthand if statements can cause failures)
375 
376### Manual Rewriting Example
377 
378**Before** (closure-based):
379```swift
380func fetchImage(urlRequest: URLRequest, 
381                completion: @escaping @Sendable (Result<UIImage, Error>) -> Void) {
382    URLSession.shared.dataTask(with: urlRequest) { data, _, error in
383        do {
384            if let error = error { throw error }
385            guard let data = data, let image = UIImage(data: data) else {
386                throw ImageError.conversionFailed
387            }
388            completion(.success(image))
389        } catch {
390            completion(.failure(error))
391        }
392    }.resume()
393}
394```
395 
396**After** (async/await):
397```swift
398func fetchImage(urlRequest: URLRequest) async throws -> UIImage {
399    let (data, _) = try await URLSession.shared.data(for: urlRequest)
400    guard let image = UIImage(data: data) else {
401        throw ImageError.conversionFailed
402    }
403    return image
404}
405```
406 
407**Benefits**:
408- Less code to maintain
409- Easier to reason about
410- No nested closures
411- Automatic error propagation
412 
413> **Course Deep Dive**: This topic is covered in detail in [Lesson 12.7: Techniques for rewriting closures to async/await syntax](https://www.swiftconcurrencycourse.com?utm_source=github&utm_medium=agent-skill&utm_campaign=lesson-reference)
414 
415---
416 
417## Using @preconcurrency
418 
419Suppresses `Sendable` warnings from modules you don't control.
420 
421### When to Use
422 
423```swift
424// ⚠️ Third-party library doesn't support Swift Concurrency yet
425@preconcurrency import SomeThirdPartyLibrary
426 
427actor DataProcessor {
428    func process(_ data: LibraryType) {  // No Sendable warning
429        // ...
430    }
431}
432```
433 
434### Risks
435 
436- **No compile-time safety**: You're responsible for ensuring thread safety
437- **Hides real issues**: Library might not be thread-safe at all
438- **Technical debt**: Easy to forget to revisit later
439 
440### Best Practices
441 
4421. **Don't use by default**: Only add when compiler suggests it
4432. **Check for updates first**: Library might have a newer version with concurrency support
4443. **Document why**: Add a comment explaining why it's needed
4454. **Revisit regularly**: Set reminders to check if library has been updated
446 
447```swift
448// TODO: Remove @preconcurrency when SomeLibrary adds Sendable support
449// Last checked: 2026-01-07 (version 2.3.0)
450@preconcurrency import SomeLibrary
451```
452 
453The compiler will warn if `@preconcurrency` is unused:
454```
455'@preconcurrency' attribute on module 'SomeModule' is unused
456```
457 
458> **Course Deep Dive**: This topic is covered in detail in [Lesson 12.8: How and when to use @preconcurrency](https://www.swiftconcurrencycourse.com?utm_source=github&utm_medium=agent-skill&utm_campaign=lesson-reference)
459 
460---
461 
462## Migrating from Combine/RxSwift
463 
464### Observation Alternative
465 
466Swift 6 will include **Transactional Observation** (SE-475):
467 
468```swift
469// Future API (not yet implemented)
470let names = Observations { person.name }
471 
472Task.detached {
473    for await name in names {
474        print("Name updated to: \(name)")
475    }
476}
477```
478 
479**Current alternatives**:
480- Use `@Observable` macro for SwiftUI
481- Use `AsyncStream` for custom observation
482- Consider [AsyncExtensions](https://github.com/sideeffect-io/AsyncExtensions) package
483 
484### Debouncing Example
485 
486**Combine**:
487```swift
488$searchQuery
489    .debounce(for: .milliseconds(500), scheduler: DispatchQueue.main)
490    .sink { [weak self] query in
491        self?.performSearch(query)
492    }
493    .store(in: &cancellables)
494```
495 
496**Swift Concurrency**:
497```swift
498func search(_ query: String) {
499    currentSearchTask?.cancel()
500    
501    currentSearchTask = Task {
502        do {
503            try await Task.sleep(for: .milliseconds(500))
504            performSearch(query)
505        } catch {
506            // Search was cancelled
507        }
508    }
509}
510```
511 
512**SwiftUI Integration**:
513```swift
514struct SearchView: View {
515    @State private var searchQuery = ""
516    @State private var searcher = ArticleSearcher()
517    
518    var body: some View {
519        List(searcher.results) { result in
520            Text(result.title)
521        }
522        .searchable(text: $searchQuery)
523        .onChange(of: searchQuery) { _, newValue in
524            searcher.search(newValue)
525        }
526    }
527}
528```
529 
530### Mindset Shift
531 
532**Don't think in Combine pipelines**. Many problems are simpler without FRP:
533 
534```swift
535// ❌ Looking for AsyncSequence equivalent of complex Combine pipeline
536somePublisher
537    .debounce(for: .seconds(0.5))
538    .removeDuplicates()
539    .flatMap { ... }
540    .sink { ... }
541 
542// ✅ Rethink the problem with Swift Concurrency
543Task {
544    var lastValue: String?
545    for await value in stream {
546        guard value != lastValue else { continue }
547        lastValue = value
548        try await Task.sleep(for: .seconds(0.5))
549        await process(value)
550    }
551}
552```
553 
554**For complex operators**: Check [Swift Async Algorithms](https://github.com/apple/swift-async-algorithms) package.
555 
556### ⚠️ Critical: Actor Isolation with Combine
557 
558**Problem**: `sink` closures don't respect actor isolation at compile time.
559 
560```swift
561@MainActor
562final class NotificationObserver {
563    private var cancellables: [AnyCancellable] = []
564    
565    init() {
566        NotificationCenter.default.publisher(for: .someNotification)
567            .sink { [weak self] _ in
568                self?.handleNotification()  // ⚠️ May crash if posted from background
569            }
570            .store(in: &cancellables)
571    }
572    
573    private func handleNotification() {
574        // Expects to run on main actor
575    }
576}
577```
578 
579**Why it crashes**: Notification observers run on the same thread as the poster. If posted from a background thread, the `@MainActor` method is called off the main actor.
580 
581**Solutions**:
582 
5831. **Migrate to Swift Concurrency** (recommended):
584```swift
585Task { [weak self] in
586    for await _ in NotificationCenter.default.notifications(named: .someNotification) {
587        await self?.handleNotification()  // ✅ Compile-time safe
588    }
589}
590```
591 
5922. **Use Task wrapper** (temporary):
593```swift
594.sink { [weak self] _ in
595    Task { @MainActor in
596        self?.handleNotification()
597    }
598}
599```
600 
601> **Course Deep Dive**: This topic is covered in detail in [Lesson 12.9: Migrating away from Functional Reactive Programming like RxSwift or Combine](https://www.swiftconcurrencycourse.com?utm_source=github&utm_medium=agent-skill&utm_campaign=lesson-reference)
602 
603---
604 
605## When to Use AsyncAlgorithms
606 
607When migrating from Combine or RxSwift, you have multiple options for handling asynchronous patterns:
608 
609### Use AsyncAlgorithms for:
610 
611- **Time-based operations**: debounce, throttle, timers
612- **Combining multiple async sequences**: merge, combineLatest, zip
613- **Multi-consumer scenarios**: AsyncChannel for backpressure
614- **Complex operator chains**: FRP-like patterns in Swift Concurrency
615- **Specific operators**: removeDuplicates, chunks, adjacentPairs, compacted
616 
617### Use Standard Library for:
618 
619- **Bridging callbacks**: AsyncStream is sufficient
620- **Simple iteration**: for await in sequence
621- **Single-value operations**: async/await
622- **Basic transformations**: map, filter, contains
623 
624### Use SwiftUI for:
625 
626- **UI observation**: @Observable macro
627- **State management**: @State, @Published properties
628- **User interactions**: onChange, onReceive modifiers
629 
630> **See**: [async-algorithms.md](async-algorithms.md) for detailed AsyncAlgorithms usage examples.
631 
632---
633 
634## Real-World Migration Examples
635 
636### Example: ArticleSearcher with AsyncAlgorithms
637 
638**Before: Manual Debouncing**
639 
640```swift
641final class ArticleSearcher {
642    @MainActor private(set) var results: [Article] = []
643    private var currentSearchTask: Task<Void, Never>?
644 
645    func search(_ query: String) {
646        currentSearchTask?.cancel()
647 
648        currentSearchTask = Task {
649            do {
650                try await Task.sleep(for: .milliseconds(500))
651                await MainActor.run {
652                    self.results = []
653                }
654                self.results = await APIClient.searchArticles(query)
655            } catch {
656                // Search was cancelled
657            }
658        }
659    }
660}
661 
662// SwiftUI integration
663struct SearchView: View {
664    @State private var searchQuery = ""
665    @State private var searcher = ArticleSearcher()
666 
667    var body: some View {
668        List(searcher.results) { result in
669            Text(result.title)
670        }
671        .searchable(text: $searchQuery)
672        .onChange(of: searchQuery) { _, newValue in
673            searcher.search(newValue)
674        }
675    }
676}
677```
678 
679**After: AsyncAlgorithms Debounce**
680 
681```swift
682import AsyncAlgorithms
683 
684@Observable
685final class ArticleSearcher {
686    @MainActor private(set) var results: [Article] = []
687    private var searchQueryContinuation: AsyncStream<String>.Continuation?
688 
689    private lazy var searchQueryStream: AsyncStream<String> = {
690        AsyncStream { continuation in
691            searchQueryContinuation = continuation
692        }
693    }()
694 
695    func search(_ query: String) {
696        searchQueryContinuation?.yield(query)
697    }
698 
699    func startDebouncedSearch() {
700        Task { @MainActor in
701            for await query in searchQueryStream.debounce(for: .milliseconds(500)) {
702                self.results = []
703                self.results = await APIClient.searchArticles(query)
704            }
705        }
706    }
707}
708 
709// SwiftUI integration
710struct SearchView: View {
711    @State private var searchQuery = ""
712    @State private var searcher = ArticleSearcher()
713 
714    var body: some View {
715        List(searcher.results) { result in
716            Text(result.title)
717        }
718        .searchable(text: $searchQuery)
719        .onChange(of: searchQuery) { _, newValue in
720            searcher.search(newValue)
721        }
722        .onAppear {
723            searcher.startDebouncedSearch()
724        }
725    }
726}
727```
728 
729**Benefits of using AsyncAlgorithms**:
730- Automatic cancellation when new values arrive
731- Backpressure handling (producer respects consumer pace)
732- Cleaner code than manual Task.sleep management
733- No need to track and cancel tasks manually
734 
735### Example: Notification Stream Migration
736 
737**Before: Combine Publisher**
738 
739```swift
740import Combine
741 
742final class NotificationObserver: ObservableObject {
743    @Published private(set) var notifications: [AppNotification] = []
744    private var cancellables = Set<AnyCancellable>()
745 
746    init() {
747        NotificationCenter.default.publisher(for: UIApplication.didBecomeActiveNotification)
748            .compactMap { notification in
749                notification.object as? AppNotification
750            }
751            .receive(on: DispatchQueue.main)
752            .assign(to: &$notifications)
753    }
754}
755```
756 
757**After: Standard Library Notifications**
758 
759```swift
760@Observable
761final class NotificationObserver {
762    @MainActor private(set) var notifications: [AppNotification] = []
763 
764    func startObserving() {
765        Task {
766            for await notification in NotificationCenter.default.notifications(named: UIApplication.didBecomeActiveNotification) {
767                if let appNotification = notification.object as? AppNotification {
768                    notifications.append(appNotification)
769                }
770            }
771        }
772    }
773}
774```
775 
776**When to use each approach**:
777- Use `notifications(named:)` for standard system notifications
778- Use `AsyncChannel` for custom multi-consumer notification scenarios
779- Use `@Observable` + SwiftUI for UI state updates
780 
781### Example: Multi-Source Data Loading
782 
783**Before: Combine Merge**
784 
785```swift
786import Combine
787 
788final class MultiSourceLoader: ObservableObject {
789    @Published private(set) var items: [Item] = []
790    private var cancellables = Set<AnyCancellable>()
791 
792    func loadFromAllSources() {
793        let source1 = APIClient.fetchItems(from: .source1)
794        let source2 = APIClient.fetchItems(from: .source2)
795        let source3 = APIClient.fetchItems(from: .source3)
796 
797        Publishers.Merge3(source1, source2, source3)
798            .flatMap { items in
799                Just(items)
800                    .delay(for: .seconds(0.1), scheduler: DispatchQueue.main)
801            }
802            .scan([]) { accumulated, new in
803                accumulated + new
804            }
805            .receive(on: DispatchQueue.main)
806            .assign(to: &$items)
807            .store(in: &cancellables)
808    }
809}
810```
811 
812**After: AsyncAlgorithms Merge + TaskGroup**
813 
814```swift
815import AsyncAlgorithms
816 
817@Observable
818final class MultiSourceLoader {
819    @MainActor private(set) var items: [Item] = []
820 
821    func loadFromAllSources() async {
822        let sources = [
823            APIClient.fetchItems(from: .source1),
824            APIClient.fetchItems(from: .source2),
825            APIClient.fetchItems(from: .source3)
826        ]
827 
828        Task { @MainActor in
829            for await stream in sources.map { $0.values }.merge() {
830                for await newItems in stream {
831                    self.items.append(contentsOf: newItems)
832                }
833            }
834        }
835    }
836 
837    // Alternative: Using TaskGroup for parallel execution
838    func loadFromAllSourcesParallel() async {
839        await withTaskGroup(of: [Item].self) { group in
840            group.addTask {
841                await APIClient.fetchItems(from: .source1)
842            }
843            group.addTask {
844                await APIClient.fetchItems(from: .source2)
845            }
846            group.addTask {
847                await APIClient.fetchItems(from: .source3)
848            }
849 
850            for await newItems in group {
851                await MainActor.run {
852                    self.items.append(contentsOf: newItems)
853                }
854            }
855        }
856    }
857}
858```
859 
860**Key differences**:
861- Combine `merge()` combines publishers; AsyncAlgorithms `merge()` combines sequences
862- For parallel execution, use `TaskGroup` instead of `flatMap`
863- State updates can use `@MainActor` instead of `.receive(on:)`
864 
865---
866 
867## Anti-Patterns to Avoid
868 
869### ❌ Don't Use Task.sleep for Debouncing
870 
871```swift
872// ❌ Bad: Manual debouncing without backpressure
873func search(_ query: String) {
874    Task {
875        try? await Task.sleep(for: .milliseconds(500))
876        await performSearch(query)
877    }
878}
879```
880 
881**Problem**: Every keystroke spawns a new task. If user types fast, multiple tasks execute simultaneously after 500ms, causing out-of-order results and wasted API calls.
882 
883**Solution**: Use `debounce()` from AsyncAlgorithms for automatic backpressure and cancellation.
884 
885### ❌ Don't Manually Combine Values
886 
887```swift
888// ❌ Bad: Manual combination without operator
889actor FormValidator {
890    private var currentUsername: String = ""
891    private var currentEmail: String = ""
892    private var currentPassword: String = ""
893 
894    func updateUsername(_ username: String) {
895        currentUsername = username
896        checkForm()
897    }
898 
899    func updateEmail(_ email: String) {
900        currentEmail = email
901        checkForm()
902    }
903 
904    func updatePassword(_ password: String) {
905        currentPassword = password
906        checkForm()
907    }
908 
909    private func checkForm() {
910        let state = validate(
911            username: currentUsername,
912            email: currentEmail,
913            password: currentPassword
914        )
915        // Update UI or emit validation state
916    }
917}
918```
919 
920**Problems**:
921- More state management
922- Boilerplate code for each field
923- Harder to add new fields
924- No stream composition benefits
925 
926**Solution**: Use `combineLatest()` for cleaner, composable validation.
927 
928### ❌ Don't Share Streams Without AsyncChannel
929 
930```swift
931// ❌ Bad: Multiple consumers sharing same stream
932let stream = AsyncStream<Int> { continuation in
933    for i in 1...10 {
934        continuation.yield(i)
935    }
936    continuation.finish()
937}
938 
939Task {
940    for await value in stream {
941        print("Consumer 1: \(value)")
942    }
943}
944 
945Task {
946    for await value in stream {
947        print("Consumer 2: \(value)")
948    }
949}
950```
951 
952**Problem**: Values are split between consumers unpredictably. Each value goes to only one consumer.
953 
954**Solution**: Use `AsyncChannel` for true multi-consumer scenarios with backpressure.
955 
956---
957 
958---
959 
960## Concurrency-Safe Notifications (iOS 26+)
961 
962Swift 6.2 introduces **typed, thread-safe notifications**.
963 
964### MainActorMessage
965 
966For notifications that should be delivered on the main actor:
967 
968```swift
969// Old way
970NotificationCenter.default.addObserver(
971    forName: UIApplication.didBecomeActiveNotification,
972    object: nil,
973    queue: .main
974) { [weak self] _ in
975    self?.handleDidBecomeActive()  // ⚠️ Concurrency warning
976}
977 
978// New way (iOS 26+)
979token = NotificationCenter.default.addObserver(
980    of: UIApplication.self,
981    for: .didBecomeActive
982) { [weak self] message in
983    self?.handleDidBecomeActive()  // ✅ No warning, guaranteed main actor
984}
985```
986 
987**Key difference**: Observer closure is guaranteed to run on `@MainActor`.
988 
989### AsyncMessage
990 
991For notifications delivered asynchronously on arbitrary isolation:
992 
993```swift
994struct RecentBuildsChangedMessage: NotificationCenter.AsyncMessage {
995    typealias Subject = [RecentBuild]
996    let recentBuilds: Subject
997}
998 
999// Enable static member lookup
1000extension NotificationCenter.MessageIdentifier 
1001where Self == NotificationCenter.BaseMessageIdentifier<RecentBuildsChangedMessage> {
1002    static var recentBuildsChanged: NotificationCenter.BaseMessageIdentifier<RecentBuildsChangedMessage> {
1003        .init()
1004    }
1005}
1006```
1007 
1008**Posting**:
1009```swift
1010let builds = [RecentBuild(appName: "Stock Analyzer")]
1011let message = RecentBuildsChangedMessage(recentBuilds: builds)
1012NotificationCenter.default.post(message)
1013```
1014 
1015**Observing**:
1016```swift
1017// Old way: Unsafe casting
1018NotificationCenter.default.addObserver(forName: .recentBuildsChanged, object: nil, queue: nil) { notification in
1019    guard let builds = notification.object as? [RecentBuild] else { return }
1020    handleBuilds(builds)
1021}
1022 
1023// New way: Strongly typed, thread-safe
1024token = NotificationCenter.default.addObserver(
1025    of: [RecentBuild].self,
1026    for: .recentBuildsChanged
1027) { message in
1028    handleBuilds(message.recentBuilds)  // ✅ Direct access, no casting
1029}
1030```
1031 
1032**Benefits**:
1033- Strongly typed (no `Any` casting)
1034- Compile-time thread safety
1035- Clear isolation guarantees
1036 
1037> **Course Deep Dive**: This topic is covered in detail in [Lesson 12.10: Migrating to concurrency-safe notifications](https://www.swiftconcurrencycourse.com?utm_source=github&utm_medium=agent-skill&utm_campaign=lesson-reference)
1038 
1039---
1040 
1041## Common Challenges
1042 
1043### "It's Too Much Work"
1044 
1045Break it down:
1046- Migrate one package at a time
1047- Use 30-minute daily sessions
1048- Create checkpoints with small PRs
1049- Celebrate incremental progress
1050 
1051### "My Team Isn't Ready"
1052 
1053Start small:
1054- Enable Swift 6 for new files only
1055- Make new types `Sendable` by default
1056- Share learnings in team meetings
1057- Pair program on tricky migrations
1058 
1059### "Dependencies Aren't Ready"
1060 
1061Options:
1062- Update to latest versions first
1063- Use `@preconcurrency` temporarily
1064- Contribute fixes to open-source dependencies
1065- Wrap third-party APIs in your own concurrency-safe layer
1066 
1067### "I Keep Going in Circles"
1068 
1069This is the "concurrency rabbit hole":
1070- Take breaks and revisit later
1071- Temporarily disable strict checking to make progress elsewhere
1072- Focus on one module at a time
1073- Don't try to fix everything at once
1074 
1075> **Course Deep Dive**: This topic is covered in detail in [Lesson 12.11: Frequently Asked Questions (FAQ) around Swift 6 Migrations](https://www.swiftconcurrencycourse.com?utm_source=github&utm_medium=agent-skill&utm_campaign=lesson-reference)
1076 
1077---
1078 
1079## Common Mistakes Agents Make
1080 
1081- **Blanket `@MainActor`**: Do not slap `@MainActor` on everything to silence errors. Ask whether the code truly needs main-actor isolation.
1082- **Mixing migration with unrelated refactors**: Focus solely on concurrency changes. Architectural improvements belong in separate PRs.
1083- **Using `@unchecked Sendable` as a first response**: Prefer immutable value types or actors. Reserve escape hatches for documented, temporary exceptions.
1084- **Giving pre-Swift 6.2 execution advice without checking the active feature set**: `nonisolated async` behavior depends on whether `NonisolatedNonsendingByDefault` is enabled.
1085- **Using Approachable Concurrency without migrating feature-by-feature first**: Enable individual upcoming features before the full bundle to understand each change's impact.
1086 
1087## Summary
1088 
1089Migration to Swift 6 is a journey, not a sprint:
1090 
10911. **Start small**: Find isolated code with minimal dependencies
10922. **Be incremental**: Use the three strict concurrency levels (Minimal → Targeted → Complete)
10933. **Use tooling**: Leverage Xcode refactoring and `swift package migrate`
10944. **Create checkpoints**: Small, focused PRs that can be merged quickly
10955. **Stay positive**: The concurrency rabbit hole is real, but manageable with the right habits
10966. **Think differently**: Let go of the threading mindset; trust the compiler
1097 
1098The result is **compile-time thread safety**, more maintainable code, and a future-proof codebase.
1099 
1100**Additional resources**:
1101- [Approachable Concurrency Video](https://youtu.be/y_Qc8cT-O_g?si=y4C1XQDGtyIOLW81)
1102- [Migration Tooling Video](https://youtu.be/FK9XFxSWZPg?si=2z_ybn1t1YCJow5k)
1103- [Swift Concurrency Course](https://www.swiftconcurrencycourse.com) for in-depth migration strategies
1104 
1105