Swift Concurrency

Lifecycle Position

Phase 3 (Implement) and Phase 5 (Review). Load for async patterns during implementation; use checklist during code review. Related: swift-networking for async network calls.

Decision Tree: Where Should This Code Run?

Is it UI code (views, view models, UI state)? → Yes → @MainActor Does it manage shared mutable state? → Yes → Custom actor Is it pure computation with no shared state? → Yes → nonisolated (Swift 6.2: @concurrent for CPU-heavy work) Is it a one-off async operation from synchronous code? → Yes → Task { } (inherits actor context)

Actor Isolation

@MainActor

// On the entire class (recommended for ViewModels) @Observable @MainActor class UserViewModel { var users: [User] = [] var isLoading = false

func loadUsers() async {
    isLoading = true
    defer { isLoading = false }
    users = try? await api.fetchUsers() ?? []
}

}

// On specific methods only class DataProcessor { @MainActor func updateUI(with results: [Result]) { // Safe to touch UI state }

nonisolated func processInBackground(_ data: Data) -> [Result] {
    // Runs on any thread, no actor isolation
}

}

Custom Actors

actor ImageCache { private var cache: [URL: Image] = [:]

func image(for url: URL) -> Image? {
    cache[url]
}

func store(_ image: Image, for url: URL) {
    cache[url] = image
}

}

// Usage — every call crosses an isolation boundary let cache = ImageCache() let image = await cache.image(for: url) // await required

Actor Reentrancy

actor BankAccount { var balance: Decimal

func withdraw(_ amount: Decimal) async throws {
    // WARNING: balance might change between check and deduction
    // because another task could run during the await
    guard balance >= amount else { throw BankError.insufficientFunds }

    await recordTransaction(amount)  // suspension point — other tasks can interleave

    // Re-check invariant after suspension
    guard balance >= amount else { throw BankError.insufficientFunds }
    balance -= amount
}

}

Rule: Always re-validate state after any await inside an actor.

SwiftData Concurrency

@Model classes have specific concurrency constraints enforced by Swift 6:

• @Model is non-Sendable — do not pass model instances across actor boundaries

• ModelContext is @MainActor -bound — create and use on the main actor

• ModelContainer is Sendable — safe to pass between actors

Cross-Actor Access Pattern

// WRONG — passing @Model across actors let item = context.fetch(...) // on MainActor await backgroundActor.process(item) // non-Sendable error

// RIGHT — pass the identifier, re-fetch on the other side let itemID = item.persistentModelID await backgroundActor.process(itemID, container: container)

// In the background actor: let bgContext = ModelContext(container) let item = bgContext.model(for: itemID) as? Item

Testing Implications

When writing tests for @Observable @MainActor models that use SwiftData:

• Test suites must be @MainActor (matches the model's isolation)

• Use .serialized on @Suite to prevent parallel container conflicts

• See ios-testing skill for complete SwiftData testing patterns

Sendability

Sendable Protocol

// Value types are automatically Sendable struct UserID: Sendable { let rawValue: UUID }

// Immutable classes can be Sendable final class Configuration: Sendable { let apiURL: URL // let = immutable = safe let timeout: TimeInterval }

// Mutable shared state needs an actor, not @unchecked Sendable // AVOID unless you truly manage synchronization yourself: final class LegacyCache: @unchecked Sendable { private let lock = NSLock() private var storage: [String: Data] = [:] // Must manually synchronize ALL access }

The sending Keyword (Swift 6)

func process(_ data: sending Data) async { // Compiler guarantees caller won't access data after passing it }

Structured Concurrency

async let (parallel independent work)

async let profile = api.fetchProfile(id) async let posts = api.fetchPosts(userId: id) async let followers = api.fetchFollowers(userId: id)

let (p, po, f) = try await (profile, posts, followers) // all run in parallel

TaskGroup (dynamic parallel work)

let images = try await withThrowingTaskGroup(of: (URL, Image).self) { group in for url in urls { group.addTask { let image = try await downloadImage(from: url) return (url, image) } } var results: [URL: Image] = [:] for try await (url, image) in group { results[url] = image } return results }

Cancellation

func processLargeDataset(_ items: [Item]) async throws { for item in items { try Task.checkCancellation() // Throws if cancelled await process(item) } }

// Or check without throwing if Task.isCancelled { return }

Unstructured Tasks

// Task { } — inherits current actor context @MainActor class ViewModel { func start() { Task { // This runs on MainActor (inherited) await loadData() } } }

// Task.detached { } — no actor inheritance, runs on global executor Task.detached(priority: .background) { // This does NOT run on MainActor let result = heavyComputation(data) await MainActor.run { self.updateUI(result) } }

When to use each:

• Task { } — 90% of cases. Starting async work from sync context.

• Task.detached { } — CPU-heavy work that must NOT run on MainActor.

Migration from GCD

GCD Pattern Modern Equivalent

DispatchQueue.main.async { }

@MainActor or MainActor.run { }

DispatchQueue.global().async { }

Task.detached { } or nonisolated method

DispatchGroup

TaskGroup or async let

DispatchSemaphore

Actor isolation (semaphores + async = deadlock risk)

DispatchQueue (serial, for sync) Actor

Completion handler async throws -> return value

Bridging Completion Handlers

func legacyFetch(completion: @escaping (Result<Data, Error>) -> Void) { /* ... */ }

// Wrap with continuation func modernFetch() async throws -> Data { try await withCheckedThrowingContinuation { continuation in legacyFetch { result in continuation.resume(with: result) // MUST be called exactly once } } }

Swift 6 Strict Concurrency

Incremental Adoption

// Enable per-target in Package.swift .target(name: "MyApp", swiftSettings: [.swiftLanguageMode(.v6)])

// Or per-file: suppress specific warnings during migration @preconcurrency import SomeOldLibrary

Common Warnings and Fixes

Warning Fix

"Sending 'value' risks data race" Make type Sendable or use sending parameter

"Non-sendable type captured by @Sendable closure" Move to actor-isolated method or make type Sendable

"Actor-isolated property cannot be mutated from nonisolated context" Add await or annotate caller with same actor

"Global variable is not concurrency-safe" Make it let , move to actor, or use nonisolated(unsafe) (last resort)

"Conformance of X to protocol Y crosses into main actor-isolated code" Use isolated conformance: extension X: @MainActor Y (Swift 6.2+)

Swift 6.2 Approachable Concurrency

Swift 6.2 changes the default: async functions stay on the calling actor instead of hopping to the global concurrent executor. This eliminates entire categories of data race errors for UI-bound code.

Key changes: See references/swift-6-2-changes.md for full details.

Feature What It Does

Async stays on caller's actor No implicit background hop — eliminates "Sending X risks data races" errors

@concurrent attribute Explicit opt-in to run on concurrent pool (replaces Task.detached for this use case)

Main-actor-by-default mode Opt-in: all types in a target implicitly @MainActor

Isolated conformances extension Foo: @MainActor Bar — protocol conformance restricted to main actor

SwiftUI-specific: See references/swiftui-concurrency.md for off-main-thread APIs (Shape , Layout , visualEffect , onGeometryChange ) and their Sendable closure requirements.

Project triage: Before diagnosing concurrency errors, check Xcode Build Settings → Swift Compiler → Concurrency for language version and default actor isolation settings.

Common Patterns

Actor-Isolated Repository

For a complete actor-based persistence pattern with file backing, see swift-actor-persistence .

actor UserRepository { private let api: any APIClientProtocol private var cache: [UserID: User] = [:]

func user(_ id: UserID) async throws -> User {
    if let cached = cache[id] { return cached }
    let user: User = try await api.request("/users/\(id.rawValue)")
    cache[id] = user
    return user
}

}

.task Modifier for View Lifecycle

struct UserView: View { @State private var viewModel = UserViewModel()

var body: some View {
    content
        .task { await viewModel.load() }          // auto-cancels on disappear
        .task(id: selectedID) { await viewModel.load(selectedID) }  // re-runs when ID changes
}

}

Review Checklist

• No data races: mutable shared state in actors or protected by isolation

• Actor isolation boundaries clearly documented (which actor owns which state)

• Cancellation cooperative: long operations check Task.checkCancellation()

• Task references stored for cleanup if not using .task modifier

• .task modifier used for view lifecycle async work (not onAppear { Task { } } )

• @MainActor on view models and UI state classes

• No DispatchSemaphore mixed with async code (deadlock risk)

• withCheckedContinuation resumes exactly once (not zero, not twice)

• State re-validated after suspension points in actors (reentrancy)

• @unchecked Sendable justified in comment if used

• Swift 6.2: Check project concurrency settings before diagnosing (language version, default actor isolation)

• Swift 6.2: @concurrent used instead of Task.detached for explicit background work

• SwiftUI: No @MainActor state accessed from Sendable closures (visualEffect, onGeometryChange) — use value copies

Cross-References

• swift-networking — async/await network patterns

• swiftui-ui-patterns — .task modifier, @MainActor ViewModel pattern, Sendable checks

• ios-testing — testing async code with Swift Testing (#expect with await )

• code-analyzer — concurrency safety review section

• swift-actor-persistence — actor-based persistence pattern with file backing (extends the Actor-Isolated Repository pattern above)