Swift Concurrency

Swift Concurrency

Enterprise-grade skill for Swift Concurrency crash prevention, strict concurrency migration, and Swift 6.2 readiness. Opinionated: prescribes structured concurrency over unstructured, actors for shared mutable state, @MainActor for UI isolation, Mutex for synchronous critical sections, compile-time isolation over runtime hops, and withCheckedContinuation over withUnsafeContinuation. Every rule in this skill has broken a real production app.

Concurrency Layers

Application Layer    -> Structured concurrency: TaskGroup, async let, .task modifier
Actor Layer          -> actor for shared mutable state, @MainActor for UI state
Async/Await Layer    -> Cooperative, non-blocking async functions on the cooperative pool
Sendable Layer       -> Compile-time data-race safety at isolation boundary crossings
Compiler Layer       -> SWIFT_STRICT_CONCURRENCY=complete, Swift 6 language mode, TSan

Quick Decision Trees

"What isolation does this type need?"

Does this type own mutable state shared across concurrency domains?
+-- YES -> Does it need to update UI?
|   +-- YES -> @MainActor class/struct
|   +-- NO  -> Is the state complex or involves await points?
|       +-- YES -> actor
|       +-- NO  -> Mutex<State> (Swift 6+, iOS 18+) or NSLock wrapper
+-- NO  -> Is it a value type with only Sendable stored properties?
    +-- YES -> Implicitly Sendable (internal types only; public needs explicit conformance)
    +-- NO  -> Can it be redesigned as a value type?
        +-- YES -> Refactor to struct/enum
        +-- NO  -> Keep non-Sendable, contain within single isolation domain

"async let vs TaskGroup vs Task {}?"

How many concurrent operations?
+-- Known at compile time (2-5) -> async let (simplest, heterogeneous return types OK)
+-- Dynamic count (N items)     -> TaskGroup
|   +-- Need results?
|   |   +-- YES -> withThrowingTaskGroup (iterate with for await)
|   |   +-- NO  -> withDiscardingTaskGroup (no result accumulation leak)
|   +-- Unbounded input? -> Throttle: limit addTask to activeProcessorCount
+-- Fire-and-forget from sync context?
    +-- Need caller's isolation -> Task { } (inherits actor context)
    +-- Need background, no isolation -> Task.detached { }
       WARNING: detached strips priority, task-locals, cancellation propagation. Rarely correct.

"Is this safe to call from an async context?"

Does the API block the current thread?
+-- YES (semaphore.wait, group.wait, Thread.sleep, sync file I/O, NSLock in long section)
|   -> NEVER in async context. Deadlocks cooperative pool (capped at CPU core count).
|   -> Wrap in DispatchQueue + withCheckedContinuation to move off cooperative pool.
+-- NO  -> Is the work CPU-bound and takes >1ms?
    +-- YES -> Use @concurrent func (Swift 6.2+) or nonisolated func on dedicated queue
    +-- NO  -> Safe in async context

Workflows

Workflow: Audit Existing Codebase

When: First encounter with a codebase, or preparing for Swift 6 migration.

1. Check SWIFT_STRICT_CONCURRENCY setting (references/compiler-flags-ci.md)
2. Scan for crash patterns: continuation misuse, cooperative pool blocking, TaskGroup without throttling (references/crash-patterns.md)
3. Scan for @unchecked Sendable usage (references/sendable-transfer.md)
4. Check actor isolation: reentrancy bugs, deinit access, split isolation (references/actor-isolation.md)
5. Check AsyncStream usage: missing finish(), infinite sequences, no backpressure (references/asyncstream-memory.md)
6. For security-sensitive code: token refresh, TOCTOU, Keychain (references/security-concurrency.md)
7. Create refactoring/ directory with severity-ranked findings (references/refactoring-workflow.md)
8. Execute fixes: 🔴 crash → 🟡 hang → 🟠 data race → 🟢 best practice

Workflow: Migrate Module to Strict Concurrency

When: Enabling SWIFT_STRICT_CONCURRENCY=complete or Swift 6 mode.

The migration is a THREE-STEP progression, not a binary flip. Do not jump directly to complete or to Swift 6 language mode — you will drown in errors. The canonical progression is:

Most teams spend weeks in step 2 before advancing to step 3. Enabling step 3 prematurely produces hundreds of errors with no actionable incremental path.

1. Start with leaf modules (no internal dependencies) (references/migration-strategy.md)
2. Enable targeted on the leaf first to surface obvious Sendable gaps
3. Audit third-party SDKs for Sendable conformance; wrap blockers in actors (references/migration-strategy.md)
4. Fix global mutable state: static var → actor, Mutex, or let (references/actor-isolation.md)
5. Advance to complete on the leaf, fix each warning module by module
6. Annotate Sendable on public types; use sending where applicable (references/sendable-transfer.md)
7. Check Swift 6.2 caller-side isolation changes (references/swift-6-2-changes.md)
8. Only after complete is warning-free on the leaf, advance that leaf to Swift 6 language mode
9. Enable per-target in SPM (references/compiler-flags-ci.md)
10. Run TSan + LIBDISPATCH_COOPERATIVE_POOL_STRICT=1 (references/testing-debugging.md)
11. One PR per module, bottom-up order

Workflow: Create New Concurrent Feature

When: Building a new feature from scratch with Swift Concurrency.

1. Choose isolation model using Decision Tree 1 (actor vs @MainActor vs Mutex)
2. Choose concurrency structure using Decision Tree 2 (async let vs TaskGroup)
3. Implement with Sendable-clean types (references/sendable-transfer.md)
4. Add cancellation handling (references/advanced-patterns.md)
5. Use Clock injection for testability (references/testing-debugging.md)
6. Write deterministic tests with withMainSerialExecutor (references/testing-debugging.md)

Workflow: Fix Production Crash

When: Crash report points to continuation, actor, AsyncStream, or TaskGroup.

1. Classify crash type (references/crash-patterns.md)
2. Check if release-only (optimized builds strip cooperative pool assertions) -- Rule 9
3. For reentrancy crashes: check state assumptions after await (references/actor-isolation.md)
4. For security crashes: token refresh, TOCTOU patterns (references/security-concurrency.md)
5. Add targeted test reproducing the crash (references/testing-debugging.md)
6. Verify fix with TSan + LIBDISPATCH_COOPERATIVE_POOL_STRICT=1

Code Generation Rules

1. Never block the cooperative thread pool -- no semaphore.wait(), group.wait(), Thread.sleep(), synchronous file I/O in any async context
2. Resume every continuation exactly once on every code path -- use withCheckedThrowingContinuation
3. Re-check actor state after every await -- actors are reentrant at suspension points
4. Use withDiscardingTaskGroup for fire-and-forget child tasks -- prevents result accumulation memory leaks
5. AsyncStream must use onTermination for EVERY external resource cleanup — NotificationCenter observers, delegate assignments, timers, KVO, Combine subscribers, or any observer/callback registration made inside the stream's setup closure. deinit is not sufficient because an AsyncStream can outlive or be dropped independently of its owner; onTermination fires when the stream is finished or its task is cancelled, which is exactly when cleanup must run. Always pair every addObserver/delegate = self/registration call inside the stream setup with a symmetric removal in onTermination. Also call continuation.finish() from inside onTermination when your stream is an infinite observer pattern
6. Mark public types with explicit Sendable conformance -- no automatic inference across module boundaries
7. Limit TaskGroup child task count for unbounded work -- throttle to ProcessInfo.processInfo.activeProcessorCount
8. Use @MainActor annotation for UI isolation, not MainActor.run {}
9. Handle CancellationError silently -- never surface "cancelled" to users
10. Inject Clock protocol for time-dependent code -- never hardcode Task.sleep
11. Check Swift 6.2 caller-side isolation -- nonisolated async now inherits caller's actor; use @concurrent for explicit background
12. Before generating concurrent code, output a brief <thought> analyzing isolation domains, Sendable conformance, and potential reentrancy

Fallback Strategies & Loop Breakers

1. Sendable spiral: Conforming a type to Sendable cascades into 20+ errors across files. Temporarily use @preconcurrency import for the offending module and log a migration task in refactoring/discovered.md. Why: @preconcurrency suppresses Sendable checking at module boundaries while preserving local safety — it's the sanctioned escape hatch, unlike @unchecked Sendable which bypasses all checking.
2. Actor isolation cascade: Adding @MainActor to a class cascades into dozens of async call-site errors. Start by marking individual methods @MainActor instead of the whole class. Why: class-level isolation propagates to all methods, forcing every call site to be async — method-level isolation limits the blast radius.
3. Third-party SDK blocker: A third-party type is not Sendable and cannot be made so. Wrap it in a dedicated actor that owns the instance and mediates all access. Why: the actor serializes all access, making the non-Sendable type safe without needing to modify the SDK.
4. TaskGroup OOM: TaskGroup spawns thousands of child tasks and OOMs. Add a semaphore-based throttle: acquire before addTask, release inside the task. Limit to ProcessInfo.processInfo.activeProcessorCount * 2. Why: each child task retains its result until the group iterates — unbounded tasks accumulate results in memory.

Confidence Checks

Before finalizing generated or refactored concurrent code, verify ALL:

[] No cooperative pool blocking -- no semaphore.wait, Thread.sleep, sync I/O in any async function
[] No continuation leaks -- every withChecked*Continuation resumes on every path (success, failure, cancellation)
[] No unchecked Sendable -- every @unchecked Sendable has documented synchronization (Mutex, NSLock, or actor)
[] Actor reentrancy -- state re-checked after every await inside actors
[] AsyncStream cleanup -- finish() called in onTermination, no infinite sequence without cancellation
[] TaskGroup bounded -- child task count limited for unbounded input
[] MainActor correct -- UI state @MainActor-isolated, no MainActor.run anti-pattern
[] Swift 6.2 ready -- nonisolated async caller-isolation understood, @concurrent used where needed
[] Cancellation handled -- withTaskCancellationHandler for long-running ops, CancellationError caught silently
[] Tests deterministic -- Clock injected, withMainSerialExecutor used, no flaky timing dependencies
[] Compiler flags -- SWIFT_STRICT_CONCURRENCY=complete set, TSan enabled in CI

References

Start here for most tasks: crash-patterns.md, actor-isolation.md, sendable-transfer.md. Then consult the specific reference based on your workflow.