Overview

• a documented safety invariant
• a follow-up ticket to remove or migrate it

Recommended Tools for Analysis

When analyzing Swift projects for concurrency issues:

1. Project Settings Discovery
   • Use Read on Package.swift for SwiftPM settings (tools version, strict concurrency flags, upcoming features)
   • Use Grep for SWIFT_STRICT_CONCURRENCY or SWIFT_DEFAULT_ACTOR_ISOLATION in .pbxproj files
   • Use Grep for SWIFT_UPCOMING_FEATURE_ to find enabled upcoming features

Project Settings Intake (Evaluate Before Advising)

Concurrency behavior depends on build settings. Always try to determine:

• Default actor isolation (is the module default @MainActor or nonisolated?)
• Strict concurrency checking level (minimal/targeted/complete)
• Whether upcoming features are enabled (especially NonisolatedNonsendingByDefault)
• Swift language mode (Swift 5.x vs Swift 6) and SwiftPM tools version

Manual checks (no scripts)

• SwiftPM:
  • Check Package.swift for .defaultIsolation(MainActor.self).
  • Check Package.swift for .enableUpcomingFeature("NonisolatedNonsendingByDefault").
  • Check for strict concurrency flags: .enableExperimentalFeature("StrictConcurrency=targeted") (or similar).
  • Check tools version at the top: // swift-tools-version: ...
• Xcode projects:
  • Search project.pbxproj for:
    • SWIFT_DEFAULT_ACTOR_ISOLATION
    • SWIFT_STRICT_CONCURRENCY
    • SWIFT_UPCOMING_FEATURE_ (and/or SWIFT_ENABLE_EXPERIMENTAL_FEATURES)

If any of these are unknown, ask the developer to confirm them before giving migration-sensitive guidance.

Quick Decision Tree

When a developer needs concurrency guidance, follow this decision tree:

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”.
• SwiftLint async_without_await warning
  • Remove async if not required; if required by protocol/override/@concurrent, prefer narrow suppression over adding fake awaits. See references/linting.md.
• "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 (especially Swift 6.2 behavior changes)
• "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) and references/threading.md (default isolation)
• "Class property 'current' is unavailable from asynchronous contexts" (Thread APIs)
  • Use references/threading.md to avoid thread-centric debugging and rely on isolation + Instruments
• 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)

Core Patterns Reference

When to Use Each Concurrency Tool

async/await - Making existing synchronous code asynchronous

// Use for: Single asynchronous operations
func fetchUser() async throws -> User {
    try await networkClient.get("/user")
}

async let - Running multiple independent async operations in parallel

// Use for: Fixed number of parallel operations known at compile time
async let user = fetchUser()
async let posts = fetchPosts()
let profile = try await (user, posts)

Task - Starting unstructured asynchronous work

// Use for: Fire-and-forget operations, bridging sync to async contexts
Task {
    await updateUI()
}

Task Group - Dynamic parallel operations with structured concurrency

// Use for: Unknown number of parallel operations at compile time
await withTaskGroup(of: Result.self) { group in
    for item in items {
        group.addTask { await process(item) }
    }
}

Actor - Protecting mutable state from data races

// Use for: Shared mutable state accessed from multiple contexts
actor DataCache {
    private var cache: [String: Data] = [:]
    func get(_ key: String) -> Data? { cache[key] }
}

@MainActor - Ensuring UI updates on main thread

// Use for: View models, UI-related classes
@MainActor
class ViewModel: ObservableObject {
    @Published var data: String = ""
}

Common Scenarios

Scenario: Network request with UI update

Task { @concurrent in
    let data = try await fetchData() // Background
    await MainActor.run {
        self.updateUI(with: data) // Main thread
    }
}

Scenario: Multiple parallel network requests

async let users = fetchUsers()
async let posts = fetchPosts()
async let comments = fetchComments()
let (u, p, c) = try await (users, posts, comments)

Scenario: Processing array items in parallel

await withTaskGroup(of: ProcessedItem.self) { group in
    for item in items {
        group.addTask { await process(item) }
    }
    for await result in group {
        results.append(result)
    }
}

Swift 6 Migration Quick Guide

Key changes in Swift 6:

• Strict concurrency checking enabled by default
• Complete data-race safety at compile time
• Sendable requirements enforced on boundaries
• Isolation checking for all async boundaries

For detailed migration steps, see references/migration.md.

Swift 6.2+ Review Mode

Use when asked to review Swift Concurrency usage, improve concurrency compliance, or fix Swift concurrency compiler errors in a feature or file.

1. Triage the issue

• Capture the exact compiler diagnostics and the offending symbol(s).
• Check project concurrency settings: Swift language version (6.2+), strict concurrency level, and whether approachable concurrency (default actor isolation / main-actor-by-default) is enabled.
• Identify the current actor context (@MainActor, actor, nonisolated) and whether a default actor isolation mode is enabled.
• Confirm whether the code is UI-bound or intended to run off the main actor.

2. Apply the smallest safe fix

Prefer edits that preserve existing behavior while satisfying data-race safety.

Common fixes:

• UI-bound types: annotate the type or relevant members with @MainActor.
• Protocol conformance on main actor types: make the conformance isolated (e.g., extension Foo: @MainActor SomeProtocol).
• Global/static state: protect with @MainActor or move into an actor.
• Background work: move expensive work into a @concurrent async function on a nonisolated type or use an actor to guard mutable state.
• Sendable errors: prefer immutable/value types; add Sendable conformance only when correct; avoid @unchecked Sendable unless you can prove thread safety.

Swift 6.2+ Reference Files

• references/swift-6-2-concurrency.md — Swift 6.2 changes, patterns, and examples
• references/approachable-concurrency.md — when the project is opted into approachable concurrency mode
• references/swiftui-concurrency-tour-wwdc.md — SwiftUI-specific concurrency guidance

Reference Files

Load these files as needed for specific topics:

• async-await-basics.md - async/await syntax, execution order, async let, URLSession patterns
• tasks.md - Task lifecycle, cancellation, priorities, task groups, structured vs unstructured
• threading.md - Thread/task relationship, suspension points, isolation domains, nonisolated
• memory-management.md - Retain cycles in tasks, memory safety patterns
• actors.md - Actor isolation, @MainActor, global actors, reentrancy, custom executors, Mutex
• sendable.md - Sendable conformance, value/reference types, @unchecked, region isolation
• linting.md - Concurrency-focused lint rules and SwiftLint async_without_await
• async-sequences.md - AsyncSequence, AsyncStream, when to use vs regular async methods
• core-data.md - NSManagedObject sendability, custom executors, isolation conflicts
• performance.md - Profiling with Instruments, reducing suspension points, execution strategies
• testing.md - XCTest async patterns, Swift Testing, concurrency testing utilities
• migration.md - Swift 6 migration strategy, closure-to-async conversion, @preconcurrency, FRP migration

Best Practices Summary

1. Prefer structured concurrency - Use task groups over unstructured tasks when possible
2. Minimize suspension points - Keep actor-isolated sections small to reduce context switches
3. Use @MainActor judiciously - Only for truly UI-related code
4. Make types Sendable - Enable safe concurrent access by conforming to Sendable
5. Handle cancellation - Check Task.isCancelled in long-running operations
6. Avoid blocking - Never use semaphores or locks in async contexts
7. Test concurrent code - Use proper async test methods and consider timing issues

Verification Checklist (When You Change Concurrency Code)

• Confirm build settings (default isolation, strict concurrency, upcoming features) before interpreting diagnostics.
• After refactors:
  • Run tests, especially concurrency-sensitive ones (see references/testing.md).
  • If performance-related, verify with Instruments (see references/performance.md).
  • If lifetime-related, verify deinit/cancellation behavior (see references/memory-management.md).

Glossary

See references/glossary.md for quick definitions of core concurrency terms used across this skill.

Note: This skill is based on the comprehensive Swift Concurrency Course by Antoine van der Lee.