concurrency-patterns

Swift Concurrency Patterns

Comprehensive guide for Swift concurrency covering async/await, structured concurrency, actors, and the Swift 6.2 "Approachable Concurrency" features. Focuses on patterns that prevent data races and common mistakes that cause crashes.

When This Skill Activates

• User has data race errors or actor isolation compiler errors
• User is migrating to Swift 6 strict concurrency
• User asks about async/await, actors, Sendable, TaskGroup, or MainActor
• User needs to bridge legacy completion-handler APIs to async/await
• User is working with Swift 6.2 features (@concurrent, isolated conformances)
• User has concurrency bugs (actor reentrancy, task cancellation, UI freezes)

Decision Tree

What concurrency problem are you solving?
│
├─ Swift 6 compiler errors / migration
│  └─ migration-guide.md
│
├─ Swift 6.2 new features (@concurrent, isolated conformances)
│  └─ swift62-concurrency.md
│
├─ Running work in parallel (async let, TaskGroup)
│  └─ structured-concurrency.md
│
├─ Thread safety for shared mutable state
│  └─ actors-and-isolation.md
│
├─ Bridging old APIs (delegates, callbacks) to async/await
│  └─ continuations-bridging.md
│
├─ Hangs, slow parallelism, thread-pool problems, profiling
│  └─ concurrency-internals.md
│
└─ General async/await patterns
   └─ See macos/coding-best-practices/modern-concurrency.md for basics

Quick Reference

Pattern	When to Use	Reference
async let	Fixed number of parallel operations	structured-concurrency.md
withTaskGroup	Dynamic number of parallel operations	structured-concurrency.md
withDiscardingTaskGroup	Fire-and-forget parallel operations	structured-concurrency.md
.task { } modifier	Load data when view appears	structured-concurrency.md
.task(id:) modifier	Re-load when a value changes	structured-concurrency.md
actor	Shared mutable state protection	actors-and-isolation.md
@MainActor	UI-bound state and updates	actors-and-isolation.md
@concurrent	Explicitly offload to background (6.2)	swift62-concurrency.md
Isolated conformances	@MainActor type conforming to protocol (6.2)	swift62-concurrency.md
withCheckedContinuation	Bridge callback API to async	continuations-bridging.md
AsyncStream	Bridge delegate/notification API to async sequence	continuations-bridging.md
@TaskLocal	Context (IDs, tracing) down the task tree	structured-concurrency.md
Atomic / Mutex	Sendable wrappers for synchronous hot paths (Swift 6)	actors-and-isolation.md
Custom actor executors	Bridge existing DispatchSerialQueue synchronization	concurrency-internals.md
Swift Concurrency Instrument	Diagnose hangs, actor contention, continuation leaks	concurrency-internals.md
Strict concurrency migration	Incremental Swift 6 adoption	migration-guide.md

Process

1. Identify the Problem

Read the user's code or error messages to determine:

• Is this a compiler error (strict concurrency) or a runtime issue (data race, crash)?
• What Swift version and concurrency checking level are they using?
• Are they migrating existing code or writing new code?

2. Load Relevant Reference Files

Based on the problem, read from this directory:

• swift62-concurrency.md — Swift 6.2 approachable concurrency features, Apple's adoption doctrine, Swift 6.3/6.4 additions
• structured-concurrency.md — async let, TaskGroup, .task modifier lifecycle, task-locals, cancellation semantics
• actors-and-isolation.md — Actor patterns, reentrancy, @MainActor, Sendable, Atomic/Mutex
• concurrency-internals.md — cooperative pool, unsafe primitives, actor scheduling, Swift Concurrency Instrument
• continuations-bridging.md — withCheckedContinuation, AsyncStream, built-in async sequences, legacy bridging
• migration-guide.md — Incremental Swift 6 strict concurrency adoption (WWDC24 doctrine)

3. Review Checklist

• No blocking calls on @MainActor (use await for long operations)
• Shared mutable state protected by an actor (not locks or DispatchQueue)
• Sendable conformance correct for types crossing isolation boundaries
• Task cancellation handled (check Task.isCancelled or Task.checkCancellation())
• No unstructured Task {} where structured concurrency (.task, TaskGroup) would work
• Actor reentrancy considered at suspension points
• withCheckedContinuation called exactly once (not zero, not twice)
• .task(id:) used instead of manual onChange + cancel patterns

4. Cross-Reference

• For async/await basics and actor fundamentals, see macos/coding-best-practices/modern-concurrency.md
• For networking concurrency patterns, see generators/networking-layer/networking-patterns.md
• For SwiftData concurrency (@ModelActor), see macos/swiftdata-architecture/repository-pattern.md
• For auth token refresh with actors, see generators/auth-flow/auth-patterns.md

References

• Swift Concurrency
• Migrating to Swift 6
• Local captured doc (optional): ~/Downloads/docs/Swift-Concurrency-Updates.md — read if present; skip silently if absent.