@mmerterden/multi-agent-pipeline 20.6.0 → 20.8.0

package/pipeline/skills/shared/external/swift-concurrency/references/swiftui-concurrency.md

@@ -1,187 +1,158 @@
-# SwiftUI Concurrency Guide
+# SwiftUI and Concurrency
 
-Concurrency patterns and best practices specific to SwiftUI applications.
+## Views live on the main actor
 
-## Contents
+The `View` protocol is isolated to `@MainActor` (from the iOS 18 SDK on; older
+SDKs isolated only `body`), so `body` and every other member of a view inherit
+that isolation. SE-0466 can extend the same default to every type in a module.
+This lines up with UIKit and AppKit, whose UI APIs are also `@MainActor`, and
+removes most annotations from UI code.
 
-- [MainActor Default in SwiftUI](#mainactor-default-in-swiftui)
-- [Where SwiftUI Runs Code Off the Main Thread](#where-swiftui-runs-code-off-the-main-thread)
-- [Sendable Closures and Data-Race Safety](#sendable-closures-and-data-race-safety)
-- [Structuring Async Work](#structuring-async-work)
-- [The .task Modifier](#the-task-modifier)
-- [`@Observable View Models`](#observable-view-models)
-- [Async Observation with Observations (SE-0475)](#async-observation-with-observations-se-0475)
-- [Performance-Driven Concurrency](#performance-driven-concurrency)
-- [Common SwiftUI Concurrency Mistakes](#common-swiftui-concurrency-mistakes)
+## Callbacks SwiftUI may run off the main thread
 
-## MainActor Default in SwiftUI
+Some framework hooks are called from background threads for performance:
 
-- `View` is `@MainActor` isolated by default; `body` and all members inherit
-  this isolation.
-- Swift 6.2 can infer `@MainActor` for all types in a module via default actor
-  isolation (SE-0466).
-- This default aligns with UIKit/AppKit `@MainActor` APIs and simplifies UI
-  code.
+- `Shape.path(in:)`
+- `Layout.sizeThatFits(proposal:subviews:cache:)` and
+  `Layout.placeSubviews(in:proposal:subviews:cache:)`
+- the closure passed to `visualEffect`
+- the closures passed to `onGeometryChange`
 
-## Where SwiftUI Runs Code Off the Main Thread
+Their closure parameters are often declared `Sendable` so the compiler can
+enforce that fact.
 
-SwiftUI may evaluate some view logic on background threads for performance:
+## Reading state inside a Sendable closure
 
-- `Shape` path generation
-- `Layout` methods (`sizeThatFits`, `placeSubviews`)
-- `visualEffect` closures
-- `onGeometryChange` closures
-
-These APIs often require `Sendable` closures to reflect their off-main-thread
-runtime semantics.
-
-## Sendable Closures and Data-Race Safety
-
-Accessing `@MainActor` state from a `Sendable` closure is unsafe and flagged by
-the compiler.
-
-**Fix:** Capture value copies in the closure capture list.
+Main-actor state such as a `@State` property or a property of a `@MainActor`
+model cannot be read from a `Sendable` closure, and the compiler says so (as a
+warning with the iOS 26 SDK). A plain stored `let` or `var` of a `Sendable`
+type on the view itself is exempt, because SE-0434 makes it `nonisolated`.
+Copy the value first and capture the copy:
 
 ```swift
-// WRONG: Captures @MainActor state directly
-.visualEffect { content, proxy in
-    content.offset(y: self.offset)  // Error: @MainActor state in Sendable closure
-}
+struct ParallaxCard: View {
+    @State private var depth: CGFloat = 40
 
-// CORRECT: Capture a copy
-let currentOffset = offset
-// ... use in closure:
-.visualEffect { [currentOffset] content, proxy in
-    content.offset(y: currentOffset)
+    var body: some View {
+        // warning: main actor-isolated property 'depth' can not be referenced from a Sendable closure
+        // Image("cover").visualEffect { content, _ in content.offset(y: depth) }
+
+        let capturedDepth = depth
+        return Image("cover")
+            .visualEffect { [capturedDepth] content, proxy in
+                content.offset(y: capturedDepth * proxy.size.height / 100)
+            }
+    }
 }
 ```
 
-Avoid sending `self` into a `Sendable` closure just to read a single property.
+Capturing `self` just to read one property sends the whole view into the
+closure; capture the value instead.
 
-## Structuring Async Work
+## Structuring async work
 
-SwiftUI action callbacks are synchronous so UI updates (like loading states) can
-be immediate.
+Button actions and other SwiftUI callbacks are synchronous on purpose, so
+state set in them shows on screen immediately. Flip the visible state first,
+then start the async part:
 
 ```swift
-struct ContentView: View {
-    @State private var isLoading = false
-    @State private var result: String?
-
-    var body: some View {
-        Button("Load") {
-            isLoading = true           // Immediate UI update
-            Task {
-                result = await fetchData()
-                isLoading = false
-            }
-        }
+Button("Sync") {
+    isSyncing = true
+    Task {
+        report = await syncService.run()
+        isSyncing = false
     }
 }
 ```
 
-**Pattern:** Use state as the boundary. Async work updates model/state; UI
-reacts synchronously.
+Treat state as the seam: async work writes into the model or view state, and
+the UI reacts to that state synchronously.
 
-## The .task Modifier
+## The `.task` modifier
 
-Prefer `.task` over manual `Task` creation in views:
+Prefer `.task` to creating `Task` values inside a view:
 
-```swift
-.task {
-    await loadInitialData()
-}
-```
-
-**Advantages:**
-- Automatically cancels on view disappear.
-- Inherits the view's actor isolation (`@MainActor`).
-- No need to store `Task` references for cancellation.
+- it is cancelled automatically when the view disappears,
+- it runs with the view's `@MainActor` isolation,
+- nothing needs to be stored to cancel it later.
 
-Use `.task(id:)` to restart work when a value changes:
+`.task(id:)` cancels and restarts its work whenever the id changes:
 
 ```swift
-.task(id: selectedItem) {
-    details = await fetchDetails(for: selectedItem)
+.task(id: selectedRoute) {
+    guard let selectedRoute else { return }
+    stops = await transit.stops(on: selectedRoute)
 }
 ```
 
-## `@Observable` View Models
+## Observable view models
 
-- Annotate view models with both `@Observable` and `@MainActor`.
-- Use `@State` to own an `@Observable` instance (replaces `@StateObject`).
-- Avoid `@ObservedObject` / `@StateObject` / `ObservableObject` in new code.
+Mark view models `@Observable` and `@MainActor`, own them with `@State`, and
+leave `ObservableObject`, `@StateObject` and `@ObservedObject` out of new code
+that targets iOS 17 or later.
 
 ```swift
 @Observable @MainActor
-final class ViewModel {
-    var items: [Item] = []
+final class InboxModel {
+    var threads: [MailThread] = []
     var isLoading = false
 
-    func load() async {
+    func refresh() async {
         isLoading = true
-        items = await fetchItems()
-        isLoading = false
+        defer { isLoading = false }
+        threads = await mailbox.latestThreads()
     }
 }
 
-struct ItemListView: View {
-    @State private var viewModel = ViewModel()
+struct InboxView: View {
+    @State private var model = InboxModel()
 
     var body: some View {
-        List(viewModel.items) { item in
-            Text(item.name)
-        }
-        .task { await viewModel.load() }
+        List(model.threads) { Text($0.subject) }
+            .task { await model.refresh() }
     }
 }
 ```
 
-## Async Observation with Observations (SE-0475)
-
-Use `Observations { }` for transactional async observation:
+## Reacting to model changes with Observations
 
 ```swift
 .task {
-    for await _ in Observations { viewModel.searchText } {
-        await viewModel.performSearch()
+    for await query in Observations({ model.query }) {
+        await model.runSearch(query)
     }
 }
 ```
 
-## Performance-Driven Concurrency
+## Concurrency for performance
 
-- Offload expensive work from the main actor to avoid hitches.
-- Keep time-sensitive UI logic (animations, gesture responses) synchronous.
-- Separate UI code from long-running async work.
+- Move expensive work off the main actor so frames are not dropped.
+- Keep timing-sensitive UI logic such as animations and gesture handling
+  synchronous.
+- Keep long-running async work in separate types from view code.
 
 ```swift
 @Observable @MainActor
-final class ImageProcessor {
-    var processedImage: UIImage?
+final class PosterModel {
+    var poster: UIImage?
 
-    func process(data: Data) async {
-        // Offload heavy work
-        let result = await Self.runProcessing(data: data)
-        processedImage = result
+    func load(from data: Data) async {
+        poster = await Self.render(data)
     }
 
     @concurrent
-    nonisolated static func runProcessing(data: Data) async -> UIImage {
-        // Runs on background thread pool
-        // ...
+    nonisolated static func render(_ data: Data) async -> UIImage? {
+        UIImage(data: data)?.preparingForDisplay()
     }
 }
 ```
 
-## Common SwiftUI Concurrency Mistakes
-
-1. **Creating `Task` in `body`.** Use `.task` modifier instead.
-2. **Not cancelling tasks.** `.task` does this automatically; manual `Task`
-   references must be cancelled in `onDisappear`.
-3. **Blocking MainActor in view updates.** Move heavy computation to
-   `@concurrent` functions.
-4. **Using `Task.detached` in views.** Loses actor context. Use `Task { }` or
-   `.task` modifier.
-5. **Updating state from background.** Always update `@State` / `@Observable`
-   properties on `@MainActor`.
+## Mistakes
+
+| Mistake | Fix |
+|---|---|
+| `Task { }` created inside `body` | Use `.task` |
+| Manual tasks never cancelled | Use `.task`, or cancel stored handles in `onDisappear` |
+| Heavy work blocks the main actor during updates | Move it into a `@concurrent` function |
+| `Task.detached` inside a view drops the main actor | Use `Task { }` or `.task` |
+| `@State` or `@Observable` properties written off the main actor | Write them only from `@MainActor` code |