@mmerterden/multi-agent-pipeline 20.7.0 → 20.8.1

package/pipeline/skills/shared/external/swift-concurrency/references/synchronization-primitives.md

@@ -1,347 +1,283 @@
 # Synchronization Primitives
 
-Low-level synchronization tools for protecting shared mutable state when actors
-are not the right fit. All primitives discussed here are `Sendable` and safe
-to use from multiple threads.
-
-## Contents
-
-- [Mutex](#mutex)
-- [OSAllocatedUnfairLock](#osallocatedunfairlock)
-- [Atomic](#atomic)
-- [Locks vs Actors: When to Use Each](#locks-vs-actors-when-to-use-each)
+When an actor is the wrong shape for some shared mutable state, these types
+protect it instead. Each one is `Sendable` and safe to use from any thread.
 
 ## Mutex
 
-**Module:** `Synchronization` · **Availability:** iOS 18.0+
-
-`Mutex<Value>` is a synchronization primitive that protects shared mutable
-state via mutual exclusion. It blocks threads attempting to acquire the lock,
-ensuring only one execution context accesses the protected value at a time.
-
-**Documentation:**
-[sosumi.ai/documentation/synchronization/mutex](https://sosumi.ai/documentation/synchronization/mutex)
-
-### Basic Usage
+`Mutex<Value>` lives in the `Synchronization` module and needs iOS 18.0 or
+later. It guarantees mutual exclusion: a thread that asks for a lock someone
+else holds waits until it is released. Documentation:
+https://developer.apple.com/documentation/synchronization/mutex
 
 ```swift
 import Synchronization
+import UIKit
 
-class ImageCache: Sendable {
-    let storage = Mutex<[String: UIImage]>([:])
+final class AvatarCache: Sendable {
+    private let images = Mutex<[String: UIImage]>([:])
 
-    func image(forKey key: String) -> UIImage? {
-        storage.withLock { $0[key] }
+    func image(for handle: String) -> UIImage? {
+        images.withLock { $0[handle] }
     }
 
-    func store(_ image: UIImage, forKey key: String) {
-        storage.withLock { $0[key] = image }
+    func store(_ image: UIImage, for handle: String) {
+        images.withLock { $0[handle] = image }
     }
 
-    func removeAll() {
-        storage.withLock { $0.removeAll() }
+    func purge() {
+        images.withLock { $0.removeAll() }
     }
 }
 ```
 
-### withLockIfAvailable
-
-Use `withLockIfAvailable` to attempt acquisition without blocking. Returns
-`nil` if the lock is already held.
+`withLockIfAvailable` tries once and returns `nil` instead of waiting when the
+lock is taken:
 
 ```swift
-let counter = Mutex<Int>(0)
+let pendingFlushes = Mutex<Int>(0)
 
-// Non-blocking attempt  -  returns nil if lock is contended
-if let value = counter.withLockIfAvailable({ $0 }) {
-    print("Current count: \(value)")
+if let count = pendingFlushes.withLockIfAvailable({ $0 }) {
+    metrics.report(pendingFlushes: count)
 } else {
-    print("Lock was busy, skipping")
+    // contended: skip this sample
 }
 ```
 
-### Key Properties
+Properties worth remembering:
 
-- **Generic over `Value`:** The protected state is stored inside the mutex,
-  making it clear what the lock protects.
-- **`Sendable`:** `Mutex` conforms to `Sendable`, so it can be stored in
-  `Sendable` types (classes, actors, global state).
-- **Non-recursive:** Attempting to lock a `Mutex` that you already hold on the
-  same thread is undefined behavior.
-- **Synchronous only:** Do not `await` inside `withLock`. The lock is held for
-  the duration of the closure  -  blocking across a suspension point will
-  deadlock or starve other threads.
+- It is generic over the protected value and stores that value itself, so it
+  is always clear what the lock guards.
+- It is `Sendable`, so it can sit in a `Sendable` class, in global state, or
+  (rarely) next to an actor.
+- It is not recursive. Locking it again on the thread that holds it is
+  undefined behavior.
+- It is synchronous. The lock is held for the entire `withLock` closure, so
+  never `await` inside it; suspending while holding a lock can deadlock or
+  starve the thread pool.
 
 ## OSAllocatedUnfairLock
 
-**Module:** `os` · **Availability:** iOS 16.0+
-
-`OSAllocatedUnfairLock<State>` wraps `os_unfair_lock` in a safe Swift API.
-It heap-allocates the underlying lock, avoiding the unsound address-of
-problem that makes raw `os_unfair_lock` unusable from Swift.
+`OSAllocatedUnfairLock<State>` comes from the `os` module and needs iOS 16.0.
+It wraps `os_unfair_lock` in a safe API. Because it allocates the lock on the
+heap, it avoids the problem that makes a raw `os_unfair_lock` unsound in Swift:
+Swift gives no stable address for a stored struct. Documentation:
+https://developer.apple.com/documentation/os/osallocatedunfairlock
 
-**Documentation:**
-[sosumi.ai/documentation/os/osallocatedunfairlock](https://sosumi.ai/documentation/os/osallocatedunfairlock)
-
-### State-Protecting Lock
+Guarding state:
 
 ```swift
 import os
 
-enum LoadState: Sendable {
-    case idle
-    case loading
-    case complete(Data)
-    case failed(Error)
+enum UploadPhase: Sendable {
+    case waiting
+    case sending(progress: Double)
+    case done(receipt: String)
+    case failed(any Error)
 }
 
-final class ResourceLoader: Sendable {
-    let state = OSAllocatedUnfairLock(initialState: LoadState.idle)
-
-    func beginLoading() {
-        state.withLock { $0 = .loading }
-    }
+final class UploadTracker: Sendable {
+    private let phase = OSAllocatedUnfairLock(initialState: UploadPhase.waiting)
 
-    func completeLoading(with data: Data) {
-        state.withLock { $0 = .complete(data) }
+    func update(_ newPhase: UploadPhase) {
+        phase.withLock { $0 = newPhase }
     }
 
-    var currentState: LoadState {
-        state.withLock { $0 }
+    var current: UploadPhase {
+        phase.withLock { $0 }
     }
 }
 ```
 
-### Stateless Lock
-
-When protecting external state or a code section rather than a specific value:
+Guarding a critical section with no state inside the lock:
 
 ```swift
-let lock = OSAllocatedUnfairLock()
+let journalLock = OSAllocatedUnfairLock()
 
-lock.withLock {
-    // Critical section  -  no associated state
-    writeToSharedFile(data)
+func appendToJournal(_ line: String) {
+    journalLock.withLock {
+        writeLine(line, toFileAt: journalURL)
+    }
 }
 ```
 
-### Manual lock/unlock
-
-Available but discouraged. Must unlock from the same thread that locked.
-**Never** use across `await` suspension points.
+`lock()` and `unlock()` also exist but are discouraged. If you use them, unlock
+on the same thread that locked, never span an `await`, and pair them with
+`defer`:
 
 ```swift
-lock.lock()
-defer { lock.unlock() }
-// Critical section
+journalLock.lock()
+defer { journalLock.unlock() }
+writeLine("checkpoint", toFileAt: journalURL)
 ```
 
-### Mutex vs OSAllocatedUnfairLock
+## Mutex or OSAllocatedUnfairLock
 
-| | `Mutex<Value>` | `OSAllocatedUnfairLock<State>` |
+| | `Mutex` | `OSAllocatedUnfairLock` |
 |---|---|---|
-| **Availability** | iOS 18+ | iOS 16+ |
-| **Module** | `Synchronization` | `os` |
-| **State model** | Value stored inside lock (generic `Value`) | Optional state via `initialState:` |
-| **`withLockIfAvailable`** | Returns `nil` on contention | Returns `nil` on contention |
-| **Ownership assertions** | Not available | `precondition(.owner)` / `precondition(.notOwner)` |
-| **Manual lock/unlock** | Not available | Available (`lock()` / `unlock()`) |
-| **Recommendation** | Preferred for iOS 18+ code | Use when targeting iOS 16-17 |
-
-**Guideline:** Use `Mutex` for new code targeting iOS 18+. For apps that run on
-iOS 16 through current releases, either keep the shared abstraction backed by
-`OSAllocatedUnfairLock` or branch with `#available(iOS 18, *)` so iOS 18+ uses
-`Mutex` and iOS 16-17 uses `OSAllocatedUnfairLock`. Prefer
-`OSAllocatedUnfairLock` when you need ownership assertions for debugging.
+| Minimum OS | iOS 18 | iOS 16 |
+| Module | `Synchronization` | `os` |
+| State | Always stores a generic `Value` | Optional, via `initialState:` |
+| Non-blocking attempt | `withLockIfAvailable` | `withLockIfAvailable` |
+| Ownership checks | None | `precondition(.owner)`, `precondition(.notOwner)` |
+| Manual `lock()` / `unlock()` | No | Yes |
+
+- Targeting iOS 18 or later: use `Mutex`.
+- Targeting iOS 16 or 17: use `OSAllocatedUnfairLock`.
+- Supporting iOS 16 through the current release: build the shared abstraction
+  on `OSAllocatedUnfairLock`, or branch with `#available(iOS 18, *)` and use
+  `Mutex` where it exists.
+- Want to assert lock ownership while debugging: `OSAllocatedUnfairLock`.
 
 ## Atomic
 
-**Module:** `Synchronization` · **Availability:** iOS 18.0+
-
-`Atomic<Value>` provides lock-free atomic operations on values conforming to
-`AtomicRepresentable`. Use atomics for simple counters, flags, and
-compare-and-swap patterns where a full lock would be overkill.
-
-**Documentation:**
-[sosumi.ai/documentation/synchronization/atomic](https://sosumi.ai/documentation/synchronization/atomic)
-
-### Counter Example
+`Atomic<Value>` is in `Synchronization` and needs iOS 18.0. It performs
+lock-free operations on types conforming to `AtomicRepresentable` and suits
+counters, flags and compare-and-exchange where a lock would be overkill.
+Documentation: https://developer.apple.com/documentation/synchronization/atomic
 
 ```swift
 import Synchronization
 
-final class RequestTracker: Sendable {
-    let activeRequests = Atomic<Int>(0)
-
-    func beginRequest() {
-        activeRequests.wrappingAdd(1, ordering: .relaxed)
-    }
+final class ActiveStreams: Sendable {
+    private let count = Atomic<Int>(0)
 
-    func endRequest() {
-        activeRequests.wrappingSubtract(1, ordering: .relaxed)
-    }
+    func opened() { count.wrappingAdd(1, ordering: .relaxed) }
+    func closed() { count.wrappingSubtract(1, ordering: .relaxed) }
+    var value: Int { count.load(ordering: .relaxed) }
+}
 
-    var count: Int {
-        activeRequests.load(ordering: .relaxed)
+final class Teardown: Sendable {
+    private let finished = Atomic<Bool>(false)
+
+    func runOnce() {
+        let (won, _) = finished.compareExchange(
+            expected: false,
+            desired: true,
+            ordering: .acquiringAndReleasing
+        )
+        guard won else { return }
+        closeSockets()
     }
 }
 ```
 
-### Boolean Flag
+### Memory ordering
 
-```swift
-let isShutdown = Atomic<Bool>(false)
-
-func shutdown() {
-    let (exchanged, _) = isShutdown.compareExchange(
-        expected: false,
-        desired: true,
-        ordering: .acquiringAndReleasing
-    )
-    guard exchanged else { return } // Already shut down
-    performCleanup()
-}
-```
+Every atomic call names an ordering.
 
-### Memory Ordering
+| Ordering | Use |
+|---|---|
+| `.relaxed` | Counters and statistics; no ordering relative to other memory |
+| `.acquiring` | A load that must see everything written before the matching release |
+| `.releasing` | A store whose earlier writes must be visible to the matching acquire |
+| `.acquiringAndReleasing` | Compare-and-exchange and other read-modify-write operations |
+| `.sequentiallyConsistent` | Strongest and slowest; rarely required, use only with a proven need |
 
-Atomic operations require an explicit memory ordering:
+Rule of thumb: `.relaxed` for plain counters, `.acquiringAndReleasing` for
+compare-and-exchange.
 
-| Ordering | Use case |
-|---|---|
-| `.relaxed` | Counters, statistics  -  no ordering guarantees needed |
-| `.acquiring` | Read that must see all writes before a corresponding release |
-| `.releasing` | Write that must be visible to a corresponding acquire |
-| `.acquiringAndReleasing` | Compare-and-swap, read-modify-write |
-| `.sequentiallyConsistent` | Strongest guarantee  -  rarely needed |
-
-**Guideline:** Use `.relaxed` for simple counters. Use
-`.acquiringAndReleasing` for compare-and-swap patterns. Avoid
-`.sequentiallyConsistent` unless you have a proven need  -  it is the most
-expensive ordering.
-
-### When to Use Atomics vs Mutex
-
-- **Atomics:** Simple scalar values (Int, Bool, UInt64), single-field updates,
-  counters, flags. Lock-free and very fast.
-- **Mutex:** Compound state (dictionaries, structs with multiple fields),
-  multi-step operations that must be atomic as a group.
-
-## Locks vs Actors: When to Use Each
-
-### Use Actors When:
-
-- **Async isolation is natural.** The protected state is accessed from async
-  contexts and you can afford the hop.
-- **Callers can suspend.** Actor-isolated APIs are `async` from outside the
-  actor, so they fit task-based code but not synchronous C callbacks, real-time
-  hooks, or other no-suspension call sites.
-- **Structured concurrency.** You want the compiler to enforce isolation
-  boundaries and prevent data races statically.
-- **Most Swift code.** Actors are the default recommendation for shared mutable
-  state in Swift concurrency.
-- **Complex state with multiple methods.** Actor isolation protects all
-  properties and methods automatically.
+### Atomic or Mutex
+
+- **Atomic:** a single scalar such as `Int`, `Bool` or `UInt64`, updated one
+  field at a time: counters, flags. Lock-free and very fast.
+- **Mutex:** compound state such as dictionaries or structs with several
+  fields, and any sequence of steps that must happen as one unit.
+
+## Locks or actors
+
+### Choose an actor when
+
+- the state is reached from async code and the cost of hopping is acceptable;
+- callers can suspend. From outside, an actor's API is `async`, which rules it
+  out for synchronous C callbacks, real-time audio hooks and similar call sites;
+- you want the compiler to enforce the isolation boundary;
+- there is no special constraint: actors are the default for shared mutable
+  state in most Swift code;
+- the state is rich and has many operations, since isolation covers all of
+  them at once.
 
 ```swift
-// GOOD: Actor for a cache accessed from async contexts
-actor ImageDownloader {
-    private var cache: [URL: UIImage] = [:]
+actor ArtworkLoader {
+    private var loaded: [URL: UIImage] = [:]
 
-    func image(for url: URL) async throws -> UIImage {
-        if let cached = cache[url] { return cached }
+    func artwork(at url: URL) async throws -> UIImage? {
+        if let image = loaded[url] { return image }
         let (data, _) = try await URLSession.shared.data(from: url)
-        let image = UIImage(data: data)!
-        cache[url] = image
+        let image = UIImage(data: data)
+        loaded[url] = image
         return image
     }
 }
 ```
 
-### Use Mutex / Locks When:
+### Choose a lock when
 
-- **Synchronous access is required.** Callers cannot (or should not) be async.
-  Accessing an actor from synchronous code requires `Task` and introduces
-  unwanted asynchrony.
-- **Performance-critical paths.** Lock acquisition is nanoseconds; actor hops
-  involve task scheduling. For tight loops or high-frequency access, a lock
-  may be significantly faster.
-- **Bridging with C/ObjC.** C callbacks, delegate methods, or ObjC APIs that
-  cannot be made async.
-- **Simple counters or flags.** `Atomic<Int>` or `Atomic<Bool>` is cheaper and
-  simpler than creating an actor for a single value.
+- callers must stay synchronous; calling an actor from sync code requires a
+  `Task` and makes the operation asynchronous;
+- the path is hot: taking an uncontended lock costs nanoseconds while an actor
+  hop involves scheduling, so tight loops can be far faster with a lock;
+- C or Objective-C callbacks, delegates or APIs that cannot become async touch
+  the state;
+- the state is one counter or flag, where `Atomic<Int>` or `Atomic<Bool>` is
+  both cheaper and simpler than an actor.
 
 ```swift
-// GOOD: Mutex for synchronous, high-frequency access
-final class MetricsCollector: Sendable {
-    let metrics = Mutex<[String: Int]>([:])
+final class EventTally: Sendable {
+    private let counts = Mutex<[String: Int]>([:])
 
-    // Called from tight loops, C callbacks, or synchronous code
-    func increment(_ key: String) {
-        metrics.withLock { $0[key, default: 0] += 1 }
+    func record(_ name: String) {
+        counts.withLock { $0[name, default: 0] += 1 }
     }
 
     func snapshot() -> [String: Int] {
-        metrics.withLock { $0 }
+        counts.withLock { $0 }
     }
 }
 ```
 
-### Decision Guide
-
-```text
-Need shared mutable state protection?
-├── Can all access be async?
-│   ├── Yes → Use an actor
-│   └── No → Use Mutex or OSAllocatedUnfairLock
-├── Single scalar value (counter, flag)?
-│   └── Use Atomic<Value>
-├── Performance-critical (nanosecond-level)?
-│   └── Use Mutex or Atomic
-└── Bridging C/ObjC callbacks?
-    └── Use Mutex or OSAllocatedUnfairLock
-```
+## Decision guide
+
+| Situation | Use |
+|---|---|
+| Every access can be async | An actor |
+| Some access must be synchronous | `Mutex`, or `OSAllocatedUnfairLock` below iOS 18 |
+| One counter or flag | `Atomic<Value>` |
+| Nanosecond-sensitive path | `Mutex` or `Atomic` |
+| C or Objective-C callbacks | `Mutex` or `OSAllocatedUnfairLock` |
 
-### Anti-Patterns
+## Anti-patterns
 
-**Never put locks inside actors.** An actor already serializes access; adding
-a lock creates double synchronization and risks deadlocks.
+**A lock inside an actor.** The actor already serializes access; the lock adds
+a second layer and a way to deadlock.
 
 ```swift
-// WRONG: Lock inside an actor  -  double synchronization
-actor BadCache {
-    let lock = Mutex<[String: Data]>([:])  // Unnecessary!
-    // The actor already protects its state
+// Wrong
+actor PrefetchQueueWrong {
+    private let pending = Mutex<[URL]>([])
 }
 
-// CORRECT: Just use the actor's built-in isolation
-actor GoodCache {
-    var cache: [String: Data] = [:]
-
-    func store(_ data: Data, key: String) {
-        cache[key] = data
-    }
+// Right
+actor PrefetchQueue {
+    private var pending: [URL] = []
+    func enqueue(_ url: URL) { pending.append(url) }
 }
 ```
 
-**Avoid reaching first for `DispatchSemaphore` or `NSLock` in modern Swift.**
-`NSLock` is `Sendable`, but `Mutex` (iOS 18+) and `OSAllocatedUnfairLock`
-(iOS 16+) make the protected state and lock ownership clearer in Swift
-concurrency code. Use `NSLock` only when compatibility or existing API shape
-requires it.
+**Old primitives by reflex.** `DispatchSemaphore` and `NSLock` should not be the
+first tool in modern Swift. `NSLock` is `Sendable`, so it is legal, but `Mutex`
+(iOS 18) and `OSAllocatedUnfairLock` (iOS 16) tie the lock to the state it
+protects and make ownership clearer. Keep `NSLock` for compatibility or where an
+existing API expects it.
 
-**Never hold a lock across `await`.** This blocks the thread and can deadlock
-the cooperative thread pool.
+**A lock held across `await`.** The thread stays blocked while the task is
+suspended, which can exhaust or deadlock the cooperative pool.
 
 ```swift
-// WRONG: Holding lock across suspension point
-mutex.withLock { value in
-    value = await fetchData()  // DEADLOCK RISK
-}
+// Wrong: suspends while holding the lock
+// latest.withLock { $0 = await feed.fetch() }
 
-// CORRECT: Fetch first, then lock to update
-let data = await fetchData()
-mutex.withLock { value in
-    value = data
-}
+// Right: await first, lock only to publish the result
+let fresh = await feed.fetch()
+latest.withLock { $0 = fresh }
 ```