swift-concurrency-developer

Swift Concurrency Developer (Smart Router)

Purpose

Expert guidance on Swift's concurrency system using the "Office Building" mental model from Fucking Approachable Swift Concurrency, combined with comprehensive reference material from Swift Concurrency Course.

When Auto-Activated

• Working with actors, isolation, Sendable, TaskGroups
• Keywords: actor, isolation, Sendable, TaskGroup, nonisolated, async let
• Fixing concurrency warnings or data race issues

Agent Behavior Contract (Follow These Rules)

1. Analyze the project/package file to find out which Swift language mode (Swift 5.x vs Swift 6) and which Xcode/Swift toolchain is used when advice depends on it.
2. Before proposing fixes, identify the isolation boundary: @MainActor, custom actor, actor instance isolation, or nonisolated.
3. Do not recommend @MainActor as a blanket fix. Justify why main-actor isolation is correct for the code.
4. Prefer structured concurrency (child tasks, task groups) over unstructured tasks. Use Task.detached only with a clear reason.
5. If recommending @preconcurrency, @unchecked Sendable, or nonisolated(unsafe), require:
   • a documented safety invariant
   • a follow-up ticket to remove or migrate it
6. For migration work, optimize for minimal blast radius (small, reviewable changes) and add verification steps.
7. Course references are for deeper learning only. Use them sparingly and only when they clearly help answer the developer's question.

Project Settings Discovery

Always confirm these before interpreting diagnostics or giving migration-sensitive guidance. Do not guess — if any are unknown, ask the developer.

Tools: Read on Package.swift, Grep on .pbxproj.

Core Mental Model: The Office Building

Think of your app as an office building where isolation domains are private offices with locks:

Key insight: You can't barge into someone's office. You knock (await) and wait.

Quick Decision Tree

When a developer needs concurrency guidance:

1. Starting fresh with async code?

   • Read references/async-await-basics.md for foundational patterns
   • For parallel operations → references/tasks.md (async let, task groups)

2. Protecting shared mutable state?

   • Need to protect class-based state → references/actors.md (actors, @MainActor)
   • Need thread-safe value passing → references/sendable.md (Sendable conformance)

3. Managing async operations?

   • Structured async work → references/tasks.md (Task, child tasks, cancellation)
   • Streaming data → references/async-sequences.md (AsyncSequence, AsyncStream)

4. Working with legacy frameworks?

   • Core Data integration → references/core-data.md
   • General migration → references/migration.md

5. Performance or debugging issues?

   • Slow async code → references/performance.md (profiling, suspension points)
   • Testing concerns → references/testing.md (XCTest, Swift Testing)

6. Understanding threading behavior?

   • Read references/threading.md for thread/task relationship and isolation

7. Memory issues with tasks?

   • Read references/memory-management.md for retain cycle prevention

Triage-First Playbook (Common Errors -> Next Best Move)

• SwiftLint concurrency-related warnings
  • Use references/linting.md for rule intent and preferred fixes; avoid dummy awaits as "fixes".
• "Sending value of non-Sendable type ... risks causing data races"
  • First: identify where the value crosses an isolation boundary
  • Then: use references/sendable.md and references/threading.md
• "Main actor-isolated ... cannot be used from a nonisolated context"
  • First: decide if it truly belongs on @MainActor
  • Then: use references/actors.md (global actors, nonisolated, isolated parameters)
• XCTest async errors like "wait(...) is unavailable from asynchronous contexts"
  • Use references/testing.md (await fulfillment(of:) and Swift Testing patterns)
• Core Data concurrency warnings/errors
  • Use references/core-data.md (DAO/NSManagedObjectID, default isolation conflicts)

Quick Patterns

Async/Await

func fetchUser(id: Int) async throws -> User {
    let (data, _) = try await URLSession.shared.data(from: url)
    return try JSONDecoder().decode(User.self, from: data)
}

Parallel Work with async let

async let avatar = fetchImage("avatar.jpg")
async let banner = fetchImage("banner.jpg")
return Profile(avatar: try await avatar, banner: try await banner)

Tasks

// SwiftUI - cancels when view disappears
.task { avatar = await downloadAvatar() }

// Manual task (inherits actor context)
Task { await saveProfile() }

Task Entry Isolation (Swift 6.2)

Match a Task's entry isolation to its synchronous prefix — everything from { to the first await. Whatever runs in that prefix executes on the inherited actor.

• If the prefix needs @MainActor (touches UI state, mutates self.isLoading, etc.), keep the inherited start.
• If the prefix has nothing main-actor-bound, prefer Task { @concurrent in ... } and hop back via MainActor.run { ... } only for the UI mutation.
• A trivial non-main statement (e.g. print) followed by main-actor work is not a reason to switch to @concurrent — the cheap line rides along.
• For delayed retries, timers, and backoff: separate the waiting from the UI mutation. The sleep usually belongs off-main even when the final state update belongs on-main.

// ❌ Called from @MainActor; fetchData() is nonisolated, so the task starts on main then hops away
// (whether the hop happens depends on fetchData()'s declared isolation — nonisolated/@concurrent hop, @MainActor does not)
Task {
    await fetchData()  // nonisolated async
}

// ✅ Start off the main actor, hop back only for UI work
Task { @concurrent in
    let data = try await fetchData()
    await MainActor.run { self.items = data }
}

// ✅ Prefix DOES need main actor — keep inheritance
Task {
    self.isLoading = true       // needs @MainActor, before any await
    await fetchData()
    self.isLoading = false
}

TaskGroup for Dynamic Parallel Work

try await withThrowingTaskGroup(of: Void.self) { group in
    group.addTask { avatar = try await downloadAvatar() }
    group.addTask { bio = try await fetchBio() }
    try await group.waitForAll()
}

Actors

actor BankAccount {
    var balance: Double = 0
    func deposit(_ amount: Double) { balance += amount }

    // No await needed - can access directly inside actor
    nonisolated func bankName() -> String { "Acme Bank" }
}

await account.deposit(100)  // Must await from outside
let name = account.bankName()  // No await needed

Sendable Types

// Automatically Sendable - value type
struct User: Sendable {
    let id: Int
    let name: String
}

// Thread-safe class with internal synchronization
final class ThreadSafeCache: @unchecked Sendable {
    private let lock = NSLock()
    private var storage: [String: Data] = [:]
}

Common Mistakes

1. Thinking async = background

// WRONG: Still blocks main thread!
@MainActor func slowFunction() async {
    let result = expensiveCalculation()  // Synchronous = blocking
}

// CORRECT: Use detached task for CPU-heavy work
Task.detached(priority: .userInitiated) {
    let result = expensiveCalculation()
    await MainActor.run { updateUI(result) }
}

Production impact: Apps get rejected for "became unresponsive." See references/production-pitfalls.md section 2.

2. Creating too many actors

Most things can live on MainActor. Only create actors when you have shared mutable state that can't be on MainActor.

3. Using MainActor.run unnecessarily

// WRONG
await MainActor.run { self.data = data }

// CORRECT - annotate the function
@MainActor func loadData() async { self.data = await fetchData() }

4. Blocking the cooperative thread pool (violates runtime contract)

Never use DispatchSemaphore, DispatchGroup.wait(), or condition variables in async code.

Why: These primitives hide dependencies from the runtime. The cooperative thread pool has a contract that threads will always make forward progress. Blocking primitives violate this contract and can cause deadlock.

// ❌ DANGEROUS: Can deadlock the cooperative pool
let semaphore = DispatchSemaphore(value: 0)
Task {
    await doWork()
    semaphore.signal()
}
semaphore.wait()  // Thread blocked, runtime unaware

// ✅ Use async/await instead
let result = await doWork()

Debug tip: Set LIBDISPATCH_COOPERATIVE_POOL_STRICT=1 to catch blocking calls during development.

5. Creating unnecessary Tasks

// WRONG - unstructured
Task { await fetchUsers() }
Task { await fetchPosts() }

// CORRECT - structured concurr

---

*Content truncated.*