axiom-concurrency

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Concurrency

并发编程

You MUST use this skill for ANY concurrency, async/await, threading, or Swift 6 concurrency work.

编写任何并发、async/await、线程或Swift 6并发相关代码时，都必须使用本技能。

Quick Reference

快速参考

Symptom / Task	Reference
async/await patterns, @MainActor, actors	See `skills/swift-concurrency.md`
Data race errors, Sendable conformance	See `skills/swift-concurrency.md`
Swift 6 migration, @concurrent attribute	See `skills/swift-concurrency.md`
Actor definition, reentrancy, global actors	See `skills/swift-concurrency-ref.md`
Task/TaskGroup/cancellation API	See `skills/swift-concurrency-ref.md`
AsyncStream, continuations	See `skills/swift-concurrency-ref.md`
DispatchQueue → actor migration	See `skills/swift-concurrency-ref.md`
Mutex (iOS 18+), OSAllocatedUnfairLock	See `skills/synchronization.md`
Atomic types, lock vs actor decision	See `skills/synchronization.md`
MainActor.assumeIsolated	See `skills/assume-isolated.md`
@preconcurrency protocol conformances	See `skills/assume-isolated.md`
Legacy delegate callbacks	See `skills/assume-isolated.md`
Swift Concurrency Instruments template	See `skills/concurrency-profiling.md`
Actor contention diagnosis	See `skills/concurrency-profiling.md`
Thread pool exhaustion	See `skills/concurrency-profiling.md`

症状/任务	参考文档
async/await模式、@MainActor、actors	查看 `skills/swift-concurrency.md`
数据竞争错误、Sendable合规	查看 `skills/swift-concurrency.md`
Swift 6迁移、@concurrent属性	查看 `skills/swift-concurrency.md`
Actor定义、可重入性、全局actors	查看 `skills/swift-concurrency-ref.md`
Task/TaskGroup/取消API	查看 `skills/swift-concurrency-ref.md`
AsyncStream、续体（continuations）	查看 `skills/swift-concurrency-ref.md`
DispatchQueue → actor迁移	查看 `skills/swift-concurrency-ref.md`
Mutex（iOS 18+）、OSAllocatedUnfairLock	查看 `skills/synchronization.md`
原子类型、锁与actor的选择	查看 `skills/synchronization.md`
MainActor.assumeIsolated	查看 `skills/assume-isolated.md`
@preconcurrency协议合规	查看 `skills/assume-isolated.md`
旧版代理回调	查看 `skills/assume-isolated.md`
Swift并发性能分析模板	查看 `skills/concurrency-profiling.md`
Actor竞争诊断	查看 `skills/concurrency-profiling.md`
线程池耗尽	查看 `skills/concurrency-profiling.md`

Decision Tree

决策树

dot

digraph concurrency {
    start [label="Concurrency task" shape=ellipse];
    what [label="What do you need?" shape=diamond];

    start -> what;
    what -> "skills/swift-concurrency.md" [label="async/await, actors,\nSendable, data races,\nSwift 6 migration"];
    what -> "skills/swift-concurrency-ref.md" [label="API syntax lookup\n(TaskGroup, AsyncStream,\ncontinuations, migration)"];
    what -> "skills/synchronization.md" [label="Mutex, locks,\natomic types"];
    what -> "skills/assume-isolated.md" [label="assumeIsolated,\n@preconcurrency"];
    what -> "skills/concurrency-profiling.md" [label="profile async perf,\nactor contention"];
}

Data races / actor isolation / @MainActor / Sendable / Swift 6 migration? →
```
skills/swift-concurrency.md
```
1a. Need specific API syntax (actor definition, TaskGroup, AsyncStream, continuations)? →
```
skills/swift-concurrency-ref.md
```
Writing async/await code? →
```
skills/swift-concurrency.md
```
assumeIsolated / @preconcurrency? →
```
skills/assume-isolated.md
```
Mutex / lock / synchronization? →
```
skills/synchronization.md
```
Profile async performance / actor contention? →
```
skills/concurrency-profiling.md
```
Value type / ARC / generic optimization? → See axiom-performance (skills/swift-performance.md)
borrowing / consuming / ~Copyable? → See axiom-swift (skills/ownership-conventions.md)
Combine / @Published / AnyCancellable / reactive streams? → See axiom-uikit (skills/combine-patterns.md)
Want automated concurrency scan? → concurrency-auditor (Agent)

dot

digraph concurrency {
    start [label="并发任务" shape=ellipse];
    what [label="你需要什么？" shape=diamond];

    start -> what;
    what -> "skills/swift-concurrency.md" [label="async/await, actors,\nSendable, 数据竞争,\nSwift 6 migration"];
    what -> "skills/swift-concurrency-ref.md" [label="API语法查询\n(TaskGroup, AsyncStream,\n续体, 迁移)"];
    what -> "skills/synchronization.md" [label="Mutex, 锁,\n原子类型"];
    what -> "skills/assume-isolated.md" [label="assumeIsolated,\n@preconcurrency"];
    what -> "skills/concurrency-profiling.md" [label="分析异步性能,\nActor竞争"];
}

遇到数据竞争/actor隔离/@MainActor/Sendable/Swift 6迁移问题？→
```
skills/swift-concurrency.md
```
1a. 需要特定API语法（actor定义、TaskGroup、AsyncStream、续体）？→
```
skills/swift-concurrency-ref.md
```
编写async/await代码？→
```
skills/swift-concurrency.md
```
涉及assumeIsolated/@preconcurrency？→
```
skills/assume-isolated.md
```
涉及Mutex/锁/同步机制？→
```
skills/synchronization.md
```
分析异步性能/Actor竞争？→
```
skills/concurrency-profiling.md
```
值类型/ARC/泛型优化？→ 查看axiom-performance（skills/swift-performance.md）
借用/消耗/~Copyable？→ 查看axiom-swift（skills/ownership-conventions.md）
Combine/@Published/AnyCancellable/响应式流？→ 查看axiom-uikit（skills/combine-patterns.md）
想要自动并发扫描？→ 使用concurrency-auditor（Agent）

Conflict Resolution

冲突解决

concurrency vs axiom-performance: When app freezes or feels slow:

Try concurrency FIRST — Main thread blocking is the #1 cause of UI freezes. Check for synchronous work on @MainActor before profiling.
Only use axiom-performance if concurrency fixes don't help — Profile after ruling out obvious blocking.

concurrency vs axiom-build: When seeing Swift 6 concurrency errors:

Use concurrency, NOT axiom-build — Concurrency errors are CODE issues, not environment issues.

concurrency vs axiom-data: When concurrency errors involve Core Data or SwiftData:

Core Data threading (NSManagedObjectContext thread confinement) → use axiom-data first
SwiftData + @MainActor ModelContext → use concurrency
General "background saves losing data" → use axiom-data first

concurrency vs axiom-performance：当应用冻结或运行缓慢时：

优先使用concurrency —— 主线程阻塞是UI冻结的首要原因。在进行性能分析前，先检查@MainActor上的同步操作。
仅在concurrency修复无效时使用axiom-performance —— 排除明显的阻塞问题后再进行性能分析。

concurrency vs axiom-build：遇到Swift 6并发错误时：

使用concurrency，而非axiom-build —— 并发错误是代码问题，而非环境问题。

concurrency vs axiom-data：当并发错误涉及Core Data或SwiftData时：

Core Data线程处理（NSManagedObjectContext线程限制）→ 优先使用axiom-data
SwiftData + @MainActor ModelContext → 使用concurrency
通用“后台保存丢失数据”问题 → 优先使用axiom-data

Critical Patterns

核心模式

Swift Concurrency (

skills/swift-concurrency.md

Progressive journey: single-threaded → async → concurrent → actors
@concurrent attribute for forced background execution
Isolated conformances, main actor mode
12 copy-paste patterns including delegate value capture, weak self in Tasks
Comprehensive decision tree for 7 common error messages

API Reference (

skills/swift-concurrency-ref.md

Actor definition, reentrancy, global actors, nonisolated
Sendable patterns, @unchecked Sendable, sending parameter
Task/TaskGroup/cancellation, async let, withDiscardingTaskGroup
AsyncStream, continuations, buffering policies
Isolation patterns (#isolation, @preconcurrency, nonisolated(unsafe))
DispatchQueue/DispatchGroup/completion handler migration

Synchronization (

skills/synchronization.md

Mutex (iOS 18+), OSAllocatedUnfairLock (iOS 16+), Atomic types
Lock vs actor decision tree
Danger patterns: locks across await, semaphores in async context

Profiling (

skills/concurrency-profiling.md

Swift Concurrency Instruments template
Diagnosing main thread blocking, actor contention, thread pool exhaustion
Safe vs unsafe primitives for cooperative pool

Swift Concurrency（

skills/swift-concurrency.md

）：

渐进式演进：单线程 → 异步 → 并发 → actors
用于强制后台执行的@concurrent属性
隔离合规、主线程actor模式
12个可直接复制使用的模式，包括代理值捕获、Tasks中的weak self
针对7种常见错误信息的完整决策树

API参考（

skills/swift-concurrency-ref.md

）：

Actor定义、可重入性、全局actors、nonisolated
Sendable模式、@unchecked Sendable、参数传递
Task/TaskGroup/取消、async let、withDiscardingTaskGroup
AsyncStream、续体、缓冲策略
隔离模式（#isolation、@preconcurrency、nonisolated(unsafe)）
DispatchQueue/DispatchGroup/完成处理程序迁移

同步机制（

skills/synchronization.md

）：

Mutex（iOS 18+）、OSAllocatedUnfairLock（iOS 16+）、原子类型
锁与actor的决策树
危险模式：await跨锁、异步上下文使用信号量

性能分析（

skills/concurrency-profiling.md

）：

Swift Concurrency Instruments模板
诊断主线程阻塞、Actor竞争、线程池耗尽
协作池的安全与不安全原语

Automated Scanning

自动扫描

Concurrency audit → Launch

concurrency-auditor

agent or

/axiom:audit concurrency

(5-phase semantic audit: maps isolation architecture, detects 8 anti-patterns, reasons about missing concurrency patterns, correlates compound risks, scores Swift 6.3 readiness)

并发审计 → 启动

concurrency-auditor

agent或使用

/axiom:audit concurrency

（5阶段语义审计：映射隔离架构、检测8种反模式、分析缺失的并发模式、关联复合风险、评估Swift 6.3就绪度）

Anti-Rationalization

常见误区纠正

Thought	Reality
"Just add @MainActor and it'll work"	@MainActor has isolation inheritance rules. `skills/swift-concurrency.md` covers all patterns.
"I'll use nonisolated(unsafe) to silence the warning"	Silencing warnings hides data races. `skills/swift-concurrency.md` shows the safe pattern.
"It's just one async call"	Even single async calls have cancellation and isolation implications.
"I know how actors work"	Actor reentrancy and isolation rules changed in Swift 6.2.
"I'll fix the Sendable warnings later"	Sendable violations cause runtime crashes. Fix them now.
"Combine is dead, just use async/await"	Combine has no deprecation notice. Rewriting working pipelines wastes time. See See axiom-uikit (skills/combine-patterns.md).
"I'll use @unchecked Sendable to silence this"	You're hiding a data race from the compiler. It will crash in production.
"This async function runs on a background thread"	`async` suspends without blocking but resumes on the same actor. Use `@concurrent` to force background.

错误想法	实际情况
"只要加上@MainActor就能正常工作"	@MainActor有隔离继承规则。 `skills/swift-concurrency.md` 涵盖了所有模式。
"我用nonisolated(unsafe)来消除警告就行"	消除警告会隐藏数据竞争问题。 `skills/swift-concurrency.md` 展示了安全的实现模式。
"只是一个简单的异步调用而已"	即使是单个异步调用也涉及取消和隔离的问题。
"我知道actors怎么工作"	Actor的可重入性和隔离规则在Swift 6.2中已更新。
"Sendable警告以后再修复"	Sendable违规会导致运行时崩溃。现在就修复它们。
"Combine已经过时了，直接用async/await就行"	Combine没有被弃用的通知。重写可用的流水线纯属浪费时间。请查看axiom-uikit（skills/combine-patterns.md）。
"我用@unchecked Sendable来消除这个警告"	你是在向编译器隐藏数据竞争问题，这会导致生产环境崩溃。
"这个异步函数在后台线程运行"	`async` 会挂起但不阻塞，恢复时会在同一个actor上执行。使用 `@concurrent` 强制在后台执行。

Example Invocations

调用示例

User: "I'm getting 'data race' errors in Swift 6" → Read:

skills/swift-concurrency.md

User: "How do I use @MainActor correctly?" → Read:

skills/swift-concurrency.md

User: "How do I create a TaskGroup?" → Read:

skills/swift-concurrency-ref.md

User: "What's the AsyncStream API?" → Read:

skills/swift-concurrency-ref.md

User: "How do I use assumeIsolated?" → Read:

skills/assume-isolated.md

User: "Should I use Mutex or actor?" → Read:

skills/synchronization.md

User: "My async code is slow, how do I profile it?" → Read:

skills/concurrency-profiling.md

User: "My app is slow due to unnecessary copying" → See axiom-performance (skills/swift-performance.md)

User: "Check my code for Swift 6 concurrency issues" → Invoke:

concurrency-auditor

agent

用户："我在Swift 6中遇到了‘数据竞争’错误" → 阅读：

skills/swift-concurrency.md

用户："如何正确使用@MainActor？" → 阅读：

skills/swift-concurrency.md

用户："如何创建TaskGroup？" → 阅读：

skills/swift-concurrency-ref.md

用户："AsyncStream API是什么？" → 阅读：

skills/swift-concurrency-ref.md

用户："如何使用assumeIsolated？" → 阅读：

skills/assume-isolated.md

用户："我应该用Mutex还是actor？" → 阅读：

skills/synchronization.md

用户："我的异步代码运行缓慢，如何分析性能？" → 阅读：

skills/concurrency-profiling.md

用户："我的应用因为不必要的复制操作运行缓慢" → 查看axiom-performance（skills/swift-performance.md）

用户："检查我的代码是否存在Swift 6并发问题" → 调用：

concurrency-auditor

agent