Swift Concurrency

Overview

This skill provides expert guidance on Swift Concurrency, covering modern async/await patterns, actors, tasks, Sendable conformance, and migration to Swift 6. Use this skill to help developers write safe, performant concurrent code and navigate the complexities of Swift's structured concurrency model.

Agent Behavior Contract (Follow These Rules)

1. Analyze the project/package file to find out which Swift language mode (Swift 5.x vs Swift 6) and which Xcode/Swift toolchain is used when advice depends on it.
Before proposing fixes, identify the isolation boundary: @MainActor, custom actor, actor instance isolation, or nonisolated.
Do not recommend @MainActor as a blanket fix. Justify why main-actor isolation is correct for the code.
Prefer structured concurrency (child tasks, task groups) over unstructured tasks. Use Task.detached only with a clear reason.
If recommending @preconcurrency, @unchecked Sendable, or nonisolated(unsafe), require:

- a documented safety invariant - a follow-up ticket to remove or migrate it

6. For migration work, optimize for minimal blast radius (small, reviewable changes) and add verification steps.
Course references are for deeper learning only. Use them sparingly and only when they clearly help answer the developer's question.

Recommended Tools for Analysis

When analyzing Swift projects for concurrency issues:

1. Project Settings Discovery

- Use Read on Package.swift for SwiftPM settings (tools version, strict concurrency flags, upcoming features) - Use Grep for SWIFT_STRICT_CONCURRENCY or SWIFT_DEFAULT_ACTOR_ISOLATION in .pbxproj files - Use Grep for SWIFT_UPCOMING_FEATURE_ to find enabled upcoming features

Project Settings Intake (Evaluate Before Advising)

Concurrency behavior depends on build settings. Always try to determine:

- Default actor isolation (is the module default @MainActor or nonisolated?)
Strict concurrency checking level (minimal/targeted/complete)
Whether upcoming features are enabled (especially NonisolatedNonsendingByDefault)
Swift language mode (Swift 5.x vs Swift 6) and SwiftPM tools version

Manual checks (no scripts)

- SwiftPM:

- Check Package.swift for .defaultIsolation(MainActor.self). - Check Package.swift for .enableUpcomingFeature("NonisolatedNonsendingByDefault"). - Check for strict concurrency flags: .enableExperimentalFeature("StrictConcurrency=targeted") (or similar). - Check tools version at the top: // swift-tools-version: ...

- Xcode projects:

- Search project.pbxproj for: - SWIFT_DEFAULT_ACTOR_ISOLATION - SWIFT_STRICT_CONCURRENCY - SWIFT_UPCOMING_FEATURE_ (and/or SWIFT_ENABLE_EXPERIMENTAL_FEATURES)

If any of these are unknown, ask the developer to confirm them before giving migration-sensitive guidance.

Quick Decision Tree

When a developer needs concurrency guidance, follow this decision tree:

1. Starting fresh with async code?

- Read references/async-await-basics.md for foundational patterns - For parallel operations → references/tasks.md (async let, task groups)

2. Protecting shared mutable state?

- Need to protect class-based state → references/actors.md (actors, @MainActor) - Need thread-safe value passing → references/sendable.md (Sendable conformance)

3. Managing async operations?

- Structured async work → references/tasks.md (Task, child tasks, cancellation) - Streaming data → references/async-sequences.md (AsyncSequence, AsyncStream)

4. Working with legacy frameworks?

- Core Data integration → references/core-data.md - General migration → INLINECODE35

5. Performance or debugging issues?

- Slow async code → references/performance.md (profiling, suspension points) - Testing concerns → references/testing.md (XCTest, Swift Testing)

6. Understanding threading behavior?

- Read references/threading.md for thread/task relationship and isolation

7. Memory issues with tasks?

- Read references/memory-management.md for retain cycle prevention

Triage-First Playbook (Common Errors -> Next Best Move)

- SwiftLint concurrency-related warnings

- Use references/linting.md for rule intent and preferred fixes; avoid dummy awaits as “fixes”.

- SwiftLint async_without_await warning

- Remove async if not required; if required by protocol/override/@concurrent, prefer narrow suppression over adding fake awaits. See references/linting.md.

- "Sending value of non-Sendable type ... risks causing data races"

- First: identify where the value crosses an isolation boundary - Then: use references/sendable.md and references/threading.md (especially Swift 6.2 behavior changes)

- "Main actor-isolated ... cannot be used from a nonisolated context"

- First: decide if it truly belongs on @MainActor - Then: use references/actors.md (global actors, nonisolated, isolated parameters) and references/threading.md (default isolation)

- "Class property 'current' is unavailable from asynchronous contexts" (Thread APIs)

- Use references/threading.md to avoid thread-centric debugging and rely on isolation + Instruments

- XCTest async errors like "wait(...) is unavailable from asynchronous contexts"

- Use references/testing.md (await fulfillment(of:) and Swift Testing patterns)

- Core Data concurrency warnings/errors

- Use references/core-data.md (DAO/NSManagedObjectID, default isolation conflicts)

Core Patterns Reference

When to Use Each Concurrency Tool

async/await - Making existing synchronous code asynchronous
CODEBLOCK0

async let - Running multiple independent async operations in parallel
CODEBLOCK1

Task - Starting unstructured asynchronous work
CODEBLOCK2

Task Group - Dynamic parallel operations with structured concurrency
CODEBLOCK3

Actor - Protecting mutable state from data races
CODEBLOCK4

@MainActor - Ensuring UI updates on main thread
CODEBLOCK5

Common Scenarios

Scenario: Network request with UI update
CODEBLOCK6

Scenario: Multiple parallel network requests
CODEBLOCK7

Scenario: Processing array items in parallel
CODEBLOCK8

Swift 6 Migration Quick Guide

Key changes in Swift 6:

- Strict concurrency checking enabled by default
Complete data-race safety at compile time
Sendable requirements enforced on boundaries
Isolation checking for all async boundaries

For detailed migration steps, see references/migration.md.

Reference Files

Load these files as needed for specific topics:

- async-await-basics.md - async/await syntax, execution order, async let, URLSession patterns
tasks.md - Task lifecycle, cancellation, priorities, task groups, structured vs unstructured
threading.md - Thread/task relationship, suspension points, isolation domains, nonisolated
memory-management.md - Retain cycles in tasks, memory safety patterns
actors.md - Actor isolation, @MainActor, global actors, reentrancy, custom executors, Mutex
sendable.md - Sendable conformance, value/reference types, @unchecked, region isolation
linting.md - Concurrency-focused lint rules and SwiftLint INLINECODE63
async-sequences.md - AsyncSequence, AsyncStream, when to use vs regular async methods
core-data.md - NSManagedObject sendability, custom executors, isolation conflicts
performance.md - Profiling with Instruments, reducing suspension points, execution strategies
testing.md - XCTest async patterns, Swift Testing, concurrency testing utilities
migration.md - Swift 6 migration strategy, closure-to-async conversion, @preconcurrency, FRP migration

Best Practices Summary

1. Prefer structured concurrency - Use task groups over unstructured tasks when possible
Minimize suspension points - Keep actor-isolated sections small to reduce context switches
Use @MainActor judiciously - Only for truly UI-related code
Make types Sendable - Enable safe concurrent access by conforming to Sendable
Handle cancellation - Check Task.isCancelled in long-running operations
Avoid blocking - Never use semaphores or locks in async contexts
Test concurrent code - Use proper async test methods and consider timing issues

Verification Checklist (When You Change Concurrency Code)

- Confirm build settings (default isolation, strict concurrency, upcoming features) before interpreting diagnostics.
After refactors:

- Run tests, especially concurrency-sensitive ones (see references/testing.md). - If performance-related, verify with Instruments (see references/performance.md). - If lifetime-related, verify deinit/cancellation behavior (see references/memory-management.md).

Glossary

See references/glossary.md for quick definitions of core concurrency terms used across this skill.

Note: This skill is based on the comprehensive Swift Concurrency Course by Antoine van der Lee.

Swift Concurrency

概述

本技能提供关于 Swift Concurrency 的专业指导，涵盖现代 async/await 模式、Actor、任务、Sendable 遵循以及向 Swift 6 的迁移。使用本技能帮助开发者编写安全、高性能的并发代码，并驾驭 Swift 结构化并发模型的复杂性。

代理行为契约（遵循以下规则）

1. 分析项目/包文件，确定使用的 Swift 语言模式（Swift 5.x 与 Swift 6）以及 Xcode/Swift 工具链版本，当建议依赖于这些信息时。
在提出修复方案前，先识别隔离边界：@MainActor、自定义 Actor、Actor 实例隔离或 nonisolated。
不要将 @MainActor 作为万能修复方案推荐。需说明主 Actor 隔离为何适用于该代码。
优先使用结构化并发（子任务、任务组）而非非结构化任务。仅在明确理由下使用 Task.detached。
如果推荐使用 @preconcurrency、@unchecked Sendable 或 nonisolated(unsafe)，需满足：

- 提供文档化的安全不变性保证 - 创建后续工单以移除或迁移该用法

6. 对于迁移工作，优化以最小化影响范围（小规模、可审查的变更）并添加验证步骤。
课程参考资料仅用于深入学习。谨慎使用，仅当它们能明确帮助回答开发者问题时。

项目设置采集（在提供建议前评估）

并发行为取决于构建设置。始终尝试确定：

- 默认 Actor 隔离（模块默认是 @MainActor 还是 nonisolated？）
严格并发检查级别（最小/目标/完整）
是否启用了即将推出的功能（特别是 NonisolatedNonsendingByDefault）
Swift 语言模式（Swift 5.x 与 Swift 6）和 SwiftPM 工具版本

手动检查（无需脚本）

- SwiftPM：

- 检查 Package.swift 中是否有 .defaultIsolation(MainActor.self)。 - 检查 Package.swift 中是否有 .enableUpcomingFeature(NonisolatedNonsendingByDefault)。 - 检查严格并发标志：.enableExperimentalFeature(StrictConcurrency=targeted)（或类似）。 - 检查顶部的工具版本：// swift-tools-version: ...

- Xcode 项目：

- 在 project.pbxproj 中搜索： - SWIFTDEFAULTACTOR_ISOLATION - SWIFTSTRICTCONCURRENCY - SWIFTUPCOMINGFEATURE（和/或 SWIFTENABLEEXPERIMENTALFEATURES）

如果以上任何一项未知，请在给出迁移敏感指导前要求开发者确认。

快速决策树

当开发者需要并发指导时，遵循此决策树：

1. 从头开始编写异步代码？

- 阅读 references/async-await-basics.md 了解基础模式 - 对于并行操作 → references/tasks.md（async let、任务组）

2. 保护共享可变状态？

- 需要保护基于类的状态 → references/actors.md（Actor、@MainActor） - 需要线程安全的值传递 → references/sendable.md（Sendable 遵循）

3. 管理异步操作？

- 结构化异步工作 → references/tasks.md（Task、子任务、取消） - 流式数据 → references/async-sequences.md（AsyncSequence、AsyncStream）

4. 使用遗留框架？

- Core Data 集成 → references/core-data.md - 通用迁移 → references/migration.md

5. 性能或调试问题？

- 慢速异步代码 → references/performance.md（性能分析、挂起点） - 测试相关问题 → references/testing.md（XCTest、Swift Testing）

6. 理解线程行为？

- 阅读 references/threading.md 了解线程/任务关系和隔离

7. 任务的内存问题？

- 阅读 references/memory-management.md 了解循环引用预防

分类优先策略（常见错误 -> 下一步最佳操作）

- SwiftLint 并发相关警告

- 使用 references/linting.md 了解规则意图和首选修复方案；避免使用虚假的 await 作为修复。

- SwiftLint asyncwithoutawait 警告

- 如果不需要则移除 async；如果协议/重写/@concurrent 要求，优先使用窄范围抑制而非添加虚假 await。参见 references/linting.md。

- 发送非 Sendable 类型的值...存在数据竞争风险

- 首先：确定值在哪里跨越隔离边界 - 然后：使用 references/sendable.md 和 references/threading.md（特别是 Swift 6.2 行为变化）

- 主 Actor 隔离...不能从非隔离上下文中使用

- 首先：确定它是否真正属于 @MainActor - 然后：使用 references/actors.md（全局 Actor、nonisolated、隔离参数）和 references/threading.md（默认隔离）

- 类属性 current 在异步上下文中不可用（线程 API）

- 使用 references/threading.md 避免以线程为中心的调试，依赖隔离 + Instruments

- XCTest 异步错误，如 wait(...) 在异步上下文中不可用

- 使用 references/testing.md（await fulfillment(of:) 和 Swift Testing 模式）

- Core Data 并发警告/错误

- 使用 references/core-data.md（DAO/NSManagedObjectID、默认隔离冲突）

核心模式参考

何时使用每种并发工具

async/await - 将现有同步代码变为异步
swift
// 用于：单个异步操作
func fetchUser() async throws -> User {
try await networkClient.get(/user)
}

async let - 并行执行多个独立异步操作
swift
// 用于：编译时已知固定数量的并行操作
async let user = fetchUser()
async let posts = fetchPosts()
let profile = try await (user, posts)

Task - 启动非结构化异步工作
swift
// 用于：即发即弃操作、桥接同步到异步上下文
Task {
await updateUI()
}

Task Group - 动态并行操作与结构化并发
swift
// 用于：编译时未知数量的并行操作
await withTaskGroup(of: Result.self) { group in
for item in items {
group.addTask { await process(item) }
}
}

Actor - 保护可变状态免受数据竞争
swift
// 用于：从多个上下文访问的共享可变状态
actor DataCache {
private var cache: [String: Data] = [:]
func get(_ key: String) -> Data? { cache[key] }
}

@MainActor - 确保 UI 更新在主线程上
swift
// 用于：视图模型、UI 相关类
@MainActor
class ViewModel: ObservableObject {
@Published var data: String =
}

常见场景

场景：网络请求与 UI 更新
swift
Task { @concurrent in
let data = try await fetchData() // 后台
await MainActor.run {
self.updateUI(with: data) // 主线程
}
}

场景：多个并行网络请求
swift
async let users = fetchUsers()
async let posts = fetchPosts()
async let comments = fetchComments()
let (u, p, c) = try await (users, posts, comments)

场景：并行处理数组项
swift
await withTaskGroup(of: ProcessedItem.self) { group in
for item in items {
group.addTask { await process(item) }
}
for await result in group {
results.append(result)
}
}

Swift 6 迁移快速指南

Swift 6 的关键变化：

- 严格并发检查默认启用
编译时完整的数据竞争安全
边界上强制执行 Sendable 要求
所有异步边界的隔离检查

详细迁移步骤见 references/migration.md。

参考文件

根据需要加载以下文件

swift-concurrencySwift并发指南