Swift Concurrency

Apply the smallest change that makes isolation and ownership correct while preserving observable behavior.

Contents

• Scope and Toolchain Preflight
• Diagnostic Workflow
• Isolation Decisions
• Safety Rules
• Interop and Streams
• Common Mistakes
• Review Checklist
• References

Scope and Toolchain Preflight

This skill owns compiler concurrency diagnostics, actor isolation, Sendable, task structure, cancellation, reentrancy, async sequences, continuations, and synchronization. Route routine SwiftUI .task ownership to swiftui-patterns, app architecture to swift-architecture, and test syntax to swift-testing.

Before recommending versioned language features, inspect:

• Xcode and Swift toolchain version
• Swift language mode and strict-concurrency setting
• Approachable Concurrency setting
• Default Actor Isolation setting
• deployment target when a runtime API is involved

Do not change project-wide isolation or language settings unless the request includes migration or build configuration. Verify new language/API claims against Swift Evolution, release notes, SDK headers, or primary Apple/Swift documentation.

Diagnostic Workflow

1. Capture the exact diagnostic and declaration involved.
2. Identify current isolation, mutation owner, call direction, and values crossing the boundary.
3. Decide whether the operation is UI-bound, stateful background work, stateless work, or legacy interop.
4. Apply the narrowest safe fix and avoid broad escape hatches.
5. Rebuild, inspect new diagnostics, and test cancellation/failure behavior affected by the change.

Use Diagnostics for compiler-message-specific remedies and Approachable Concurrency for build-setting semantics.

Isolation Decisions

Default MainActor isolation does not make every operation appropriate for the main actor. Keep CPU-heavy work, blocking I/O, and non-UI services off it. Conversely, do not remove isolation merely to silence a compiler error.

Safety Rules

• Prefer structured child tasks over detached tasks so priority, task-local values, and cancellation propagate.
• Treat cancellation as cooperative: check it at meaningful boundaries and clean up resources.
• Revalidate actor state after every suspension point when intervening work could change it.
• Add Sendable only when the stored graph and mutation model make the conformance true.
• Use @unchecked Sendable or nonisolated(unsafe) only with a local, documented invariant and targeted verification.
• Never hold a synchronous lock across await.
• Do not place locks inside an actor to protect the actor's own state.
• Avoid semaphores and blocking waits on cooperative executor threads.
• A manual task needs a clear owner, cancellation point, and lifetime.

Read Synchronization Primitives for locks versus actors, and Concurrency Patterns for task groups, actors, cancellation, and reentrancy examples.

Interop and Streams

Use checked continuations for one-shot callbacks and resume exactly once on every terminal path. Use AsyncStream/AsyncThrowingStream for multiple values and install termination cleanup for delegates, observers, or underlying operations.

Read Bridging and Interop before adapting delegates, GCD, unsafe buffers, or synchronous parallel loops. Read Async Algorithms for debounce, throttle, merge, and related sequence operations.

Common Mistakes

• Silencing compiler concurrency errors with @unchecked Sendable or removing isolation without an invariant.
• Holding an unfair lock or NSLock across an await suspension point.
• Spawning detached tasks (Task.detached) instead of structured child tasks (async let, TaskGroup).
• Assuming actor state is unchanged after await without revalidating invariants.
• Blocking cooperative executor threads with synchronous disk/network I/O or Thread.sleep.

Review Checklist

• Exact toolchain and concurrency settings are known when they matter
• Every mutable state graph has a clear isolation owner
• Cross-isolation values are safely transferable
• No blocking work runs on the main actor or cooperative pool
• Structured tasks are preferred; detached/manual tasks are justified
• Cancellation, failure, and resource cleanup are tested
• Actor state assumptions are reconsidered after await
• No unjustified @unchecked Sendable, nonisolated(unsafe), or @preconcurrency remains
• Locks are synchronous, local, and never held across suspension
• The compiler diagnostic is gone without changing unrelated behavior

References

• Concurrency patterns and migration
• Approachable Concurrency
• SwiftUI-specific concurrency
• Synchronization primitives
• Callbacks, GCD, and unsafe interop
• Compiler diagnostics
• Async algorithms