engsys 1.0.0

package/stacks/lang/swift/skills/swift-concurrency/references/concurrency-patterns.md

@@ -0,0 +1,233 @@
+# Concurrency Patterns
+
+Approachable concurrency patterns introduced in Swift 6.2+ — a philosophy shift where
+code stays single-threaded by default until you choose to introduce concurrency.
+
+## Contents
+
+- [Core Problem Solved](#core-problem-solved)
+- [SE-0466: Default MainActor Isolation](#se-0466-default-mainactor-isolation)
+- [SE-0461: nonisolated(nonsending)](#se-0461-nonisolatednonsending)
+- [@concurrent Attribute](#concurrent-attribute)
+- [SE-0472: Task.immediate](#se-0472-taskimmediate)
+- [Isolated Conformances](#isolated-conformances)
+- [SE-0481: weak let (Proposed)](#se-0481-weak-let-proposed--swift-62)
+- [SE-0475: Transactional Observation (Observations)](#se-0475-transactional-observation-observations)
+- [Global and Static State](#global-and-static-state)
+- [Migration and Build Settings](#migration-and-build-settings)
+- [Summary](#summary)
+
+## Core Problem Solved
+
+In Swift 6.0/6.1, data-race safety was enforced at compile time, but the most
+natural code to write often produced data-race errors. Async functions on types
+with mutable state would implicitly hop to the global concurrent executor,
+causing send-safety violations even when no actual parallelism was intended.
+
+```swift
+// Swift 6.0/6.1: This produces a data-race error
+class PhotoProcessor {
+    func extractSticker(data: Data, with id: String?) async -> Sticker? { /* ... */ }
+}
+
+@MainActor
+final class StickerModel {
+    let photoProcessor = PhotoProcessor()
+
+    func extractSticker(_ item: PhotosPickerItem) async throws -> Sticker? {
+        guard let data = try await item.loadTransferable(type: Data.self) else { return nil }
+        // Error: Sending 'self.photoProcessor' risks causing data races
+        return await photoProcessor.extractSticker(data: data, with: item.itemIdentifier)
+    }
+}
+```
+
+```swift
+// Swift 6.2: The same code compiles without error
+// because extractSticker stays on the caller's actor
+class PhotoProcessor {
+    func extractSticker(data: Data, with id: String?) async -> Sticker? { /* ... */ }
+}
+
+@MainActor
+final class StickerModel {
+    let photoProcessor = PhotoProcessor()
+
+    func extractSticker(_ item: PhotosPickerItem) async throws -> Sticker? {
+        guard let data = try await item.loadTransferable(type: Data.self) else { return nil }
+        return await photoProcessor.extractSticker(data: data, with: item.itemIdentifier)
+    }
+}
+```
+
+## SE-0466: Default MainActor Isolation
+
+Enable with the `-default-isolation MainActor` compiler flag or the Xcode 26
+"Approachable Concurrency" build setting.
+
+**What it does:**
+- All declarations in the module are implicitly `@MainActor` unless opted out.
+- Global and static variables are protected by the main actor by default.
+- Protocol conformances are implicitly isolated to `@MainActor`.
+- Eliminates most annotation burden for single-threaded UI code.
+
+**Recommended for:** Apps, scripts, and executable targets. Not recommended for
+library targets that should remain actor-agnostic.
+
+```swift
+// With default MainActor isolation -- no @MainActor annotations needed:
+final class StickerLibrary {
+    static let shared = StickerLibrary()
+}
+
+final class StickerModel {
+    let photoProcessor = PhotoProcessor()
+    var selection: [PhotosPickerItem] = []
+}
+
+extension StickerModel: Exportable {
+    func export() { photoProcessor.exportAsPNG() }
+}
+```
+
+## SE-0461: nonisolated(nonsending)
+
+Nonisolated async functions stay on the caller's actor by default instead of
+hopping to the global concurrent executor. This is the `nonisolated(nonsending)`
+default behavior.
+
+**Key implication:** Values passed into an async function are never sent outside
+the actor, eliminating data races without annotation.
+
+To explicitly opt into background execution, use `@concurrent`.
+
+## @concurrent Attribute
+
+Ensures a function always runs on the concurrent thread pool, freeing the
+calling actor for other work.
+
+```swift
+class PhotoProcessor {
+    var cachedStickers: [String: Sticker] = [:]
+
+    func extractSticker(data: Data, with id: String) async -> Sticker {
+        if let sticker = cachedStickers[id] { return sticker }
+        let sticker = await Self.extractSubject(from: data)
+        cachedStickers[id] = sticker
+        return sticker
+    }
+
+    @concurrent
+    static func extractSubject(from data: Data) async -> Sticker { /* ... */ }
+}
+```
+
+**Steps to offload a function to background:**
+1. Ensure the containing type is `nonisolated` (or the function itself).
+2. Add `@concurrent` to the function.
+3. Add `async` if not already asynchronous.
+4. Add `await` at call sites.
+
+```swift
+nonisolated struct PhotoProcessor {
+    @concurrent
+    func process(data: Data) async -> ProcessedPhoto? { /* ... */ }
+}
+
+processedPhotos[item.id] = await PhotoProcessor().process(data: data)
+```
+
+## SE-0472: Task.immediate
+
+`Task.immediate` starts executing synchronously on the current actor before any
+suspension point, rather than being enqueued. There is also
+`Task.immediateDetached` which combines immediate start with detached semantics.
+
+```swift
+Task.immediate { await handleUserInput() }
+```
+
+Use for latency-sensitive work where enqueue delay is unacceptable.
+
+## Isolated Conformances
+
+A conformance that needs MainActor state is called an *isolated conformance*.
+The compiler ensures the conformance is only used in a matching isolation
+context.
+
+```swift
+protocol Exportable {
+    func export()
+}
+
+extension StickerModel: @MainActor Exportable {
+    func export() { photoProcessor.exportAsPNG() }
+}
+
+@MainActor
+struct ImageExporter {
+    var items: [any Exportable]
+
+    mutating func add(_ item: StickerModel) {
+        items.append(item)  // OK -- on MainActor
+    }
+}
+
+// But in a nonisolated context:
+nonisolated struct GenericExporter {
+    var items: [any Exportable]
+
+    mutating func add(_ item: StickerModel) {
+        // Error: Main actor-isolated conformance of 'StickerModel' to
+        // 'Exportable' cannot be used in nonisolated context
+        items.append(item)
+    }
+}
+```
+
+## SE-0481: weak let (Proposed — Swift 6.2+)
+
+Immutable weak references (`weak let`) enable `Sendable` conformance for types
+that hold weak references, since immutability guarantees thread safety. Proposed
+in SE-0481; may not yet be available in shipping toolchains.
+
+## SE-0475: Transactional Observation (Observations)
+
+`Observations { }` provides transactional observation of `@Observable` types
+via `AsyncSequence`.
+
+```swift
+for await _ in Observations { model.count } {
+    print("Count changed to \(model.count)")
+}
+```
+
+## Global and Static State
+
+Global and static variables are prone to data races. The most common protection
+is `@MainActor`:
+
+```swift
+@MainActor
+final class StickerLibrary {
+    static let shared = StickerLibrary()  // protected by MainActor
+}
+```
+
+With default MainActor isolation (SE-0466), this annotation is implicit.
+
+## Migration and Build Settings
+
+All approachable concurrency features are opt-in via:
+- **Xcode 26:** Swift Compiler > Concurrency section in build settings.
+- **SwiftPM:** `swiftSettings` in Package.swift using the `SwiftSetting` API.
+
+Swift 6.2 includes migration tooling to help make necessary code changes
+automatically. See swift.org/migration for details.
+
+## Summary
+
+The Swift 6.2 concurrency progression:
+1. Start with code that runs on the main actor by default (no data race risk).
+2. Async functions run wherever they are called from (still no data race risk).
+3. When you need performance, offload specific code with `@concurrent`.

package/stacks/lang/swift/skills/swift-concurrency/references/swiftui-concurrency.md

@@ -0,0 +1,187 @@
+# SwiftUI Concurrency Guide
+
+Concurrency patterns and best practices specific to SwiftUI applications.
+
+## Contents
+
+- [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)
+
+## MainActor Default in SwiftUI
+
+- `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.
+
+## Where SwiftUI Runs Code Off the Main Thread
+
+SwiftUI may evaluate some view logic on background threads for performance:
+
+- `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.
+
+```swift
+// WRONG: Captures @MainActor state directly
+.visualEffect { content, proxy in
+    content.offset(y: self.offset)  // Error: @MainActor state in Sendable closure
+}
+
+// CORRECT: Capture a copy
+let currentOffset = offset
+// ... use in closure:
+.visualEffect { [currentOffset] content, proxy in
+    content.offset(y: currentOffset)
+}
+```
+
+Avoid sending `self` into a `Sendable` closure just to read a single property.
+
+## Structuring Async Work
+
+SwiftUI action callbacks are synchronous so UI updates (like loading states) can
+be immediate.
+
+```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
+            }
+        }
+    }
+}
+```
+
+**Pattern:** Use state as the boundary. Async work updates model/state; UI
+reacts synchronously.
+
+## The .task Modifier
+
+Prefer `.task` over manual `Task` creation in views:
+
+```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.
+
+Use `.task(id:)` to restart work when a value changes:
+
+```swift
+.task(id: selectedItem) {
+    details = await fetchDetails(for: selectedItem)
+}
+```
+
+## @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.
+
+```swift
+@Observable @MainActor
+final class ViewModel {
+    var items: [Item] = []
+    var isLoading = false
+
+    func load() async {
+        isLoading = true
+        items = await fetchItems()
+        isLoading = false
+    }
+}
+
+struct ItemListView: View {
+    @State private var viewModel = ViewModel()
+
+    var body: some View {
+        List(viewModel.items) { item in
+            Text(item.name)
+        }
+        .task { await viewModel.load() }
+    }
+}
+```
+
+## Async Observation with Observations (SE-0475)
+
+Use `Observations { }` for transactional async observation:
+
+```swift
+.task {
+    for await _ in Observations { viewModel.searchText } {
+        await viewModel.performSearch()
+    }
+}
+```
+
+## Performance-Driven Concurrency
+
+- 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.
+
+```swift
+@Observable @MainActor
+final class ImageProcessor {
+    var processedImage: UIImage?
+
+    func process(data: Data) async {
+        // Offload heavy work
+        let result = await Self.runProcessing(data: data)
+        processedImage = result
+    }
+
+    @concurrent
+    nonisolated static func runProcessing(data: Data) async -> UIImage {
+        // Runs on background thread pool
+        // ...
+    }
+}
+```
+
+## 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`.