Swift 6 Concurrency Guide

Purpose: Progressive journey from single-threaded to concurrent Swift code Swift Version: Swift 6.3 (strict concurrency by default). @concurrent requires Swift 6.2+. iOS Version: iOS 17+ (iOS 26+ for @concurrent) Xcode: Xcode 16+ (Xcode 26+ for @concurrent)

When to Use This Skill

✅ Use this skill when:

• Starting a new project and deciding concurrency strategy
• Debugging Swift 6 concurrency errors (actor isolation, data races, Sendable warnings)
• Deciding when to introduce async/await vs concurrency
• Implementing @MainActor classes or async functions
• Converting delegate callbacks to async-safe patterns
• Deciding between @MainActor, nonisolated, @concurrent, or actor isolation
• Resolving "Sending 'self' risks causing data races" errors
• Making types conform to Sendable
• Offloading CPU-intensive work to background threads
• UI feels unresponsive and profiling shows main thread bottleneck

❌ Do NOT use this skill for:

• General Swift syntax (use Swift documentation)
• SwiftUI-specific patterns (use axiom-swiftui-debugging or axiom-swiftui-performance)
• API-specific patterns (use API documentation)

Core Philosophy: Think in Isolation Domains, Not Threads

"Your apps should start by running all of their code on the main thread, and you can get really far with single-threaded code." — Apple

Stop asking: "What thread should this run on?" Start asking: "What isolation domain should own this work?"

• @MainActor → UI state ownership
• Custom actor → shared mutable state ownership
• nonisolated → no ownership, caller decides
• @concurrent → force background execution

Async does not mean background. An async function suspends without blocking, but resumes on the same actor it was called from. A @MainActor async function runs entirely on the main actor — await just yields control, it does not switch threads. Use @concurrent (Swift 6.2+) when you need to force work off the calling actor.

Prefer structured concurrency. Use async let and TaskGroup for parallel work — they propagate cancellation and errors automatically through the task tree. Unstructured Task {} is for bridging sync→async boundaries (event handlers, SwiftUI .task). Task.detached is a last resort.

GCD is a bridge pattern, not a default. In new code, do not use DispatchQueue, DispatchGroup, DispatchSemaphore, or completion handlers as primary architecture. Use them only to bridge legacy APIs that don't have async alternatives yet. Isolate bridge code and keep the rest of the codebase idiomatic Swift 6.

The Progressive Journey

Single-Threaded → Asynchronous → Concurrent → Actors
     ↓                ↓             ↓           ↓
   Start here    Hide latency   Background   Move data
                 (network)      CPU work     off main

When to advance:

1. Stay single-threaded if UI is responsive and operations are fast
2. Add async/await when high-latency operations (network, file I/O) block UI
3. Add concurrency when CPU-intensive work (image processing, parsing) freezes UI
4. Add actors when too much main actor code causes contention

Key insight: Concurrent code is more complex. Only introduce concurrency when profiling shows it's needed.

---

Step 1: Single-Threaded Code (Start Here)

With Main Actor Mode enabled (the default for new projects in Xcode 26+), all code runs on the main thread unless explicitly marked otherwise.

// ✅ Simple, single-threaded
class ImageModel {
    var imageCache: [URL: Image] = [:]

    func fetchAndDisplayImage(url: URL) throws {
        let data = try Data(contentsOf: url)  // Reads local file
        let image = decodeImage(data)
        view.displayImage(image)
    }

    func decodeImage(_ data: Data) -> Image {
        // Decode image data
        return Image()
    }
}

Main Actor Mode (Xcode 26+)

• Enabled by default for new projects
• All code protected by @MainActor unless explicitly marked otherwise
• Access shared state safely without worrying about concurrent access

Build Setting (Xcode 26+)

Build Settings → Swift Compiler — Language
→ "Default Actor Isolation" = Main Actor

Build Settings → Swift Compiler — Upcoming Features
→ "Approachable Concurrency" = Yes

When this is enough: If all operations are fast (<16ms for 60fps), stay single-threaded!

---

Step 2: Asynchronous Tasks (Hide Latency)

Add async/await when waiting on data (network, file I/O) would freeze UI.

Problem: Network Access Blocks UI

// ❌ Blocks main thread until network completes
func fetchAndDisplayImage(url: URL) throws {
    let data = try Data(contentsOf: url)  // ❌ Synchronous network fetch, freezes UI!
    let image = decodeImage(data)
    view.displayImage(image)
}

Solution: Async/Await

// ✅ Suspends without blocking main thread
func fetchAndDisplayImage(url: URL) async throws {
    let (data, _) = try await URLSession.shared.data(from: url)  // ✅ Suspends here
    let image = decodeImage(data)  // ✅ Resumes here when data arrives
    view.displayImage(image)
}

What happens:

1. Function starts on main thread
2. await suspends function without blocking main thread
3. URLSession fetches data on background thread (library handles this)
4. Function resumes on main thread when data arrives
5. UI stays responsive the entire time

Task Creation

Create tasks in response to user events:

class ImageModel {
    var url: URL = URL(string: "https://swift.org")!

    func onTapEvent() {
        Task {  // ✅ Create task for user action
            do {
                try await fetchAndDisplayImage(url: url)
            } catch {
                displayError(error)
            }
        }
    }
}

Task Interleaving (Important Concept)

Multiple async tasks can run on the same thread by taking turns:

Task 1: [Fetch Image] → (suspend) → [Decode] → [Display]
Task 2: [Fetch News]  → (suspend) → [Display News]

Main Thread Timeline:
[Fetch Image] → [Fetch News] → [Decode Image] → [Display Image] → [Display News]

Benefits:

• Main thread never sits idle
• Tasks make progress as soon as possible
• No concurrency yet—still single-threaded!

Critical: Both tasks above run on the main actor. The await keyword suspends the task and frees the thread, but when the task resumes, it returns to the same isolation domain (main actor). No background thread is involved unless the awaited API (like URLSession) handles that internally.

When to use tasks:

• High-latency operations (network, file I/O)
• Library APIs handle background work for you (URLSession, FileManager)
• Your own code stays on main thread

---

Step 3: Concurrent Code (Background Threads)

Add concurrency when CPU-intensive work blocks UI.

Problem: Decoding Blocks UI

Profiling shows decodeImage() takes 200ms, causing UI glitches:

func fetchAndDisplayImage(url: URL) async throws {
    let (data, _) = try await URLSession.shared.data(from: url)
    let image = decodeImage(data)  // ❌ 200ms on main thread!
    view.displayImage(image)
}

Solution 1: @concurrent Attribute (Swift 6.2+)

Forces function to always run on background thread:

func fetchAndDisplayImage(url: URL) async throws {
    let (data, _) = try await URLSession.shared.data(from: url)
    let image = await decodeImage(data)  // ✅ Runs on background thread
    view.displayImage(image)
}

@concurrent
func decodeImage(_ data: Data) async -> Image {
    // ✅ Always runs on background thread pool
    // Good for: image processing, file I/O, parsing
    return Image()
}

What @concurrent does:

• Function always switches to background thread pool
• Compiler highlights main actor data access (shows what you need to fix)
• Cannot access @MainActor properties without await

Requirements: Swift 6.2+, Xcode 26+, iOS 26+

Solution 2: nonisolated (Library APIs)

If providing a general-purpose API, use nonisolated instead:

// ✅ Stays on caller's actor
nonisolated
func decodeImage(_ data: Data) -> Image {
    // Runs on whatever actor called it
    // Main actor → stays on main actor
    // Background → stays on background
    return Image()
}

When to use nonisolated:

• Library APIs where caller decides where work happens
• Small operations that might be OK on main thread
• General-purpose code used in many contexts

When to use @concurrent:

• Operations that should always run on background (image processing, parsing)
• Performance-critical work that shouldn't block UI

Breaking Ties to Main Actor

When you mark a function @concurrent, compiler shows main actor access: