swift-concurrency

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

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.

本技能提供关于Swift Concurrency的专业指导，涵盖现代async/await模式、actors、tasks、Sendable合规性以及向Swift 6的迁移。借助本技能，开发者可以编写安全、高性能的并发代码，并驾驭Swift结构化并发模型的复杂性。

Agent Behavior Contract (Follow These Rules)

Agent行为约定（请遵循以下规则）

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
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.

当建议依赖Swift语言版本时，分析项目/包文件以确定使用的Swift语言模式（Swift 5.x vs Swift 6）以及Xcode/Swift工具链。
在提出修复方案前，明确隔离边界：
```
@MainActor
```
、自定义actor、actor实例隔离或非隔离。
不要将
```
@MainActor
```
作为万能修复方案。需说明为何主actor隔离对该代码是合理的。
优先使用结构化并发（子任务、任务组）而非非结构化任务。仅在有明确理由时使用
```
Task.detached
```
。
若推荐使用
```
@preconcurrency
```
、
```
@unchecked Sendable
```
或
```
nonisolated(unsafe)
```
，需满足：
- 有文档记录的安全不变量
- 创建后续工单以移除或迁移该用法
对于迁移工作，优化以最小化影响范围（小而易于评审的变更）并添加验证步骤。
课程参考仅用于深度学习。仅在其能明确帮助解答开发者问题时才少量使用。

Recommended Tools for Analysis

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

并发行为依赖于构建设置。请务必确定：

默认actor隔离（模块默认是
```
@MainActor
```
还是
```
nonisolated
```
？）
严格并发检查级别（minimal/targeted/complete）
是否启用了即将推出的特性（尤其是
```
NonisolatedNonsendingByDefault
```
）
Swift语言模式（Swift 5.x vs Swift 6）以及SwiftPM工具版本

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:

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.

SwiftPM:

检查

Package.swift

中是否包含

.defaultIsolation(MainActor.self)

。

检查

Package.swift

中是否包含

.enableUpcomingFeature("NonisolatedNonsendingByDefault")

。

检查是否存在严格并发标志：
```
.enableExperimentalFeature("StrictConcurrency=targeted")
```
（或类似配置）。
查看顶部的工具版本：
```
// swift-tools-version: ...
```

Xcode项目:

在

project.pbxproj

中搜索：

```
SWIFT_DEFAULT_ACTOR_ISOLATION
```
```
SWIFT_STRICT_CONCURRENCY
```

SWIFT_UPCOMING_FEATURE_

（和/或

SWIFT_ENABLE_EXPERIMENTAL_FEATURES

）

如果以上任何信息未知，请先让开发者确认，再提供对迁移敏感的指导。

Quick Decision Tree

快速决策树

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

Starting fresh with async code?
- Read
```
references/async-await-basics.md
```
  for foundational patterns
- For parallel operations →
```
references/tasks.md
```
  (async let, task groups)
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)
Managing async operations?
- Structured async work →
```
references/tasks.md
```
  (Task, child tasks, cancellation)
- Streaming data →
```
references/async-sequences.md
```
  (AsyncSequence, AsyncStream)
Working with legacy frameworks?
- Core Data integration →
```
references/core-data.md
```
- General migration →
```
references/migration.md
```
Performance or debugging issues?
- Slow async code →
```
references/performance.md
```
  (profiling, suspension points)
- Testing concerns →
```
references/testing.md
```
  (XCTest, Swift Testing)
Understanding threading behavior?
- Read
```
references/threading.md
```
  for thread/task relationship and isolation
Memory issues with tasks?
- Read
```
references/memory-management.md
```
  for retain cycle prevention

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

从零开始编写异步代码？
- 阅读
```
references/async-await-basics.md
```
  了解基础模式
- 并行操作 → 参考
```
references/tasks.md
```
  （async let、任务组）
保护共享可变状态？
- 需要保护基于类的状态 → 参考
```
references/actors.md
```
  （actors、@MainActor）
- 需要线程安全的值传递 → 参考
```
references/sendable.md
```
  （Sendable合规性）
管理异步操作？
- 结构化异步工作 → 参考
```
references/tasks.md
```
  （Task、子任务、取消）
- 流式数据 → 参考
```
references/async-sequences.md
```
  （AsyncSequence、AsyncStream）
与遗留框架交互？
- Core Data集成 → 参考
```
references/core-data.md
```
- 通用迁移 → 参考
```
references/migration.md
```
性能或调试问题？
- 异步代码运行缓慢 → 参考
```
references/performance.md
```
  （性能分析、挂起点）
- 测试相关问题 → 参考
```
references/testing.md
```
  （XCTest、Swift Testing）
理解线程行为？
- 阅读
```
references/threading.md
```
  了解线程/任务关系与隔离
任务相关的内存问题？
- 阅读
```
references/memory-management.md
```
  了解如何避免保留环

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)

SwiftLint并发相关警告
- 参考
```
references/linting.md
```
  了解规则意图与推荐修复方案；避免将虚假await作为“修复手段”。
SwiftLint
```
async_without_await
```
警告
- 如果不需要则移除
```
async
```
  ；如果是协议/重写/@concurrent要求的，优先使用窄范围抑制而非添加虚假await。请参考
```
references/linting.md
```
  。
“Sending value of non-Sendable type ... risks causing data races”（发送非Sendable类型的值...可能导致数据竞争）
- 第一步：确定值在何处跨越隔离边界
- 第二步：参考
```
references/sendable.md
```
  和
```
references/threading.md
```
  （尤其是Swift 6.2的行为变更）
“Main actor-isolated ... cannot be used from a nonisolated context”（主actor隔离的...无法在非隔离上下文中使用）
- 第一步：判断该代码是否确实属于
```
@MainActor
```
- 第二步：参考
```
references/actors.md
```
  （全局actors、
```
nonisolated
```
  、隔离参数）和
```
references/threading.md
```
  （默认隔离）
“Class property 'current' is unavailable from asynchronous contexts”（Thread API相关）
- 参考
```
references/threading.md
```
  避免以线程为中心的调试，转而依赖隔离 + Instruments
XCTest异步错误，如“wait(...) is unavailable from asynchronous contexts”
- 参考
```
references/testing.md
```
  （
```
await fulfillment(of:)
```
  和Swift Testing模式）
Core Data并发警告/错误
- 参考
```
references/core-data.md
```
  （DAO/
```
NSManagedObjectID
```
  、默认隔离冲突）

Core Patterns Reference

核心模式参考

When to Use Each Concurrency Tool

各并发工具的适用场景

async/await - Making existing synchronous code asynchronous

swift

// Use for: Single asynchronous operations
func fetchUser() async throws -> User {
    try await networkClient.get("/user")
}

async let - Running multiple independent async operations in parallel

swift

// Use for: Fixed number of parallel operations known at compile time
async let user = fetchUser()
async let posts = fetchPosts()
let profile = try await (user, posts)

Task - Starting unstructured asynchronous work

swift

// Use for: Fire-and-forget operations, bridging sync to async contexts
Task {
    await updateUI()
}

Task Group - Dynamic parallel operations with structured concurrency

swift

// Use for: Unknown number of parallel operations at compile time
await withTaskGroup(of: Result.self) { group in
    for item in items {
        group.addTask { await process(item) }
    }
}

Actor - Protecting mutable state from data races

swift

// Use for: Shared mutable state accessed from multiple contexts
actor DataCache {
    private var cache: [String: Data] = [:]
    func get(_ key: String) -> Data? { cache[key] }
}

@MainActor - Ensuring UI updates on main thread

swift

// Use for: View models, UI-related classes
@MainActor
class ViewModel: ObservableObject {
    @Published var data: String = ""
}

async/await - 将现有同步代码改造为异步

swift

// Use for: Single asynchronous operations
func fetchUser() async throws -> User {
    try await networkClient.get("/user")
}

async let - 并行运行多个独立的异步操作

swift

// Use for: Fixed number of parallel operations known at compile time
async let user = fetchUser()
async let posts = fetchPosts()
let profile = try await (user, posts)

Task - 启动非结构化异步工作

swift

// Use for: Fire-and-forget operations, bridging sync to async contexts
Task {
    await updateUI()
}

Task Group - 采用结构化并发的动态并行操作

swift

// Use for: Unknown number of parallel operations at compile time
await withTaskGroup(of: Result.self) { group in
    for item in items {
        group.addTask { await process(item) }
    }
}

Actor - 保护可变状态避免数据竞争

swift

// Use for: Shared mutable state accessed from multiple contexts
actor DataCache {
    private var cache: [String: Data] = [:]
    func get(_ key: String) -> Data? { cache[key] }
}

@MainActor - 确保UI更新在主线程执行

swift

// Use for: View models, UI-related classes
@MainActor
class ViewModel: ObservableObject {
    @Published var data: String = ""
}

Common Scenarios

常见场景

Scenario: Network request with UI update

swift

Task { @concurrent in
    let data = try await fetchData() // Background
    await MainActor.run {
        self.updateUI(with: data) // Main thread
    }
}

Scenario: Multiple parallel network requests

swift

async let users = fetchUsers()
async let posts = fetchPosts()
async let comments = fetchComments()
let (u, p, c) = try await (users, posts, comments)

Scenario: Processing array items in parallel

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)
    }
}

场景：网络请求与UI更新

swift

Task { @concurrent in
    let data = try await fetchData() // Background
    await MainActor.run {
        self.updateUI(with: data) // Main thread
    }
}

场景：多个并行网络请求

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 Migration Quick Guide

Swift 6迁移快速指南

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

Swift 6中的关键变更：

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

详细迁移步骤请参考

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
```
async_without_await
```
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

根据具体主题按需加载以下文件：

async-await-basics.md
- async/await语法、执行顺序、async let、URLSession模式
tasks.md
- Task生命周期、取消、优先级、任务组、结构化vs非结构化
threading.md
- 线程/任务关系、挂起点、隔离域、非隔离
memory-management.md
- 任务中的保留环、内存安全模式
actors.md
- Actor隔离、@MainActor、全局actors、可重入性、自定义执行器、Mutex
sendable.md
- Sendable合规性、值/引用类型、@unchecked、区域隔离
linting.md
- 并发相关lint规则与SwiftLint
```
async_without_await
```
async-sequences.md
- AsyncSequence、AsyncStream、与常规异步方法的适用场景对比
core-data.md
- NSManagedObject可发送性、自定义执行器、隔离冲突
performance.md
- 使用Instruments进行性能分析、减少挂起点、执行策略
testing.md
- XCTest异步模式、Swift Testing、并发测试工具
migration.md
- Swift 6迁移策略、闭包转异步、@preconcurrency、FRP迁移

Best Practices Summary

最佳实践总结

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

优先使用结构化并发 - 尽可能使用任务组而非非结构化任务
最小化挂起点 - 缩小actor隔离代码段的范围以减少上下文切换
谨慎使用@MainActor - 仅用于真正与UI相关的代码
让类型符合Sendable - 通过遵循Sendable实现安全的并发访问
处理取消 - 在长时间运行的操作中检查Task.isCancelled
避免阻塞 - 切勿在异步上下文中使用信号量或锁
测试并发代码 - 使用正确的异步测试方法并考虑时序问题

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
```
  ).

解释诊断信息前，请确认构建设置（默认隔离、严格并发、即将推出的特性）。
重构后：
- 运行测试，尤其是对并发敏感的测试（参考
```
references/testing.md
```
  ）。
- 如果涉及性能，请使用Instruments验证（参考
```
references/performance.md
```
  ）。
- 如果涉及生命周期，请验证deinit/取消行为（参考
```
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.

核心并发术语的快速定义请参考

references/glossary.md

。

说明：本技能基于Antoine van der Lee的全面Swift Concurrency Course构建。

swift-concurrency

Original

Translation

Swift Concurrency

Swift Concurrency

Overview

概述

Agent Behavior Contract (Follow These Rules)

Agent行为约定（请遵循以下规则）

Recommended Tools for Analysis

推荐的分析工具

Project Settings Intake (Evaluate Before Advising)

项目设置评估（建议前先完成）

Manual checks (no scripts)

手动检查（无需脚本）

Quick Decision Tree

快速决策树

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

优先排查手册（常见错误 → 下一步最佳行动）

Core Patterns Reference

核心模式参考

When to Use Each Concurrency Tool

各并发工具的适用场景

Common Scenarios

常见场景

Swift 6 Migration Quick Guide

Swift 6迁移快速指南

Reference Files

参考文件

Best Practices Summary

最佳实践总结

Verification Checklist (When You Change Concurrency Code)

验证清单（修改并发代码时）

Glossary

术语表