home / skills / rshankras / claude-code-apple-skills / concurrency-patterns

concurrency-patterns skill

This skill helps you review and fix Swift concurrency issues, migrate to Swift 6, and apply structured concurrency patterns to prevent data races.

npx playbooks add skill rshankras/claude-code-apple-skills --skill concurrency-patterns

Review the files below or copy the command above to add this skill to your agents.

Files (6)

SKILL.md

4.9 KB

---
name: concurrency-patterns
description: Swift concurrency patterns including Swift 6.2 approachable concurrency, structured concurrency, actors, continuations, and migration. Use when reviewing or building async code, fixing data race errors, or migrating to Swift 6.
allowed-tools: [Read, Glob, Grep]
---

# Swift Concurrency Patterns

Comprehensive guide for Swift concurrency covering async/await, structured concurrency, actors, and the Swift 6.2 "Approachable Concurrency" features. Focuses on patterns that prevent data races and common mistakes that cause crashes.

## When This Skill Activates

- User has data race errors or actor isolation compiler errors
- User is migrating to Swift 6 strict concurrency
- User asks about async/await, actors, Sendable, TaskGroup, or MainActor
- User needs to bridge legacy completion-handler APIs to async/await
- User is working with Swift 6.2 features (@concurrent, isolated conformances)
- User has concurrency bugs (actor reentrancy, task cancellation, UI freezes)

## Decision Tree

```
What concurrency problem are you solving?
│
├─ Swift 6 compiler errors / migration
│  └─ migration-guide.md
│
├─ Swift 6.2 new features (@concurrent, isolated conformances)
│  └─ swift62-concurrency.md
│
├─ Running work in parallel (async let, TaskGroup)
│  └─ structured-concurrency.md
│
├─ Thread safety for shared mutable state
│  └─ actors-and-isolation.md
│
├─ Bridging old APIs (delegates, callbacks) to async/await
│  └─ continuations-bridging.md
│
└─ General async/await patterns
   └─ See macos/coding-best-practices/modern-concurrency.md for basics
```

## Quick Reference

| Pattern | When to Use | Reference |
|---------|-------------|-----------|
| `async let` | Fixed number of parallel operations | `structured-concurrency.md` |
| `withTaskGroup` | Dynamic number of parallel operations | `structured-concurrency.md` |
| `withDiscardingTaskGroup` | Fire-and-forget parallel operations | `structured-concurrency.md` |
| `.task { }` modifier | Load data when view appears | `structured-concurrency.md` |
| `.task(id:)` modifier | Re-load when a value changes | `structured-concurrency.md` |
| `actor` | Shared mutable state protection | `actors-and-isolation.md` |
| `@MainActor` | UI-bound state and updates | `actors-and-isolation.md` |
| `@concurrent` | Explicitly offload to background (6.2) | `swift62-concurrency.md` |
| Isolated conformances | `@MainActor` type conforming to protocol (6.2) | `swift62-concurrency.md` |
| `withCheckedContinuation` | Bridge callback API to async | `continuations-bridging.md` |
| `AsyncStream` | Bridge delegate/notification API to async sequence | `continuations-bridging.md` |
| Strict concurrency migration | Incremental Swift 6 adoption | `migration-guide.md` |

## Process

### 1. Identify the Problem

Read the user's code or error messages to determine:
- Is this a compiler error (strict concurrency) or a runtime issue (data race, crash)?
- What Swift version and concurrency checking level are they using?
- Are they migrating existing code or writing new code?

### 2. Load Relevant Reference Files

Based on the problem, read from this directory:
- `swift62-concurrency.md` — Swift 6.2 approachable concurrency features
- `structured-concurrency.md` — async let, TaskGroup, .task modifier lifecycle
- `actors-and-isolation.md` — Actor patterns, reentrancy, @MainActor, Sendable
- `continuations-bridging.md` — withCheckedContinuation, AsyncStream, legacy bridging
- `migration-guide.md` — Incremental Swift 6 strict concurrency adoption

### 3. Review Checklist

- [ ] No blocking calls on `@MainActor` (use `await` for long operations)
- [ ] Shared mutable state protected by an actor (not locks or DispatchQueue)
- [ ] `Sendable` conformance correct for types crossing isolation boundaries
- [ ] Task cancellation handled (check `Task.isCancelled` or `Task.checkCancellation()`)
- [ ] No unstructured `Task {}` where structured concurrency (`.task`, `TaskGroup`) would work
- [ ] Actor reentrancy considered at suspension points
- [ ] `withCheckedContinuation` called exactly once (not zero, not twice)
- [ ] `.task(id:)` used instead of manual `onChange` + cancel patterns

### 4. Cross-Reference

- For **async/await basics and actor fundamentals**, see `macos/coding-best-practices/modern-concurrency.md`
- For **networking concurrency patterns**, see `generators/networking-layer/networking-patterns.md`
- For **SwiftData concurrency** (@ModelActor), see `macos/swiftdata-architecture/repository-pattern.md`
- For **auth token refresh with actors**, see `generators/auth-flow/auth-patterns.md`

## References

- [Swift Concurrency](https://docs.swift.org/swift-book/documentation/the-swift-programming-language/concurrency/)
- [Migrating to Swift 6](https://www.swift.org/migration/documentation/migrationguide/)
- Apple doc: `/Users/ravishankar/Downloads/docs/Swift-Concurrency-Updates.md`

Overview

This skill provides practical Swift concurrency patterns focused on Swift 6.2 approachable concurrency, structured concurrency, actors, continuations, and migration strategies. It helps you review or build async code, fix data races and actor isolation errors, and migrate code to Swift 6 strict concurrency with minimal disruption.

How this skill works

I inspect compiler errors, runtime data races, and code structure to identify the right concurrency construct: async/await, TaskGroup, actors, continuations, or Swift 6.2 features like @concurrent and isolated conformances. I apply a decision tree to match the problem to patterns and a checklist to verify thread safety, Sendable conformance, cancellation handling, and proper continuation usage.

When to use it

You see data race errors, actor isolation compiler errors, or crashes tied to shared state.
You are migrating code to Swift 6 strict concurrency or adopting Swift 6.2 features.
You need to convert completion-handler or delegate APIs to async/await safely.
You want to run work in parallel with structured concurrency (async let, TaskGroup).
You need to protect mutable shared state using actors or @MainActor for UI updates.

Best practices

Keep UI work on @MainActor and avoid blocking calls there; use await for long operations.
Protect shared mutable state with actors rather than locks or global queues.
Prefer structured concurrency (async let, withTaskGroup) over unstructured Task {} for lifetime control.
Ensure Sendable conformance for types crossing isolation boundaries and check for inadvertent captures.
Handle Task cancellation explicitly using Task.isCancelled or Task.checkCancellation().
Use withCheckedContinuation and AsyncStream carefully: call continuations exactly once and clean up delegate bridges.

Example use cases

Migrate a view model to Swift 6 by marking UI state @MainActor and adjusting isolated conformances.
Fix intermittent crashes by converting a shared mutable cache to an actor and auditing Sendable types.
Parallelize multiple network requests using async let or withTaskGroup and aggregate results safely.
Bridge a legacy delegate-based API to async/await using withCheckedContinuation or AsyncStream.
Adopt Swift 6.2 @concurrent for explicit background work and apply isolated conformances to @MainActor types.

FAQ

How do I decide between actor and @MainActor?

@MainActor is for UI-bound state and coordination on the main thread; use a plain actor for background shared mutable state that doesn’t require main-thread execution.

When should I prefer async let vs withTaskGroup?

Use async let for a fixed small number of parallel operations. Use withTaskGroup when the number of tasks is dynamic or you need to add tasks progressively and collect results.