---

name: swift-concurrency description: Implement async/await, Actors, and structured concurrency in Swift. Use when implementing Swift async/await, Actors, or structured concurrency in iOS/macOS. metadata: triggers: files: - '**/*.swift' keywords: - async - await - actor - Swift concurrency Task - Swift Task - MainActor

Swift Concurrency

Priority: P0 (CRITICAL)

Write Structured Async Code

• Async Functions: Mark with async and call with await.
• async let: Use async let for parallel execution when multiple tasks independent.
• Task Groups: Use withTaskGroup or withThrowingTaskGroup for spawning dynamic number of tasks.
• Error Handling: Combine with throws. Always handle CancellationError.

See implementation examples for parallel fetch with async let and Task Groups.

Isolate State with Actors

• Data Isolation: Use actor for shared mutable state to avoid data races.
• @MainActor: Annotate UI classes (Views, ViewModels) with @MainActor for main thread execution. Use MainActor.run { ... } for inline UI updates in async blocks.
• Global Actors: Use @GlobalActor for specific thread-bound resources.
• nonisolated: Use nonisolated for methods that don't access actor state to avoid unnecessary hops.

See implementation examples for Actor-based state isolation and nonisolated methods.

Manage Task Lifecycle

• Task Hierarchy: Inherit isolation by using Task { ... }.
• Cancellation: Explicitly check Task.isCancelled in long loops. Use try Task.checkCancellation() for throwing functions.
• Detached Tasks: Avoid Task.detached unless you explicitly want to break context inheritance.

Anti-Patterns

• No synchronous work in @MainActor: not block main thread.
• No UI updates off @MainActor: Always dispatch back to main via MainActor.
• No ignored cancellation: Always check and propagate cancellation.

References

• async/await & Actors