Swift Concurrency Patterns

Swift Concurrency Patterns

When to Use

Use this skill when:

• The user asks how to structure async/await code in Swift 5.5+ to avoid data races, deadlocks, or excessive thread creation
• The user wants to migrate from GCD (Grand Central Dispatch) or DispatchQueue-based code to the Swift concurrency model (actors, async/await, structured concurrency)
• The user needs to decide between async let, TaskGroup, Actor, @MainActor, or Sendable for a specific iOS/macOS problem
• The user is debugging concurrency bugs such as purple runtime warnings about main thread violations, Task cancellation not propagating, or unexpected re-entrancy in actor-isolated code
• The user wants to interop between legacy Objective-C callbacks or Combine publishers and the Swift concurrency system
• The user needs to implement a producer/consumer pipeline, a cache with concurrent reads, or a background data-sync task in a Swift application
• The user asks about AsyncSequence, AsyncStream, or continuation-based bridging with UIKit/AppKit delegate patterns

Do NOT use this skill when:

• The user is asking about Combine-specific operators (.map, .flatMap, .merge) without any Swift concurrency involvement -- use a Combine-specific skill instead
• The user needs RxSwift, ReactiveSwift, or other reactive library patterns -- those have different execution models
• The user is working in Swift for server-side (SwiftNIO, Vapor event-loop threading model) where actor isolation rules interact differently with NIO's EventLoop -- those require a server-side Swift skill
• The user needs general iOS architecture patterns (MVVM, TCA, VIPER) without a concurrency component -- use an iOS architecture skill
• The user is asking about Objective-C threading (NSThread, NSOperationQueue) in a purely Objective-C codebase
• The user needs help with GPU/Metal compute shaders or parallel numerical processing -- that is a separate rendering/compute domain
• The user is asking about Python, Kotlin, or Rust async runtimes -- those use fundamentally different concurrency models

Process

1. Diagnose the Concurrency Problem Category

Before recommending any pattern, classify the problem. Swift concurrency has distinct tools for distinct problems, and choosing the wrong primitive causes subtle bugs.

• Fire-and-forget background work (e.g., prefetching, analytics) -- use an unstructured Task attached to a view or controller lifetime
• Parallel decomposition of known work (e.g., downloading 20 images in parallel, then aggregating) -- use async let for 2--5 items or withTaskGroup / withThrowingTaskGroup for dynamic counts
• Shared mutable state (e.g., a cache, a counter, a rate limiter) -- use an actor; decide whether @MainActor isolation or a custom actor is appropriate
• Streaming/event sequences (e.g., CoreLocation updates, URLSession byte streams, timer ticks) -- use AsyncStream or AsyncThrowingStream
• Bridging callbacks (e.g., URLSession completion handlers, CLLocationManager delegate) -- use withCheckedContinuation or withCheckedThrowingContinuation
• Child task coordination with cancellation -- use structured concurrency (TaskGroup) so cancellation propagates automatically

Identify which category applies before proceeding. A single request may span multiple categories.

2. Audit the Execution Context

Swift concurrency's correctness depends heavily on knowing which actor context code runs in. Mistakes here cause purple runtime warnings and data races.

• Identify all types that must run on the main thread (UIKit views, UIViewController, SwiftUI view models using @Published) -- annotate them @MainActor
• For @MainActor-isolated types, recognize that await-ing non-isolated async functions will switch off the main thread; switching back requires either another await or calling via MainActor.run {}
• Check whether a class conforms to Sendable. If a type crosses actor boundaries, it must be Sendable -- value types with only Sendable stored properties are implicitly Sendable; reference types must mark conformance explicitly and carefully
• Enable -strict-concurrency=complete in the Swift compiler flags (OTHER_SWIFT_FLAGS in Xcode build settings) to surface all Sendable and isolation violations as errors -- do this in a dedicated CI build target even if the main target uses minimal or targeted
• Map the critical path: if a user-facing action triggers async work, every await suspension point is a place where the UI can change state; plan for this explicitly

3. Select the Right Concurrency Primitive

Apply this decision framework in order:

For parallelism (doing multiple things at once):

• 2--4 statically known parallel tasks: use async let -- compiles to a child task per binding, automatic cancellation on scope exit
• 5+ tasks or dynamically sized collections: use withTaskGroup(of:) for non-throwing work, withThrowingTaskGroup(of:) for throwing work; always iterate results inside the group body using for await result in group to avoid task accumulation
• Unordered result collection where ordering does not matter: addTaskUnlessCancelled inside the group loop lets you bail cleanly when the parent task is cancelled

For shared state:

• Mutable state accessed from multiple tasks: actor -- guarantates serial access without explicit locking
• High-read, low-write state that does not need mutation (configuration, lookup tables): use a struct passed as a Sendable value; avoid actor overhead on read-heavy paths
• Main-thread-bound state (view models, UI controllers): @MainActor class -- the compiler enforces isolation; nonisolated marks functions that can run off the main thread
• Global singletons: use a global actor (@globalActor) only when you need a single shared executor across multiple types; avoid overusing this pattern as it creates a hidden serialization point

For streaming:

• Push-based event source (delegate, callback): wrap in AsyncStream { continuation in ... } -- store the continuation; call continuation.yield(value) from the callback; call continuation.finish() on teardown
• Backpressure-sensitive streaming: use AsyncStream with a bufferingPolicy of .bufferingNewest(n) or .bufferingOldest(n) to avoid unbounded memory growth; .unbounded is only safe when the producer is slower than the consumer
• Transforming an existing AsyncSequence: use .map, .filter, .compactMap from the standard library; for custom transformations, implement the AsyncSequence protocol with an AsyncIteratorProtocol

For task lifecycle:

• Work tied to a SwiftUI view: use .task {} modifier -- automatically cancelled when the view disappears
• Work tied to a UIViewController: create a Task in viewDidAppear and cancel it in viewDidDisappear or deinit; store the task in a var task: Task<Void, Never>? property
• Background work that must complete even if the UI disappears (e.g., uploading a photo): use URLSession background sessions, not a detached Task -- the OS can terminate the app

4. Implement Actor Isolation Correctly

Actor isolation is the most commonly misunderstood part of Swift concurrency. Get this right before writing any actor code.

• Actors serialize access: only one piece of code runs at a time inside an actor's executor; there is no need for DispatchQueue serial queues or NSLock inside an actor
• Actor nonisolated methods run on the caller's executor -- use nonisolated for pure functions (computations, formatting, encoding) that do not touch actor state; this avoids unnecessary hops to the actor's executor
• Actor re-entrancy: when an actor calls await on an external function, another caller can enter the actor; always re-validate state after any await inside an actor -- do not assume state is unchanged across a suspension point
• To batch multiple state reads/writes atomically, perform them all synchronously within a single actor-isolated method; do not interleave await calls between dependent reads
• actor vs. class with a lock: actors provide compile-time isolation guarantees; a class with NSLock or os_unfair_lock provides runtime protection only; prefer actors for new code; when interoping with legacy lock-based code, use actors as a wrapper

Example of re-entrancy bug to avoid:

actor BankAccount {
    var balance: Double = 0

    // WRONG: balance could be read twice before either write completes
    func transfer(amount: Double, to other: BankAccount) async {
        let current = balance  // reads balance
        await other.deposit(amount) // suspension point -- re-entrancy possible
        balance = current - amount  // may operate on stale value
    }

    // CORRECT: validate after await
    func transfer(amount: Double, to other: BankAccount) async throws {
        guard balance >= amount else { throw TransferError.insufficientFunds }
        balance -= amount  // deduct before suspending
        await other.deposit(amount)
    }
}

5. Handle Task Cancellation Explicitly

Swift's cooperative cancellation model requires code to check for cancellation -- it does not stop a task forcibly.

• Call try Task.checkCancellation() at natural suspension points in long loops or after network calls; this throws CancellationError if the task is cancelled
• Use Task.isCancelled (a Boolean) for non-throwing contexts where you want to exit gracefully rather than throw
• When implementing AsyncSequence, yield nil (finishing the sequence) when the iteration task is cancelled; do not continue producing values into a cancelled context
• withTaskCancellationHandler(operation:onCancel:) lets you register a synchronous cleanup callback that runs immediately on cancellation -- use this to cancel underlying URLSession data tasks, close file handles, or stop CLLocationManager updates
• TaskGroup cancels all child tasks automatically when any child throws -- this is the correct behavior for "fail fast" semantics; if you want "collect all results including errors", use withThrowingTaskGroup and catch errors inside the child task body before they propagate

6. Bridge Legacy APIs Safely

Most real Swift projects have existing GCD, delegation, and callback-based code that must interoperate with async/await.

• Completion handlers to async: use withCheckedContinuation (non-throwing) or withCheckedThrowingContinuation (throwing); "checked" variants assert that the continuation is resumed exactly once -- a double-resume or missing resume will produce a runtime warning or crash in debug builds
• Unsafe continuations: withUnsafeContinuation skips the double-resume check; only use this in performance-critical paths where profiling shows the overhead of the check is measurable (it is almost never necessary)
• Delegate-based APIs (CLLocationManager, AVAudioSession): wrap with AsyncStream; the delegate stores the continuation and yields values; ensure the AsyncStream is properly terminated when the delegate receives a terminal event
• NotificationCenter: use NotificationCenter.default.notifications(named:) which returns an AsyncSequence since iOS 15 -- do not wrap this in a custom AsyncStream
• Combine to AsyncSequence: use .values on any Publisher (available since iOS 15) -- somePublisher.values is an AsyncSequence you can iterate with for await
• Mixing DispatchQueue with async: calling DispatchQueue.main.async {} inside a @MainActor async function is redundant and potentially harmful; use await MainActor.run {} instead when you must explicitly switch to the main actor from a different context

7. Test and Validate Concurrency

Concurrency bugs are non-deterministic. Standard XCTest techniques must be supplemented.

• Enable the Swift Concurrency runtime checks in the scheme: "Thread Performance Checker" (SWIFT_ASYNC_DEBUG=1) and "Main Thread Checker" in the Diagnostics tab -- these surface actor isolation violations at runtime
• Enable Thread Sanitizer (TSan) on test targets to detect data races in code not yet migrated to actors -- TSan cannot catch actor-isolation violations but catches raw memory races in nonisolated code
• Use XCTestExpectation with expectation.fulfill() inside async tasks; call await fulfillment(of: [expectation], timeout: 5.0) instead of waitForExpectations for native async test support (Xcode 14.3+)
• Write deterministic tests by injecting a Clock conformance -- use ContinuousClock for real time and TestClock (from the swift-clocks library) for controlled time in unit tests; Task.sleep(for:clock:) accepts a Clock parameter
• Test cancellation explicitly: create a Task, cancel it immediately, then await the task's value; assert that the expected CancellationError was thrown or that the task exited at the correct checkpoint

8. Optimize for Performance

Swift concurrency is not automatically faster than GCD. Apply these benchmarks and decisions deliberately.

• The Swift concurrency runtime uses a cooperative thread pool sized to the number of CPU cores; creating thousands of tasks is safe (unlike threads), but each task has overhead (~heap allocation for the task object); batch small units of work into fewer, larger tasks
• actor method dispatch has measurable overhead (~50--100ns per hop in benchmarks) compared to a direct function call; for hot paths that call actor methods in tight loops, expose a nonisolated function that takes a snapshot of actor state, does the computation, and writes back once
• Avoid MainActor as a catchall for synchronization -- it is a single serial executor; pushing work there unnecessarily starves the UI rendering loop; keep @MainActor to view-state updates only
• Profile with Instruments' "Swift Concurrency" template (Xcode 14+) -- it shows task creation, suspension counts, actor contention, and thread pool utilization; look for actors with high "enqueued" counts as indicators of bottlenecks
• Prefer value types (struct, enum) for data passed across task boundaries -- they require no reference counting, are implicitly Sendable when their stored properties are Sendable, and have zero synchronization overhead

Output Format

When responding to a user question about Swift concurrency patterns, structure output as follows:

## Swift Concurrency Analysis

### Problem Classification
- Category: [parallelism | shared state | streaming | bridging | lifecycle]
- Execution context: [main actor | custom actor | unstructured | structured]
- Swift/iOS minimum version required: [e.g., iOS 15 / Swift 5.7]

### Concurrency Primitive Decision

| Requirement | Primitive | Rationale |
|---|---|---|
| [requirement 1] | [async let / TaskGroup / actor / AsyncStream / continuation] | [specific reason] |
| [requirement 2] | [primitive] | [reason] |

### Recommended Pattern
[Name of pattern and one-line summary]

### Implementation

```swift
// Full, compilable Swift code with:
// - Correct actor isolation annotations
// - Explicit Sendable conformances where needed
// - Cancellation checkpoints
// - Error handling (throws / CancellationError)
// - No TODO placeholders -- every function is implemented

Cancellation Strategy

[How and where cancellation is checked or propagated]

Testing Approach

[Specific XCTest or Swift Testing framework techniques for validating this pattern]

Performance Considerations

[Specific latency, throughput, or memory trade-offs for this pattern in this context]

Migration Notes (if applicable)

[How to incrementally replace existing GCD/Combine/callback code with this pattern]

---

## Rules

1. **NEVER call `resume` on a continuation more than once** -- double-resuming a `CheckedContinuation` crashes the app in debug builds and causes undefined behavior in release builds; wrap the callback so only the first invocation calls resume, using a flag or by nulling out the continuation reference after use.

2. **NEVER block the cooperative thread pool** -- calling synchronous, blocking APIs (like `semaphore.wait()`, `Thread.sleep()`, or synchronous file I/O) inside an async function starves the thread pool because Swift concurrency cannot reclaim the thread; use `await Task.sleep(for:)` for delays and async file APIs for I/O.

3. **NEVER use `Task.detached` as the default way to create tasks** -- detached tasks inherit no actor context, no task-local values, and no priority from their creating context; use an unstructured `Task {}` (which inherits context) unless you explicitly need isolation from the parent.

4. **ALWAYS re-validate actor state after any `await` suspension point** -- actor re-entrancy means another caller may have mutated state between when you suspended and when you resumed; do not assume that a value read before `await` is still valid after `await`.

5. **NEVER annotate an entire class `@MainActor` to "fix" concurrency warnings** without understanding which methods actually require main-thread execution -- this serializes all work through the main actor, which degrades performance and blocks the UI thread on computation-heavy tasks.

6. **ALWAYS specify a `bufferingPolicy` when creating `AsyncStream`** -- the default `.unbounded` policy can cause unbounded memory growth if the producer is faster than the consumer; use `.bufferingNewest(1)` for live sensor data where only the latest value matters, or `.bufferingOldest(n)` for ordered queues.

7. **NEVER use `@unchecked Sendable` as a quick fix** -- this suppresses compiler checks without providing actual thread safety; use it only when you have manually verified thread safety through an external mechanism (e.g., a lock-protected class that has been audited), and always add a comment documenting the manual guarantee.

8. **ALWAYS cancel tasks stored as properties when their owner is deallocated** -- call `task?.cancel()` in `deinit` or `viewDidDisappear`; failing to do this causes tasks to outlive their owning objects, leading to crashes when the task accesses deallocated memory via a weak reference that has become nil.

9. **NEVER perform UI updates from outside `@MainActor`** -- even in Swift concurrency code, UIKit and SwiftUI mutations must happen on the main thread; always wrap view updates in `await MainActor.run {}` or mark the calling function `@MainActor`.

10. **ALWAYS prefer structured concurrency over unstructured tasks** when the tasks are logically children of the current operation -- structured concurrency (`async let`, `TaskGroup`) guarantees that child tasks are cancelled and awaited before the scope exits, preventing resource leaks; use `Task {}` only when the work is genuinely independent of the current task's lifecycle.

---

## Edge Cases

### Actors and Inheritance

Swift actors cannot be subclassed -- they are implicitly `final`. If you have existing class hierarchies that need actor-like isolation, you cannot simply change the base class to `actor`. Instead, extract the mutable state into a dedicated actor, inject it into each class via dependency injection, and have the classes delegate state mutations to the actor. Alternatively, use a protocol with `@MainActor` or a custom global actor annotation applied at the protocol level so all conforming types share the same isolation.

### Mixing Swift Concurrency with Objective-C Delegates

Many UIKit APIs use delegate callbacks (e.g., `UIImagePickerControllerDelegate`, `MKLocalSearchCompleter`). These callbacks often arrive on the main thread but are not annotated with `@MainActor` in the SDK because they predate Swift concurrency. Wrapping them in `AsyncStream` is correct, but you must ensure:
- The continuation's `yield` is called from within the correct actor context; add `MainActor.assumeIsolated {}` in iOS 17+ to satisfy the compiler without a full `await` hop
- The `AsyncStream` is finished on `imagePickerControllerDidCancel` or equivalent terminal delegate method; failure to finish the stream leaks the iterator
- The lifetime of the delegate object is tied to the stream's `onTermination` handler -- cancel the operation and set the delegate to nil when the stream terminates

### Priority Inversion

Swift concurrency has automatic priority escalation to address priority inversion, but it does not eliminate it entirely. If a low-priority background task holds a lock (e.g., inside a `nonisolated` method using `NSLock`) and a high-priority task is waiting on the same lock, the system cannot escalate priority for lock-based synchronization -- only actor contention benefits from priority escalation. In performance-sensitive code:
- Replace lock-based synchronization inside hot paths with actor-isolated state
- Use `Task(priority: .userInitiated)` explicitly for work that must complete before a visible UI update
- Profile with Instruments' "CPU Profiler" template looking for unexpectedly long "waiting for actor" intervals

### Recursive Actor Methods

Calling an actor-isolated method from within the same actor is allowed synchronously (no `await` needed from within the actor itself). However, calling `await self.someActorMethod()` from inside the same actor is legal but creates a suspension point, allowing re-entrancy. This pattern is subtle and dangerous:

```swift
actor Coordinator {
    var isProcessing = false

    func process() async {
        isProcessing = true
        await self.finalize()  // suspension point -- isProcessing can be read as true by another caller
        isProcessing = false
    }
}

Avoid awaiting self-referential actor calls. Extract shared logic into nonisolated helpers that take actor state as parameters, or restructure the code to avoid the suspension between dependent state reads and writes.

Sendable Closures Capturing Non-Sendable Types

When passing a closure to Task {} or TaskGroup.addTask {}, the closure must be @Sendable. This means any captured values must be Sendable. Common non-Sendable types that get captured: UIImage, UIColor, NSAttributedString, AVAudioPlayer, and most @objc delegate objects. Solutions:

• Convert UIImage to Data (a Sendable value type) before crossing the task boundary; reconstruct the image on the other side
• Mark classes as @unchecked Sendable only after auditing thread safety
• Use @MainActor-isolated types to remove the need to send them across boundaries -- the compiler knows they stay on the main actor
• In Xcode 16+ with Swift 6 language mode, these errors are errors, not warnings; plan migration ahead of adopting Swift 6

TaskGroup Child Task Failure Semantics

withThrowingTaskGroup has a subtle behavior: when any child task throws, the group immediately cancels all remaining child tasks and rethrows the error when the group body returns. If you are implementing a "download all, ignore individual failures" pattern:

// WRONG: first failure cancels the whole group
try await withThrowingTaskGroup(of: Data.self) { group in
    for url in urls { group.addTask { try await fetch(url) } }
    for try await data in group { results.append(data) }
}

// CORRECT: catch per-task errors inside the child task
await withTaskGroup(of: Result<Data, Error>.self) { group in
    for url in urls {
        group.addTask { do { return .success(try await fetch(url)) } catch { return .failure(error) } }
    }
    for await result in group { /* handle Result */ }
}

Always choose the group type and error-catching location deliberately based on whether partial failure should abort the entire operation.

SwiftUI .task Modifier and State Updates

The .task {} modifier creates a task scoped to the view's lifetime, but the task body runs on the main actor when the view is @MainActor-isolated (which all SwiftUI views are). Updating @State or @StateObject from inside .task {} is safe because the task is already on the main actor. However:

• Avoid long synchronous work inside .task {} -- use Task.yield() to voluntarily suspend in CPU-heavy loops, allowing the main actor to process UI events
• When the view reappears (e.g., after a sheet dismiss), SwiftUI creates a new task and cancels the previous one; design the task body to be re-entrant and handle CancellationError by exiting cleanly without logging an error
• For paginated data loading triggered by scroll position, combine .task(id:) with the current page index as the id -- the task is automatically cancelled and restarted whenever the page changes

Example

Input: "I'm building an iOS photo browsing app. When a user opens an album, I need to fetch metadata for up to 200 photos in parallel from a REST API, limit concurrency to avoid overwhelming the server, update a progress indicator, and support cancellation if the user navigates away. We're targeting iOS 16, Swift 5.9."

Output:

Swift Concurrency Analysis

Problem Classification

• Category: parallelism with rate limiting, UI state updates, lifecycle-bound cancellation
• Execution context: custom actor for download state, @MainActor for progress updates
• Swift/iOS minimum version required: iOS 16 / Swift 5.9

Concurrency Primitive Decision

Recommended Pattern

Rate-Limited Parallel Task Group with Actor Token Pool

Fetch photos in parallel using withThrowingTaskGroup, control concurrency via an actor-based token pool that limits simultaneous in-flight requests, and stream progress back to the UI via @MainActor state updates.

Implementation

import Foundation

// MARK: - Rate Limiter Actor

/// Limits the number of concurrent operations by issuing and reclaiming tokens.
/// Callers await `acquire()` until a token is available, then call `release()` when done.
actor RateLimiter {
    private let maxConcurrent: Int
    private var available: Int

    init(maxConcurrent: Int) {
        self.maxConcurrent = maxConcurrent
        self.available = maxConcurrent
    }

    func acquire() async {
        // Re-validate after each suspension -- another caller may have taken a token
        while available == 0 {
            await Task.yield()
        }
        available -= 1
    }

    func release() {
        available = min(available + 1, maxConcurrent)
    }
}

// MARK: - Photo Metadata Model

struct PhotoMetadata: Sendable {
    let id: String
    let title: String
    let thumbnailURL: URL
    let dateTaken: Date
}

// MARK: - Photo Fetcher

@MainActor
final class AlbumViewModel: ObservableObject {
    @Published var photos: [PhotoMetadata] = []
    @Published var progress: Double = 0.0
    @Published var error: Error?
    @Published var isLoading = false

    private var fetchTask: Task<Void, Never>?

    func loadAlbum(photoIDs: [String]) {
        // Cancel any in-flight fetch before starting a new one
        fetchTask?.cancel()

        fetchTask = Task {
            isLoading = true
            progress = 0.0
            photos = []
            error = nil

            do {
                let fetched = try await fetchAllPhotos(photoIDs: photoIDs)
                photos = fetched
            } catch is CancellationError {
                // User navigated away -- exit silently, no error state
            } catch {
                self.error = error
            }

            isLoading = false
        }
    }

    func cancelLoad() {
        fetchTask?.cancel()
        fetchTask = nil
    }

    // MARK: - Private Fetch Logic

    /// Fetches metadata for all photo IDs in parallel, rate-limited to 10 concurrent requests.
    /// Streams results back to update progress as each photo completes.
    private func fetchAllPhotos(photoIDs: [String]) async throws -> [PhotoMetadata] {
        let rateLimiter = RateLimiter(maxConcurrent: 10)
        let total = Double(photoIDs.count)
        var completed = 0
        var results: [PhotoMetadata] = []
        results.reserveCapacity(photoIDs.count)

        try await withThrowingTaskGroup(of: PhotoMetadata.self) { group in
            for id in photoIDs {
                // Check cancellation before adding each child task
                // This prevents adding 200 tasks to a cancelled group
                try Task.checkCancellation()

                group.addTask {
                    // Acquire a rate-limit token; suspends if 10 tasks are already in flight
                    await rateLimiter.acquire()
                    defer { Task { await rateLimiter.release() } }

                    // Each child task independently checks cancellation
                    try Task.checkCancellation()
                    return try await PhotoAPI.fetchMetadata(id: id)
                }
            }

            // Collect results as they complete (order is non-deterministic)
            for try await metadata in group {
                results.append(metadata)
                completed += 1

                // Update progress on the main actor (we are already @MainActor here
                // because fetchAllPhotos is called from a @MainActor context)
                progress = Double(completed) / total
            }
        }

        // Sort by date after all fetches complete to produce stable ordering
        return results.sorted { $0.dateTaken < $1.dateTaken }
    }
}

// MARK: - API Layer (bridging async to URLSession)

enum PhotoAPI {
    static func fetchMetadata(id: String) async throws -> PhotoMetadata {
        let url = URL(string: "https://api.example.com/photos/\(id)/metadata")!
        var request = URLRequest(url: url)
        request.timeoutInterval = 10

        let (data, response) = try await URLSession.shared.data(for: request)

        guard let httpResponse = response as? HTTPURLResponse,
              (200..<300).contains(httpResponse.statusCode) else {
            throw PhotoAPIError.invalidResponse
        }

        return try JSONDecoder().decode(PhotoMetadata.self, from: data)
    }
}

enum PhotoAPIError: Error {
    case invalidResponse
}

// MARK: - SwiftUI View Integration

import SwiftUI

struct AlbumView: View {
    let photoIDs: [String]
    @StateObject private var viewModel = AlbumViewModel()

    var body: some View {
        ZStack {
            photoGrid
            if viewModel.isLoading {
                progressOverlay
            }
        }
        .task {
            // .task {} is automatically cancelled when the view disappears
            await viewModel.loadAlbum(photoIDs: photoIDs)
        }
        .onDisappear {
            viewModel.cancelLoad()
        }
    }

    private var photoGrid: some View {
        ScrollView {
            LazyVGrid(columns: [GridItem(.adaptive(minimum: 100))]) {
                ForEach(viewModel.photos, id: \.id) { photo in
                    AsyncImage(url: photo.thumbnailURL)
                        .frame(width: 100, height: 100)
                }
            }
        }
    }

    private var progressOverlay: some View {
        VStack {
            ProgressView(value: viewModel.progress)
                .padding()
            Text("\(Int(viewModel.progress * 100))%")
                .monospacedDigit()
        }
        .background(.regularMaterial)
        .cornerRadius(12)
    }
}

Cancellation Strategy

Cancellation propagates through the structured task hierarchy:

1. The SwiftUI .task {} modifier cancels the loadAlbum task when the view disappears
2. AlbumViewModel.cancelLoad() explicitly cancels fetchTask on onDisappear as a belt-and-suspenders guard
3. Inside fetchAllPhotos, try Task.checkCancellation() before each addTask prevents queuing new work after cancellation is requested
4. Each child task in the TaskGroup independently calls checkCancellation before the network request
5. withThrowingTaskGroup automatically cancels all running child tasks when any task throws -- including CancellationError
6. CancellationError is caught at the loadAlbum level and swallowed silently; the UI resets to empty state without showing an error message

Testing Approach

@MainActor
final class AlbumViewModelTests: XCTestCase {

    func testLoadAlbumUpdatesProgress() async throws {
        let mockIDs = (0..<20).map { "photo-\($0)" }
        let viewModel = AlbumViewModel()

        // Inject a mock URLSession or PhotoAPI via protocol for testability
        await viewModel.loadAlbum(photoIDs: mockIDs)

        XCTAssertEqual(viewModel.photos.count, 20)
        XCTAssertEqual(viewModel.progress, 1.0, accuracy: 0.001)
        XCTAssertFalse(viewModel.isLoading)
    }

    func testCancellationProducesNoError() async {
        let viewModel = AlbumViewModel()
        let bigList = (0..<200).map { "photo-\($0)" }

        // Start loading, then immediately cancel
        let task = Task { await viewModel.loadAlbum(photoIDs: bigList) }
        task.cancel()
        await task.value

        XCTAssertNil(viewModel.error, "Cancellation should not set error state")
    }

    func testRateLimiterNeverExceedsMaxConcurrent() async {
        let limiter = RateLimiter(maxConcurrent: 5)
        var peak = 0
        var current = 0
        let lock = NSLock()

        await withTaskGroup(of: Void.self) { group in
            for _ in 0..<50 {
                group.addTask {
                    await limiter.acquire()
                    lock.lock()
                    current += 1
                    peak = max(peak, current)
                    lock.unlock()
                    try? await Task.sleep(for: .milliseconds(10))
                    lock.lock()
                    current -= 1
                    lock.unlock()
                    await limiter.release()
                }
            }
        }

        XCTAssertLessThanOrEqual(peak, 5)
    }
}

Performance Considerations

• 10 concurrent requests is appropriate for most REST APIs on a mobile network; reduce to 5 for APIs with strict rate limits (check Retry-After headers); increase to 20 only for local network or CDN endpoints with sub-5ms response times
• The RateLimiter actor uses Task.yield() polling which has lower overhead than a semaphore but slightly higher than a condition variable; for high-frequency operations, consider an actor-based queue with AsyncStream as a token channel for O(1) wakeup
• results.reserveCapacity(photoIDs.count) prevents repeated array reallocations during the result collection loop -- at 200 items this saves approximately 7 reallocation cycles
• Sorting 200 items by date after fetch is O(n log n) and takes under 1ms; this is acceptable as a final step; avoid sorting inside the for await loop which would be O(n² log n) total
• The @MainActor progress update inside fetchAllPhotos executes approximately 200 main-actor hops; at ~50ns per hop this is ~10µs total overhead -- negligible, but if you needed to update every byte received, batch updates using a counter and yield to main only every 10 completions

Migration Notes

If the existing codebase uses DispatchGroup + DispatchSemaphore for this pattern:

// BEFORE (GCD-based, common legacy pattern)
let group = DispatchGroup()
let semaphore = DispatchSemaphore(value: 10)
let queue = DispatchQueue(label: "photo.fetch", attributes: .concurrent)
var results: [PhotoMetadata] = []
let lock = NSLock()

for id in photoIDs {
    group.enter()
    queue.async {
        semaphore.wait()
        PhotoAPI.legacyFetch(id: id) { metadata in
            lock.lock()
            results.append(metadata)
            lock.unlock()
            semaphore.signal()
            group.leave()
        }
    }
}
group.notify(queue: .main) { completion(results) }

Migrate incrementally:

1. First, wrap PhotoAPI.legacyFetch in withCheckedThrowingContinuation to get an async version
2. Replace DispatchGroup + result aggregation with withThrowingTaskGroup -- this is the highest-value change
3. Replace DispatchSemaphore with the RateLimiter actor
4. Replace NSLock-protected results array with direct result collection in the for await loop inside the group body
5. Finally, remove the DispatchQueue -- Swift concurrency manages the thread pool automatically

Each step is independently compilable and testable. Steps 1 and 2 provide the largest safety improvement; complete them first before addressing the remaining GCD infrastructure.