Fucking Approachable Swift Concurrency

Fucking Approachable
Swift Concurrency

Finally understand async/await, Tasks, and why the compiler keeps yelling at you.

Huge thanks to Matt Massicotte for making Swift concurrency understandable. Put together by Pedro Piñera, co-founder of Tuist. Found an issue? Open an issue or submit a PR.

Async Code: async/await

Most of what apps do is wait. Fetch data from a server - wait for the response. Read a file from disk - wait for the bytes. Query a database - wait for the results.

Before Swift's concurrency system, you'd express this waiting with callbacks, delegates, or Combine. They work, but nested callbacks get hard to follow, and Combine has a steep learning curve.

async/await gives Swift a new way to handle waiting. Instead of callbacks, you write code that looks sequential - it pauses, waits, and resumes. Under the hood, Swift's runtime manages these pauses efficiently. But making your app actually stay responsive while waiting depends on where code runs, which we'll cover later.

An async function is one that might need to pause. You mark it with async, and when you call it, you use await to say "pause here until this finishes":

func fetchUser(id: Int) async throws -> User {
    let url = URL(string: "https://api.example.com/users/\(id)")!
    let (data, _) = try await URLSession.shared.data(from: url)  // Suspends here
    return try JSONDecoder().decode(User.self, from: data)
}

// Calling it
let user = try await fetchUser(id: 123)
// Code here runs after fetchUser completes

Your code pauses at each await - this is called suspension. When the work finishes, your code resumes right where it left off. Suspension gives Swift the opportunity to do other work while waiting.

Waiting for them

What if you need to fetch several things? You could await them one by one:

let avatar = try await fetchImage("avatar.jpg")
let banner = try await fetchImage("banner.jpg")
let bio = try await fetchBio()

But that's slow - each waits for the previous one to finish. Use async let to run them in parallel:

func loadProfile() async throws -> Profile {
    async let avatar = fetchImage("avatar.jpg")
    async let banner = fetchImage("banner.jpg")
    async let bio = fetchBio()

    // All three are fetching in parallel!
    return Profile(
        avatar: try await avatar,
        banner: try await banner,
        bio: try await bio
    )
}

Each async let starts immediately. The await collects the results.

Managing Work: Tasks

A Task is a unit of async work you can manage. You've written async functions, but a Task is what actually runs them. It's how you start async code from synchronous code, and it gives you control over that work: wait for its result, cancel it, or let it run in the background.

Let's say you're building a profile screen. Load the avatar when the view appears using the .task modifier, which cancels automatically when the view disappears:

struct ProfileView: View {
    @State private var avatar: Image?

    var body: some View {
        avatar
            .task { avatar = await downloadAvatar() }
    }
}

If users can switch between profiles, use .task(id:) to reload when the selection changes:

struct ProfileView: View {
    var userID: String
    @State private var avatar: Image?

    var body: some View {
        avatar
            .task(id: userID) { avatar = await downloadAvatar(for: userID) }
    }
}

When the user taps "Save", create a Task manually:

Button("Save") {
    Task { await saveProfile() }
}

Accessing Task Results

When you create a Task, you get a handle back. Use .value to wait for and retrieve the result:

let handle = Task {
    return await fetchUserData()
}
let userData = await handle.value  // Suspends until task completes

This is useful when you need the result later, or when you want to store the task handle and await it elsewhere.

What if you need to load the avatar, bio, and stats all at once? Use a TaskGroup to fetch them in parallel:

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

Tasks inside a group are child tasks, linked to the parent. A few things to know:

• Cancellation propagates: cancel the parent, and all children get cancelled too
• Errors: a thrown error cancels siblings and rethrows, but only when you consume results with next(), waitForAll(), or iteration
• Completion order: results arrive as tasks finish, not the order you added them
• Waits for all: the group doesn't return until every child completes or is cancelled

This is structured concurrency: work organized in a tree that's easy to reason about and clean up.

Where Things Run: From Threads to Isolation Domains

So far we've talked about when code runs (async/await) and how to organize it (Tasks). Now: where does it run, and how do we keep it safe?

The Old World: Many Options, No Safety

Before Swift's concurrency system, you had several ways to manage execution:

All of these worked, but safety was entirely on you. The compiler couldn't help if you forgot to dispatch to main, or if two queues accessed the same data simultaneously.

The Problem: Data Races

A data race happens when two threads access the same memory at the same time, and at least one is writing:

var count = 0

DispatchQueue.global().async { count += 1 }
DispatchQueue.global().async { count += 1 }

// Undefined behavior: crash, memory corruption, or wrong value

Data races are undefined behavior. They can crash, corrupt memory, or silently produce wrong results. Your app works fine in testing, then crashes randomly in production. Traditional tools like locks and semaphores help, but they're manual and error-prone.

The Shift: From Threads to Isolation

Swift's concurrency model asks a different question. Instead of "which thread should this run on?", it asks: "who is allowed to access this data?"

This is isolation. Rather than manually dispatching work to threads, you declare boundaries around data. The compiler enforces these boundaries at build time, not runtime.

The Three Isolation Domains

1. MainActor

@MainActor is a global actor that represents the main thread's isolation domain. It's special because UI frameworks (UIKit, AppKit, SwiftUI) require main thread access.

@MainActor
class ViewModel {
    var items: [Item] = []  // Protected by MainActor isolation
}

When you mark something @MainActor, you're not saying "dispatch this to the main thread." You're saying "this belongs to the main actor's isolation domain." The compiler enforces that anything accessing it must either be on MainActor or await to cross the boundary.

2. Actors

An actor protects its own mutable state. It guarantees that only one piece of code can access its data at a time:

actor BankAccount {
    var balance: Double = 0

    func deposit(_ amount: Double) {
        balance += amount  // Safe: actor guarantees exclusive access
    }
}

// From outside, you must await to cross the boundary
await account.deposit(100)

Actors are not threads. An actor is an isolation boundary. The Swift runtime decides which thread actually executes actor code. You don't control that, and you don't need to.

3. Nonisolated

Code marked nonisolated opts out of actor isolation. It can be called from anywhere without await, but it cannot access the actor's protected state:

actor BankAccount {
    var balance: Double = 0

    nonisolated func bankName() -> String {
        "Acme Bank"  // No actor state accessed, safe to call from anywhere
    }
}

let name = account.bankName()  // No await needed

// Runs on MainActor (the default)
func updateUI() async { }

// Runs on background thread (opt-in)
@concurrent func processLargeFile() async { }

What Can Cross Isolation Domains: Sendable

Isolation domains protect data, but eventually you need to pass data between them. When you do, Swift checks if it's safe.

Think about it: if you pass a reference to a mutable class from one actor to another, both actors could modify it simultaneously. That's exactly the data race we're trying to prevent. So Swift needs to know: can this data be safely shared?

The answer is the Sendable protocol. It's a marker that tells the compiler "this type is safe to pass across isolation boundaries":

• Sendable types can cross safely (value types, immutable data, actors)
• Non-Sendable types can't (classes with mutable state)

// Sendable - it's a value type, each place gets a copy
struct User: Sendable {
    let id: Int
    let name: String
}

// Non-Sendable - it's a class with mutable state
class Counter {
    var count = 0  // Two places modifying this = disaster
}

Making Types Sendable

Swift automatically infers Sendable for many types:

• Structs and enums with only Sendable properties are implicitly Sendable
• Actors are always Sendable because they protect their own state
• @MainActor types are Sendable because MainActor serializes access

For classes, it's harder. A class can conform to Sendable only if it's final and all its stored properties are immutable:

final class APIConfig: Sendable {
    let baseURL: URL      // Immutable
    let timeout: Double   // Immutable
}

If you have a class that's thread-safe through other means (locks, atomics), you can use @unchecked Sendable to tell the compiler "trust me":

final class ThreadSafeCache: @unchecked Sendable {
    private let lock = NSLock()
    private var storage: [String: Data] = [:]
}

How Isolation Is Inherited

You've seen that isolation domains protect data, and Sendable controls what crosses between them. But how does code end up in an isolation domain in the first place?

When you call a function or create a closure, isolation flows through your code. With Approachable Concurrency, your app starts on MainActor, and that isolation propagates to the code you call, unless something explicitly changes it. Understanding this flow helps you predict where code runs and why the compiler sometimes complains.

Function Calls

When you call a function, its isolation determines where it runs:

@MainActor func updateUI() { }      // Always runs on MainActor
func helper() { }                    // Inherits caller's isolation
@concurrent func crunch() async { }  // Explicitly runs off-actor

With Approachable Concurrency, most of your code inherits MainActor isolation. The function runs where the caller runs, unless it explicitly opts out.

Closures

Closures inherit isolation from the context where they're defined:

@MainActor
class ViewModel {
    func setup() {
        let closure = {
            // Inherits MainActor from ViewModel
            self.updateUI()  // Safe, same isolation
        }
        closure()
    }
}

This is why SwiftUI's Button action closures can safely update @State: they inherit MainActor isolation from the view.

Tasks

A Task { } inherits actor isolation from where it's created:

@MainActor
class ViewModel {
    func doWork() {
        Task {
            // Inherits MainActor isolation
            self.updateUI()  // Safe, no await needed
        }
    }
}

This is usually what you want. The task runs on the same actor as the code that created it.

Breaking Inheritance: Task.detached

Sometimes you want a task that doesn't inherit any context:

@MainActor
class ViewModel {
    func doHeavyWork() {
        Task.detached {
            // No actor isolation, runs on cooperative pool
            let result = await self.expensiveCalculation()
            await MainActor.run {
                self.data = result  // Explicitly hop back
            }
        }
    }
}

Preserving Isolation in Async Utilities

Sometimes you write a generic async function that accepts a closure - a wrapper, a retry helper, a transaction scope. The caller passes a closure, your function runs it. Simple, right?

func measure<T>(
    _ label: String,
    block: () async throws -> T
) async rethrows -> T {
    let start = ContinuousClock.now
    let result = try await block()
    print("\(label): \(ContinuousClock.now - start)")
    return result
}

But when you call this from a @MainActor context, Swift complains:

Sending value of non-Sendable type '() async throws -> T' risks causing data races

What's happening? Your closure captures state from MainActor, but measure is nonisolated. Swift sees a non-Sendable closure crossing an isolation boundary - exactly what it's designed to prevent.

The simplest fix is nonisolated(nonsending). This tells Swift the function should stay on whatever executor called it:

nonisolated(nonsending)
func measure<T>(
    _ label: String,
    block: () async throws -> T
) async rethrows -> T {
    let start = ContinuousClock.now
    let result = try await block()
    print("\(label): \(ContinuousClock.now - start)")
    return result
}

Now the entire function runs on the caller's executor. Call it from MainActor, it stays on MainActor. Call it from a custom actor, it stays there. The closure never crosses an isolation boundary, so no Sendable check is needed.

If you do need explicit access to the actor, use an #isolation parameter instead:

func measure<T>(
    isolation: isolated (any Actor)? = #isolation,
    _ label: String,
    block: () async throws -> T
) async rethrows -> T {
    let start = ContinuousClock.now
    let result = try await block()
    print("\(label): \(ContinuousClock.now - start)")
    return result
}

Both approaches are essential for building async utilities that feel natural to use. Without them, callers would need to make their closures @Sendable or jump through hoops to satisfy the compiler.

Putting It All Together

Let's step back and see how all the pieces fit.

Swift Concurrency can feel like a lot of concepts: async/await, Task, actors, MainActor, Sendable, isolation domains. But there's really just one idea at the center of it all: isolation is inherited by default.

With Approachable Concurrency enabled, your app starts on MainActor. That's your starting point. From there:

• Every function you call inherits that isolation
• Every closure you create captures that isolation
• Every Task { } you spawn inherits that isolation

You don't have to annotate anything. You don't have to think about threads. Your code runs on MainActor, and the isolation just propagates through your program automatically.

When you need to break out of that inheritance, you do it explicitly:

• @concurrent says "run this on a background thread"
• actor says "this type has its own isolation domain"
• Task.detached { } says "start fresh, inherit nothing"

And when you pass data between isolation domains, Swift checks that it's safe. That's what Sendable is for: marking types that can safely cross boundaries.

That's it. That's the whole model:

1. Isolation propagates from MainActor through your code
2. You opt out explicitly when you need background work or separate state
3. Sendable guards the boundaries when data crosses between domains

When the compiler complains, it's telling you one of these rules was violated. Trace the inheritance: where did the isolation come from? Where is the code trying to run? What data is crossing a boundary? The answer is usually obvious once you ask the right question.

Where to Go From Here

The good news: you don't need to master everything at once.

Most apps only need the basics. Mark your ViewModels with @MainActor, use async/await for network calls, and create Task { } when you need to kick off async work from a button tap. That's it. That handles 80% of real-world apps. The compiler will tell you if you need more.

When you need parallel work, reach for async let to fetch multiple things at once, or TaskGroup when the number of tasks is dynamic. Learn to handle cancellation gracefully. This covers apps with complex data loading or real-time features.

Advanced patterns come later, if ever. Custom actors for shared mutable state, @concurrent for CPU-intensive processing, deep Sendable understanding. This is framework code, server-side Swift, complex desktop apps. Most developers never need this level.

Watch Out: Common Mistakes

Thinking async = background

// This STILL blocks the main thread!
@MainActor
func slowFunction() async {
    let result = expensiveCalculation()  // Synchronous work = blocking
    data = result
}

async means "can pause." The actual work still runs wherever it runs. Use @concurrent (Swift 6.2) or Task.detached for CPU-heavy work.

Creating too many actors

// Over-engineered
actor NetworkManager { }
actor CacheManager { }
actor DataManager { }

// Better - most things can live on MainActor
@MainActor
class AppState { }

You need a custom actor only when you have shared mutable state that can't live on MainActor. Matt Massicotte's rule: introduce an actor only when (1) you have non-Sendable state, (2) operations on that state must be atomic, and (3) those operations can't run on an existing actor. If you can't justify it, use @MainActor instead.

Making everything Sendable

Not everything needs to cross boundaries. If you're adding @unchecked Sendable everywhere, step back and ask if the data actually needs to move between isolation domains.

Using MainActor.run when you don't need it

// Unnecessary
Task {
    let data = await fetchData()
    await MainActor.run {
        self.data = data
    }
}

// Better - just make the function @MainActor
@MainActor
func loadData() async {
    self.data = await fetchData()
}

MainActor.run is rarely the right solution. If you need MainActor isolation, annotate the function with @MainActor instead. It's clearer and the compiler can help you more. See Matt's take on this.

Blocking the cooperative thread pool

// NEVER do this - risks deadlock
func badIdea() async {
    let semaphore = DispatchSemaphore(value: 0)
    Task {
        await doWork()
        semaphore.signal()
    }
    semaphore.wait()  // Blocks a cooperative thread!
}

Swift's cooperative thread pool has limited threads. Blocking one with DispatchSemaphore, DispatchGroup.wait(), or similar calls can cause deadlocks. If you need to bridge sync and async code, use async let or restructure to stay fully async.

func doWork() async {

    // this will return when all subtasks return, throw an error, or are cancelled
    let result = try await withThrowingTaskGroup() { group in 
        group.addTask {
            try await self.performAsyncOperation1()  
        }
        group.addTask {
            try await self.performAsyncOperation2()  
        }
        // wait for and collect the results of the tasks here 
    }
}

func performAsyncOperation1() async throws -> Int {
    return 1
}
func performAsyncOperation2() async throws -> Int {
    return 2
}

var sum = 0
for await result in group {
    sum += result
}
// sum == 3 

struct ContentView: View {
    
    @State private var shouldLoadImage = false
    
    var body: some View {
        Button("Click Me !") {
            // toggle the flag
            shouldLoadImage = !shouldLoadImage
        }
        // the View manages the subtask
        // it starts before the view is displayed 
        // and stops when the view is hidden
        .task(id: shouldLoadImage) {
            // when the flag value changes, SwiftUI restarts the task
            guard shouldLoadImage else { return }
            await loadImage()
        }
    }
}

Cheat Sheet: Quick Reference

Further Reading

AI Agent Skill

Want your AI coding assistant to understand Swift Concurrency? We provide a SKILL.md file that packages these mental models for AI agents like Claude Code, Codex, Amp, OpenCode, and others.

Other skills

• Antoine's open-sourced Swift Concurrency Agent Skill

How to Use

Choose your agent and run the commands below:

# Personal skill (all your projects)
mkdir -p ~/.claude/skills/swift-concurrency
curl -o ~/.claude/skills/swift-concurrency/SKILL.md https://fuckingapproachableswiftconcurrency.com/SKILL.md
# Project skill (just this project)
mkdir -p .claude/skills/swift-concurrency
curl -o .claude/skills/swift-concurrency/SKILL.md https://fuckingapproachableswiftconcurrency.com/SKILL.md

# Project instructions (recommended)
curl -o AGENTS.md https://fuckingapproachableswiftconcurrency.com/SKILL.md

# Global instructions (all your projects)
curl -o ~/.codex/AGENTS.md https://fuckingapproachableswiftconcurrency.com/SKILL.md
# Project instructions (just this project)
curl -o AGENTS.md https://fuckingapproachableswiftconcurrency.com/SKILL.md

# Global rules (all your projects)
mkdir -p ~/.kiro/steering
curl -o ~/.kiro/steering/swift-concurrency.md https://fuckingapproachableswiftconcurrency.com/SKILL.md
# Project rules (just this project)
mkdir -p .kiro/steering
curl -o .kiro/steering/swift-concurrency.md https://fuckingapproachableswiftconcurrency.com/SKILL.md

# Global rules (all your projects)
mkdir -p ~/.config/opencode
curl -o ~/.config/opencode/AGENTS.md https://fuckingapproachableswiftconcurrency.com/SKILL.md
# Project rules (just this project)
curl -o AGENTS.md https://fuckingapproachableswiftconcurrency.com/SKILL.md

The skill includes the Office Building analogy, isolation patterns, Sendable guidance, common mistakes, and quick reference tables. Your agent will use this knowledge automatically when you work with Swift Concurrency code.