Programming Concurrency

Swift 6.2 with defaultIsolation(MainActor.self) inverts assumptions: everything is main-actor unless opted out with nonisolated or @concurrent. Advice depends on which mode the project uses.

1. Hard Rules

Violating any of these produces crashes, deadlocks, or data corruption.

Deadlocks

1. Never DispatchQueue.main.sync from the main thread. Also applies to any serial queue calling .sync on itself.
2. Never DispatchSemaphore.wait() or Thread.sleep() inside an async context. Blocks a cooperative thread pool thread. With enough blocked threads, the entire app deadlocks.
3. Never DispatchQueue.main.sync from inside a @MainActor function. Already on main; sync dispatch to main deadlocks.
4. Never hold a lock across an await suspension point. The lock may never be released.

Data Races

5. Every mutable variable accessed from multiple isolation domains needs documented synchronization. No exceptions.
6. @unchecked Sendable on a mutable class is not a fix. It silences the compiler; the race remains. The type must actually be protected (Mutex, actor, or immutable).
7. @Observable is NOT thread-safe for mutations. The registrar's lock protects bookkeeping, not your stored properties.
8. NSManagedObject must never cross thread boundaries. Pass NSManagedObjectID (Sendable) and fetch in the target context. SwiftData: pass PersistentIdentifier.

Main Thread

9. All AppKit API calls must be on the main thread unless documented otherwise. NSView, NSWindow, NSViewController, NSOpenPanel, autolayout, menus, accessibility.
10. @Published setters must fire on the main thread when observed by SwiftUI.
11. @Observable properties read by SwiftUI must be mutated on MainActor. No runtime warning (unlike @Published) -- silent race or crash. Use @MainActor on the class.

Continuation

12. withCheckedContinuation must be resumed exactly once on every code path. Missing = caller hangs forever. Double = runtime crash.

Actor Reentrancy

13. Actor state is NOT stable across await points. Another caller can execute between suspension and resumption. Re-read state after awaiting.

2. Which Primitive?

Do NOT use in async contexts: DispatchSemaphore, NSLock.lock(), Thread.sleep(), DispatchGroup.wait().

3. Writing New Concurrent Code

The Standard Architecture

SwiftUI View (.task) ──observes──▶ @MainActor @Observable ViewModel ──await──▶ actor Service

• View: Uses .task for async work (auto-cancelled on disappear), .task(id:) for reactive async.
• ViewModel: @Observable @MainActor class. Holds UI state. Async methods call services.
• Service: actor types for business logic, caching, network. Return Sendable values.

actor ItemService {
    func fetch() async throws -> [Item] { /* network/DB */ }
}

@Observable @MainActor
final class ItemViewModel {
    var items: [Item] = []
    var error: Error?
    private let service: ItemService

    func load() async {
        do { items = try await service.fetch() }
        catch { self.error = error }
    }
}

struct ItemView: View {
    @State private var vm: ItemViewModel
    var body: some View {
        List(vm.items) { item in Text(item.name) }
            .task { await vm.load() }
    }
}

When NOT to Use @MainActor on a Class

• Pure data models not observed by SwiftUI -- use an actor.
• Computation-heavy classes -- @MainActor blocks the UI thread. Use actor or @concurrent methods.
• Shared services consumed by multiple actors.

Rule: If SwiftUI views directly read its properties, @MainActor. If it only feeds data to a ViewModel, actor.

Task {} vs Task.detached

• Task {} inherits the current actor context. Preferred in most cases.
• Task.detached {} runs on the cooperative pool with no actor inheritance. Use only for genuinely independent background work.
• Never use .detached just to "go to background" -- the actor hop is handled automatically by await.

.task vs .onChange for Async Work

Prefer .task(id:) over .onChange + Task {}. The former auto-cancels on value change and disappear. The latter leaks tasks.

4. GCD + Swift Concurrency Coexistence

Most macOS codebases mix GCD and Swift concurrency. The boundary between them is where bugs live.

Bridging GCD to Async

func fetchLegacy() async throws -> Data {
    try await withCheckedThrowingContinuation { continuation in
        legacyAPI.fetch { data, error in
            if let error { continuation.resume(throwing: error) }
            else { continuation.resume(returning: data!) }
        }
    }
}

Migration Table

When GCD Is Still Right

• C/ObjC interop requiring dispatch queues
• DispatchSource for file descriptors, signals, timers
• Precise QoS targeting
• Legacy code not yet migrated (wrap in actors at boundaries)

5. Sendable & Isolation Boundaries

Decision Tree

Value type (struct/enum)?
├── All stored properties Sendable? → Sendable automatically
└── No → Make them Sendable, or Mutex-protect + @unchecked Sendable

Reference type (class)?
├── final + all let Sendable properties → conform to Sendable
├── Protected by Mutex/actor → @unchecked Sendable + document WHY
└── Otherwise → restructure as actor or struct

The sending Keyword (SE-0430)

Marks parameters/results that transfer ownership across isolation domains. More flexible than full Sendable conformance -- compiler verifies safety at call sites.

Escape Hatches (ranked by danger)

Every escape hatch needs a comment explaining why it's safe. If you can't write that comment, don't use it.

6. Common Mistakes

7. Swift 6 Migration

Incremental Ladder

1. Swift 5 + StrictConcurrency = targeted → fix warnings
2. Swift 5 + StrictConcurrency = complete → fix warnings
3. Swift 6 language mode → warnings become errors
4. Swift 6.2 approachable concurrency flags (one at a time)

Migrate leaf modules first (no internal dependencies).

Top Compiler Errors

Swift 6.2 Feature Flags

// Package.swift swiftSettings
.enableUpcomingFeature("NonisolatedNonsendingByDefault"),  // nonisolated async stays on caller
.enableUpcomingFeature("InferSendableFromCaptures"),       // auto @Sendable for provably safe closures
.enableUpcomingFeature("InferIsolatedConformances"),       // protocol conformances inherit isolation
.defaultIsolation(MainActor.self)                          // MainActor-by-default (app targets only)

nonisolated(nonsending): In 6.2, nonisolated async functions run on the caller's executor by default. A nonisolated method called from MainActor stays on main. Use @concurrent to explicitly run off-main.

8. Code Review Checklist

• No DispatchQueue.main.sync (especially inside @MainActor code)
• No blocking calls (semaphore.wait, Thread.sleep) in async contexts
• @Observable classes driving SwiftUI are @MainActor
• @Published mutations are on main thread
• NSManagedObject / ModelContext never crosses isolation boundaries
• Every withCheckedContinuation resumes exactly once on all paths
• Actor methods that await don't assume state stability across suspension
• Every @unchecked Sendable has a comment explaining the protection mechanism
• .task(id:) preferred over .onChange + Task {} for reactive async
• No Task.detached where Task {} would preserve needed actor context
• Deployment target supports any Synchronization framework types used

9. Testing Concurrent Code

Strategy: Two Tests Per Concurrent Component

1. Deterministic test: Use withMainSerialExecutor (from swift-concurrency-extras) to force serial execution. Verifies logic without timing sensitivity.
2. Concurrent test: Run with real concurrency + TSan enabled. Catches races.

Key Tools

TSan Caveats

TSan has known false positives with Swift concurrency as of 2025. Do NOT treat "TSan found no races" as proof of safety. Use it as one signal alongside compile-time checks.

Testing Actors

@Test func actorStateUpdates() async {
    await withMainSerialExecutor {
        let vm = ItemViewModel(service: MockService())
        await vm.load()
        #expect(vm.items.count == 3)
    }
}

10. Debugging

LLDB Commands

• thread list -- all threads
• thread backtrace all -- essential for deadlock diagnosis
• thread info -- current thread's dispatch queue and QoS

11. Platform-Specific Rules

Core Data

• NSManagedObjectContext: one queue only (NSMainQueueConcurrencyType or NSPrivateQueueConcurrencyType). Use perform {} for all private context access.
• Pass NSManagedObjectID across boundaries, fetch in target context.
• NSPersistentContainer.performBackgroundTask {} for background work.

SwiftData

• ModelContext is NOT sendable. ModelContainer IS sendable.
• @ModelActor runs on the thread where it was created. If created on main, it runs on main.
• Pass PersistentIdentifier across actors.

Combine

• receive(on: DispatchQueue.main) before .sink that touches UI.
• @Published must be set from main thread when observed by SwiftUI.
• publisher.values drops events under load. Use buffered AsyncStream for reliable bridging.
• Set<AnyCancellable> is NOT thread-safe. Confine to one isolation domain.

Metal

• MTLCommandQueue: thread-safe. MTLCommandBuffer: NOT thread-safe (encode on one thread).
• Triple buffering with semaphore for CPU-GPU sync.
• CAMetalLayer configuration changes: main thread only.

AppKit Thread Safety

XPC

• Reply handlers fire on the connection's private serial queue, never main thread.
• Synchronous XPC: reply fires on calling thread.
• Bridge to async with withCheckedContinuation.