buildanything 1.7.1 → 2.0.0

package/skills/ios/swift-concurrency/references/threading.md

@@ -0,0 +1,495 @@
+# Threading
+
+Use this when:
+
+- You need to understand the relationship between tasks and threads.
+- You are debugging suspension points, actor reentrancy, or unexpected execution contexts.
+- You need Swift 6.2 behavior guidance (`nonisolated async`, `@concurrent`, `nonisolated(nonsending)`).
+
+Skip this file if:
+
+- You mainly need to protect mutable state. Use `actors.md`.
+- You need to make types safe to transfer. Use `sendable.md`.
+
+Jump to:
+
+- Core Concepts (Tasks vs Threads)
+- Cooperative Thread Pool
+- Suspension Points and Actor Reentrancy
+- Swift 6.2 Changes (SE-461, SE-466)
+- Default Isolation Domain
+- Debugging Thread Execution
+- Common Misconceptions
+- Migration Strategy
+
+## Core Concepts
+
+### What is a Thread?
+
+System-level resource that runs instructions. High overhead for creation and switching. Swift Concurrency abstracts thread management away.
+
+### Tasks vs Threads
+
+**Tasks** are units of async work, not tied to specific threads. Swift dynamically schedules tasks on available threads from a cooperative pool.
+
+**Key insight**: No direct relationship between one task and one thread.
+
+> **Course Deep Dive**: This topic is covered in detail in [Lesson 7.1: How Threads relate to Tasks](https://www.swiftconcurrencycourse.com?utm_source=github&utm_medium=agent-skill&utm_campaign=lesson-reference)
+
+**Important (Swift 6+)**: Avoid using `Thread.current` inside async contexts. In Swift 6 language mode, `Thread.current` is unavailable from asynchronous contexts and will fail to compile. Prefer reasoning in terms of isolation domains; use Instruments and the debugger to observe execution when needed.
+
+## Cooperative Thread Pool
+
+Swift creates only as many threads as CPU cores. Tasks share these threads efficiently.
+
+### How it works
+
+1. **Limited threads**: Number matches CPU cores
+2. **Task scheduling**: Tasks scheduled onto available threads
+3. **Suspension**: At `await`, task suspends, thread freed for other work
+4. **Resumption**: Task resumes on any available thread (not necessarily the same one)
+
+```swift
+func example() async {
+    print("Started on: \(Thread.current)")
+    
+    try await Task.sleep(for: .seconds(1))
+    
+    print("Resumed on: \(Thread.current)") // Likely different thread
+}
+```
+
+### Benefits over GCD
+
+**Prevents thread explosion**:
+- No excessive thread creation
+- No high memory overhead from idle threads
+- No excessive context switching
+- No priority inversion
+
+**Better performance**:
+- Fewer threads = less context switching
+- Continuations instead of blocking
+- CPU cores stay busy efficiently
+
+## Threading Mindset → Isolation Mindset
+
+### Old way (GCD)
+
+```swift
+// Thinking about threads
+DispatchQueue.main.async {
+    // Update UI on main thread
+}
+
+DispatchQueue.global(qos: .background).async {
+    // Heavy work on background thread
+}
+```
+
+### New way (Swift Concurrency)
+
+```swift
+// Thinking about isolation domains
+@MainActor
+func updateUI() {
+    // Runs on main actor (usually main thread)
+}
+
+func heavyWork() async {
+    // Runs on any available thread in pool
+}
+```
+
+### Think in isolation domains
+
+**Don't ask**: "What thread should this run on?"
+
+**Ask**: "What isolation domain should own this work?"
+
+- `@MainActor` for UI updates
+- Custom actors for specific state
+- Nonisolated for general async work
+
+### Provide hints, not commands
+
+```swift
+Task(priority: .userInitiated) {
+    await doWork()
+}
+```
+
+You're describing the nature of work, not assigning threads. Swift optimizes execution.
+
+> **Course Deep Dive**: This topic is covered in detail in [Lesson 7.2: Getting rid of the "Threading Mindset"](https://www.swiftconcurrencycourse.com?utm_source=github&utm_medium=agent-skill&utm_campaign=lesson-reference)
+
+## Suspension Points
+
+### What is a suspension point?
+
+Moment where task **may** pause to allow other work. Marked by `await`.
+
+```swift
+let data = await fetchData() // Potential suspension
+```
+
+**Critical**: `await` marks *possible* suspension, not guaranteed. If operation completes synchronously, no suspension occurs.
+
+### Why suspension points matter
+
+1. **Code may pause unexpectedly** - resumes later, possibly different thread
+2. **State can change** - mutable state may be modified during suspension
+3. **Actor reentrancy** - other tasks can access actor during suspension
+
+### Actor reentrancy example
+
+```swift
+actor BankAccount {
+    private var balance: Int = 0
+    
+    func deposit(amount: Int) async {
+        balance += amount
+        print("Balance: \(balance)")
+        
+        await logTransaction(amount) // ⚠️ Suspension point
+        
+        balance += 10 // Bonus
+        print("After bonus: \(balance)")
+    }
+    
+    func logTransaction(_ amount: Int) async {
+        try? await Task.sleep(for: .seconds(1))
+    }
+}
+
+// Two concurrent deposits
+async let _ = account.deposit(amount: 100)
+async let _ = account.deposit(amount: 100)
+
+// Unexpected: 100 → 200 → 210 → 220
+// Expected:   100 → 110 → 210 → 220
+```
+
+**Why**: During `logTransaction`, second deposit runs, modifying balance before first completes.
+
+### Avoiding reentrancy bugs
+
+**Complete actor work before suspending**:
+
+```swift
+func deposit(amount: Int) async {
+    balance += amount
+    balance += 10 // Bonus applied first
+    print("Final balance: \(balance)")
+    
+    await logTransaction(amount) // Suspend after state changes
+}
+```
+
+**Rule**: Don't mutate actor state after suspension points.
+
+> **Course Deep Dive**: This topic is covered in detail in [Lesson 7.3: Understanding Task suspension points](https://www.swiftconcurrencycourse.com?utm_source=github&utm_medium=agent-skill&utm_campaign=lesson-reference)
+
+## Thread Execution Patterns
+
+### Default: Background threads
+
+Tasks run on cooperative thread pool (background threads):
+
+```swift
+Task {
+    print(Thread.current) // Background thread
+}
+```
+
+### Main thread execution
+
+Use `@MainActor` for main thread:
+
+```swift
+@MainActor
+func updateUI() {
+    Task {
+        print(Thread.current) // Main thread
+    }
+}
+```
+
+### Inheritance example
+
+```swift
+@MainActor
+func updateUI() {
+    print("Main thread: \(Thread.current)")
+    
+    await backgroundTask() // Switches to background
+    
+    print("Back on main: \(Thread.current)") // Returns to main
+}
+
+func backgroundTask() async {
+    print("Background: \(Thread.current)")
+}
+```
+
+## Swift 6.2 Changes
+
+### Nonisolated async functions (SE-461)
+
+**Old behavior**: Nonisolated async functions always switch to background.
+
+**New behavior**: Inherit caller's isolation by default.
+
+```swift
+class NotSendable {
+    func performAsync() async {
+        print(Thread.current)
+    }
+}
+
+@MainActor
+func caller() async {
+    let obj = NotSendable()
+    await obj.performAsync()
+    // Old: Background thread
+    // New: Main thread (inherits @MainActor)
+}
+```
+
+### Enabling new behavior
+
+In Xcode 16+:
+
+```swift
+// Build setting or swift-settings
+.enableUpcomingFeature("NonisolatedNonsendingByDefault")
+```
+
+### Opting out with @concurrent
+
+Force function to switch away from caller's isolation:
+
+```swift
+@concurrent
+func performAsync() async {
+    print(Thread.current) // Always background
+}
+```
+
+### nonisolated(nonsending)
+
+Prevent sending non-Sendable values across isolation:
+
+```swift
+nonisolated(nonsending) func storeTouch(...) async {
+    // Runs on caller's isolation, no value sending
+}
+```
+
+> **Course Deep Dive**: This topic is covered in detail in [Lesson 7.4: Dispatching to different threads using nonisolated(nonsending) and @concurrent (Updated for Swift 6.2)](https://www.swiftconcurrencycourse.com?utm_source=github&utm_medium=agent-skill&utm_campaign=lesson-reference)
+
+**Use when**: Method doesn't need to switch isolation, avoiding Sendable requirements.
+
+## Default Isolation Domain (SE-466)
+
+### Configuring default isolation
+
+**Build setting** (Xcode 16+):
+- Default Actor Isolation: `MainActor` or `None`
+
+**Swift Package**:
+
+```swift
+.target(
+    name: "MyTarget",
+    swiftSettings: [
+        .defaultIsolation(MainActor.self)
+    ]
+)
+```
+
+### Why change default?
+
+Most app code runs on main thread. Setting `@MainActor` as default:
+- Reduces false warnings
+- Avoids "concurrency rabbit hole"
+- Makes migration easier
+
+### Inference with @MainActor default
+
+```swift
+// With @MainActor as default:
+
+func f() {} // Inferred: @MainActor
+
+class C {
+    init() {} // Inferred: @MainActor
+    static var value = 10 // Inferred: @MainActor
+}
+
+@MyActor
+struct S {
+    func f() {} // Inferred: @MyActor (explicit override)
+}
+
+> **Course Deep Dive**: This topic is covered in detail in [Lesson 7.5: Controlling the default isolation domain (Updated for Swift 6.2)](https://www.swiftconcurrencycourse.com?utm_source=github&utm_medium=agent-skill&utm_campaign=lesson-reference)
+```
+
+### Per-module setting
+
+Must opt in for each module/package. Not global across dependencies.
+
+### Backward compatibility
+
+Opt-in only. Default remains `nonisolated` if not specified.
+
+## Debugging Thread Execution
+
+### Print current thread
+
+**⚠️ Important**: `Thread.current` is unavailable in Swift 6 language mode from async contexts. The compiler error states: "Class property 'current' is unavailable from asynchronous contexts; Thread.current cannot be used from async contexts."
+
+**Workaround** (Swift 6+ mode only):
+
+```swift
+extension Thread {
+    public static var currentThread: Thread {
+        Thread.current
+    }
+}
+
+print("Thread: \(Thread.currentThread)")
+```
+
+### Debug navigator
+
+1. Set breakpoint in task
+2. Debug → Pause
+3. Check Debug Navigator for thread info
+
+### Verify main thread
+
+```swift
+assert(Thread.isMainThread)
+```
+
+## Common Misconceptions
+
+### ❌ Each Task runs on new thread
+
+**Wrong**. Tasks share limited thread pool, reuse threads.
+
+### ❌ await blocks the thread
+
+**Wrong**. `await` suspends task without blocking thread. Other tasks can use the thread.
+
+### ❌ Task execution order is guaranteed
+
+**Wrong**. Tasks execute based on system scheduling. Use `await` to enforce order.
+
+### ❌ Same task = same thread
+
+**Wrong**. Task can resume on different thread after suspension.
+
+## Why Sendable Matters
+
+Since tasks move between threads unpredictably:
+
+```swift
+func example() async {
+    print("Thread 1: \(Thread.current)")
+    
+    await someWork()
+    
+    print("Thread 2: \(Thread.current)") // Different thread
+}
+```
+
+Values crossing suspension points may cross threads. **Sendable** ensures safety.
+
+## Best Practices
+
+1. **Stop thinking about threads** - think isolation domains
+2. **Trust the system** - Swift optimizes thread usage
+3. **Use @MainActor for UI** - clear, explicit main thread execution
+4. **Minimize suspension points in actors** - avoid reentrancy bugs
+5. **Complete state changes before suspending** - prevent inconsistent state
+6. **Use priorities as hints** - not guarantees
+7. **Make types Sendable** - safe across thread boundaries
+8. **Enable Swift 6.2 features** - easier migration, better defaults
+9. **Set default isolation for apps** - reduce false warnings
+10. **Don't force thread switching** - let Swift optimize
+
+## Migration Strategy
+
+### For new projects (Xcode 16+)
+
+1. Set default isolation to `@MainActor`
+2. Enable `NonisolatedNonsendingByDefault`
+3. Use `@concurrent` for explicit background work
+
+### For existing projects
+
+1. Gradually enable Swift 6 language mode
+2. Consider default isolation change
+3. Use `@concurrent` to maintain old behavior where needed
+4. Migrate module by module
+
+## Decision Tree
+
+```
+Need to control execution?
+├─ UI updates? → @MainActor
+├─ Specific state isolation? → Custom actor
+├─ Background work? → Regular async (trust Swift)
+└─ Need to force background? → @concurrent (Swift 6.2+)
+
+Seeing Sendable warnings?
+├─ Can make type Sendable? → Add conformance
+├─ Same isolation OK? → nonisolated(nonsending)
+└─ Need different isolation? → Make Sendable or refactor
+```
+
+## GCD to Isolation Domain Migration
+
+Instead of asking "what thread should this run on?" ask "what isolation domain should own this work?"
+
+- `DispatchQueue.main.async { }` → `@MainActor func updateUI()`
+- `DispatchQueue.global().async { }` → `func work() async` (or `@concurrent` if it must leave caller isolation)
+- `DispatchQueue(label:).sync { }` → `actor` or `Mutex` for protecting state
+- Serial queue for ordering → `actor` (guarantees serial access)
+
+## Decision Rules
+
+- UI state → usually `@MainActor`
+- Mutable shared state → usually an `actor`
+- Plain async work with no isolated state → `async` API with explicit ownership
+- Work that must hop away from caller isolation under Swift 6.2-era behavior → consider `@concurrent`
+
+## Common Mistakes Agents Make
+
+- Recommending GCD queue hopping when actor isolation already expresses the ownership model.
+- Debugging correctness by thread ID instead of by isolation and ordering.
+- Treating `await` as a blocking call — it suspends the task, freeing the thread.
+- Mapping each `Task` to a conceptual thread.
+
+## Performance Insights
+
+### Why fewer threads = better performance
+
+- **Less context switching**: CPU spends more time on actual work
+- **Better cache utilization**: Threads stay on same cores longer
+- **No thread explosion**: Predictable resource usage
+- **Forward progress**: Threads never block, always productive
+
+### Cooperative pool advantages
+
+- Matches hardware (one thread per core)
+- Prevents oversubscription
+- Efficient task scheduling
+- Automatic load balancing
+
+## Further Learning
+
+For migration strategies, real-world examples, and advanced threading patterns, see [Swift Concurrency Course](https://www.swiftconcurrencycourse.com).
+

package/skills/ios/swift-concurrency-6-2/SKILL.md

@@ -0,0 +1,216 @@
+---
+name: swift-concurrency-6-2
+description: Swift 6.2 Approachable Concurrency — single-threaded by default, @concurrent for explicit background offloading, isolated conformances for main actor types.
+---
+
+# Swift 6.2 Approachable Concurrency
+
+Patterns for adopting Swift 6.2's concurrency model where code runs single-threaded by default and concurrency is introduced explicitly. Eliminates common data-race errors without sacrificing performance.
+
+## When to Activate
+
+- Migrating Swift 5.x or 6.0/6.1 projects to Swift 6.2
+- Resolving data-race safety compiler errors
+- Designing MainActor-based app architecture
+- Offloading CPU-intensive work to background threads
+- Implementing protocol conformances on MainActor-isolated types
+- Enabling Approachable Concurrency build settings in Xcode 26
+
+## Core Problem: Implicit Background Offloading
+
+In Swift 6.1 and earlier, async functions could be implicitly offloaded to background threads, causing data-race errors even in seemingly safe code:
+
+```swift
+// Swift 6.1: ERROR
+@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 6.2 fixes this: async functions stay on the calling actor by default.
+
+```swift
+// Swift 6.2: OK — async stays on MainActor, no data race
+@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)
+    }
+}
+```
+
+## Core Pattern — Isolated Conformances
+
+MainActor types can now conform to non-isolated protocols safely:
+
+```swift
+protocol Exportable {
+    func export()
+}
+
+// Swift 6.1: ERROR — crosses into main actor-isolated code
+// Swift 6.2: OK with isolated conformance
+extension StickerModel: @MainActor Exportable {
+    func export() {
+        photoProcessor.exportAsPNG()
+    }
+}
+```
+
+The compiler ensures the conformance is only used on the main actor:
+
+```swift
+// OK — ImageExporter is also @MainActor
+@MainActor
+struct ImageExporter {
+    var items: [any Exportable]
+
+    mutating func add(_ item: StickerModel) {
+        items.append(item)  // Safe: same actor isolation
+    }
+}
+
+// ERROR — nonisolated context can't use MainActor conformance
+nonisolated struct ImageExporter {
+    var items: [any Exportable]
+
+    mutating func add(_ item: StickerModel) {
+        items.append(item)  // Error: Main actor-isolated conformance cannot be used here
+    }
+}
+```
+
+## Core Pattern — Global and Static Variables
+
+Protect global/static state with MainActor:
+
+```swift
+// Swift 6.1: ERROR — non-Sendable type may have shared mutable state
+final class StickerLibrary {
+    static let shared: StickerLibrary = .init()  // Error
+}
+
+// Fix: Annotate with @MainActor
+@MainActor
+final class StickerLibrary {
+    static let shared: StickerLibrary = .init()  // OK
+}
+```
+
+### MainActor Default Inference Mode
+
+Swift 6.2 introduces a mode where MainActor is inferred by default — no manual annotations needed:
+
+```swift
+// With MainActor default inference enabled:
+final class StickerLibrary {
+    static let shared: StickerLibrary = .init()  // Implicitly @MainActor
+}
+
+final class StickerModel {
+    let photoProcessor: PhotoProcessor
+    var selection: [PhotosPickerItem]  // Implicitly @MainActor
+}
+
+extension StickerModel: Exportable {  // Implicitly @MainActor conformance
+    func export() {
+        photoProcessor.exportAsPNG()
+    }
+}
+```
+
+This mode is opt-in and recommended for apps, scripts, and other executable targets.
+
+## Core Pattern — @concurrent for Background Work
+
+When you need actual parallelism, explicitly offload with `@concurrent`:
+
+> **Important:** This example requires Approachable Concurrency build settings — SE-0466 (MainActor default isolation) and SE-0461 (NonisolatedNonsendingByDefault). With these enabled, `extractSticker` stays on the caller's actor, making mutable state access safe. **Without these settings, this code has a data race** — the compiler will flag it.
+
+```swift
+nonisolated final class PhotoProcessor {
+    private 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
+    }
+
+    // Offload expensive work to concurrent thread pool
+    @concurrent
+    static func extractSubject(from data: Data) async -> Sticker { /* ... */ }
+}
+
+// Callers must await
+let processor = PhotoProcessor()
+processedPhotos[item.id] = await processor.extractSticker(data: data, with: item.id)
+```
+
+To use `@concurrent`:
+1. Mark the containing type as `nonisolated`
+2. Add `@concurrent` to the function
+3. Add `async` if not already asynchronous
+4. Add `await` at call sites
+
+## Key Design Decisions
+
+| Decision | Rationale |
+|----------|-----------|
+| Single-threaded by default | Most natural code is data-race free; concurrency is opt-in |
+| Async stays on calling actor | Eliminates implicit offloading that caused data-race errors |
+| Isolated conformances | MainActor types can conform to protocols without unsafe workarounds |
+| `@concurrent` explicit opt-in | Background execution is a deliberate performance choice, not accidental |
+| MainActor default inference | Reduces boilerplate `@MainActor` annotations for app targets |
+| Opt-in adoption | Non-breaking migration path — enable features incrementally |
+
+## Migration Steps
+
+1. **Enable in Xcode**: Swift Compiler > Concurrency section in Build Settings
+2. **Enable in SPM**: Use `SwiftSettings` API in package manifest
+3. **Use migration tooling**: Automatic code changes via swift.org/migration
+4. **Start with MainActor defaults**: Enable inference mode for app targets
+5. **Add `@concurrent` where needed**: Profile first, then offload hot paths
+6. **Test thoroughly**: Data-race issues become compile-time errors
+
+## Best Practices
+
+- **Start on MainActor** — write single-threaded code first, optimize later
+- **Use `@concurrent` only for CPU-intensive work** — image processing, compression, complex computation
+- **Enable MainActor inference mode** for app targets that are mostly single-threaded
+- **Profile before offloading** — use Instruments to find actual bottlenecks
+- **Protect globals with MainActor** — global/static mutable state needs actor isolation
+- **Use isolated conformances** instead of `nonisolated` workarounds or `@Sendable` wrappers
+- **Migrate incrementally** — enable features one at a time in build settings
+
+## Anti-Patterns to Avoid
+
+- Applying `@concurrent` to every async function (most don't need background execution)
+- Using `nonisolated` to suppress compiler errors without understanding isolation
+- Keeping legacy `DispatchQueue` patterns when actors provide the same safety
+- Skipping `model.availability` checks in concurrency-related Foundation Models code
+- Fighting the compiler — if it reports a data race, the code has a real concurrency issue
+- Assuming all async code runs in the background (Swift 6.2 default: stays on calling actor)
+
+## When to Use
+
+- All new Swift 6.2+ projects (Approachable Concurrency is the recommended default)
+- Migrating existing apps from Swift 5.x or 6.0/6.1 concurrency
+- Resolving data-race safety compiler errors during Xcode 26 adoption
+- Building MainActor-centric app architectures (most UI apps)
+- Performance optimization — offloading specific heavy computations to background