gcd-operations

name	gcd-operations
description	Use for iOS/macOS concurrency problems involving dispatch queues, locks, or thread safety. Triggers on: deadlocks (sync on main, nested sync, ABBA lock ordering), thread explosion from too many DispatchQueue.global() calls, data races flagged by Thread Sanitizer (TSan), DispatchGroup enter/leave imbalance, DispatchSource timer leaks, lock selection (NSLock vs OSAllocatedUnfairLock vs os_unfair_lock), reader-writer barriers, AsyncOperation subclasses, dispatchPrecondition usage, and OperationQueue throttling. Also use when migrating GCD patterns to Swift Concurrency actors. Apply whenever someone asks about thread-safe properties, concurrent access to shared state, or sees TSan warnings in Apple platform code — even if they don't say 'GCD' or 'concurrency.'
metadata	{"version":"1.0.3"}

GCD & OperationQueue Concurrency

Enterprise-grade concurrency skill for Grand Central Dispatch and OperationQueue. Opinionated: prescribes serial queues by default, target queue hierarchies, labeled queues, NSLock/OSAllocatedUnfairLock for synchronization, barrier-based reader-writer on custom concurrent queues, and OperationQueue for dependency graphs. Apple has not deprecated any core GCD APIs — GCD remains appropriate for parallelism, system I/O, and performance-critical paths. This skill covers correct usage, deadly bug prevention, and coexistence with Swift Concurrency.

Concurrency Layers

Application Layer    -> OperationQueue for dependency graphs, cancellation, throttling.
Dispatch Layer       -> Serial queues for state protection, concurrent+barrier for R/W.
Synchronization      -> NSLock / OSAllocatedUnfairLock for short critical sections.
System I/O           -> DispatchSource (timers, file monitoring), DispatchIO (non-blocking file I/O).
Thread Pool          -> GCD manages threads. App targets 3-4 well-defined queue subsystems.

Quick Decision Trees

"Which queue type should I use?"

Do you need mutual exclusion (protecting shared state)?
+-- YES -> Serial queue (default). Simplest, safest.
+-- NO  -> Is this independent parallel work (image processing, batch transforms)?
    +-- YES -> Concurrent queue (custom) with barrier for any writes.
    +-- NO  -> Do you need dependency graphs, cancellation, or throttling?
        +-- YES -> OperationQueue with maxConcurrentOperationCount.
        +-- NO  -> Serial queue. When in doubt, serial.

"Which lock should I use?"

Which lock?
+-- iOS 16+ -> OSAllocatedUnfairLock (Apple's safe wrapper)
+-- iOS 18+ / Swift 6 -> Mutex from Synchronization framework
+-- Any iOS -> NSLock (safe, simple, recommended by Apple DTS)
NEVER: os_unfair_lock as direct Swift stored property (memory corruption).
NEVER: DispatchSemaphore as a mutex (no priority donation).

"Which QoS should I use?"

Is the user waiting and watching?
+-- Immediate response (animation, touch) -> .userInteractive
+-- User-triggered, blocking progress    -> .userInitiated
+-- Long-running with progress bar       -> .utility
+-- Invisible to user (prefetch, sync)   -> .background
WARNING: .background QoS may be halted entirely in Low Power Mode.

Workflows

Workflow: Review Existing Concurrency Code

When: First encounter with a codebase using GCD/OperationQueue.

1. Scan for deadlock patterns using detection checklist (references/deadlocks.md)
2. Scan for data race patterns (references/data-races.md)
3. Check for thread explosion indicators: DispatchQueue.global() scattered throughout, many independent queues, no maxConcurrentOperationCount (references/thread-explosion.md)
4. Verify lock correctness (references/thread-safety.md)
5. Check OperationQueue subclasses for missing KVO/state management (references/operation-queue.md)
6. Create refactoring/ directory with per-feature plans and severity-ranked findings (references/refactoring-workflow.md)
7. Execute fixes in phase order: Critical → Thread Safety → Queue Architecture → OperationQueue → Monitoring

Workflow: Add Thread-Safe Collection

When: Need concurrent read/exclusive write access to shared state.

1. Create a custom concurrent queue with descriptive label
2. Implement reads via queue.sync { return value }
3. Implement writes via queue.async(flags: .barrier) { mutate }
4. Verify barrier is on custom queue, never global (references/thread-safety.md)
5. Add dispatchPrecondition assertions at boundaries
6. Test with DispatchQueue.concurrentPerform under Thread Sanitizer

Workflow: Create AsyncOperation Subclass

When: Need OperationQueue with async work (network, disk I/O).

1. Override isAsynchronous, isExecuting, isFinished with thread-safe KVO (references/operation-queue.md)
2. Never call super.start() -- it marks the operation finished immediately
3. Check isCancelled at start, call finish() if cancelled
4. Call finish() from every completion path
5. Check dependency cancellation in main() -- cancelled deps satisfy dependencies, they don't block
6. Test with Thread Sanitizer enabled

Workflow: Migrate GCD Pattern to Swift Concurrency

When: Modernizing specific GCD patterns. Not all patterns should migrate.

1. Identify the pattern category (references/migration.md)
2. Easy: DispatchQueue.main.async -> @MainActor, DispatchGroup -> TaskGroup, serial queue -> actor
3. Keep as GCD: concurrentPerform, DispatchIO, DispatchSource, concurrent+barrier reader-writer
4. Bridge callbacks with withCheckedThrowingContinuation -- resume exactly once on every path
5. Never use DispatchSemaphore.wait() in any async context

Code Generation Rules

<critical_rules> Whether reviewing, generating, or refactoring concurrent code, every output must be thread-safe, deadlock-free, and production-ready. ALWAYS:

1. Label every DispatchQueue with reverse DNS naming including subsystem
2. Use serial queues for state protection -- concurrent only when reads vastly outnumber writes
3. Use defer { group.leave() } immediately after every group.enter()
4. Use OSAllocatedUnfairLock (iOS 16+), NSLock (any iOS), or Mutex (Swift 6+) for short critical sections -- never os_unfair_lock as a direct stored property
5. Use dispatchPrecondition(condition:) before sync dispatch and UI updates
6. Use [weak self] in repeating timer handlers and stored closures
7. Cancel DispatchSource timers in deinit (resume first if suspended)
8. Override isAsynchronous, isExecuting, isFinished with KVO in async Operations
9. Set maxConcurrentOperationCount on OperationQueues -- never leave unlimited for blocking work
10. Never call DispatchQueue.main.sync from any code that might run on the main thread
11. Before generating concurrent code, output a brief <thought> analyzing potential deadlocks, races, and retention. </critical_rules>

Fallback Strategies & Loop Breakers

<fallback_strategies> When fixing concurrency bugs, you may encounter cascading issues. If you fail to fix the same issue twice, break the loop:

1. Deadlock in sync dispatch: Replace sync with async and restructure the call site to use a completion handler or continuation. Why: eliminating sync eliminates the entire deadlock category — async dispatch never blocks the caller.
2. Thread explosion from blocking work: Wrap blocking calls in Operations with maxConcurrentOperationCount = 4 instead of trying to make GCD limit threads. Why: GCD's thread pool grows unboundedly when work items block — OperationQueue is the only reliable throttle.
3. Data race under TSan: If concurrent queue + barrier is proving fragile, fall back to NSLock protecting a plain property. Why: barrier correctness requires remembering to use the barrier flag on every write and the exact same queue for every access — a lock has a simpler mental model with fewer ways to get wrong. </fallback_strategies>

Confidence Checks

Before finalizing generated or refactored concurrent code, verify ALL:

[] No deadlock risk -- no sync on main, no nested sync on same queue, no ABBA chains
[] No thread explosion -- maxConcurrentOperationCount set, no scattered global() calls
[] No data races -- shared mutable state protected by queue, lock, or actor
[] Queue labels -- every queue has reverse DNS label with subsystem name
[] Barrier correctness -- barriers on custom concurrent queues only, never global
[] Group balance -- every enter() has defer { group.leave() }
[] Timer safety -- [weak self], cancel in deinit, resume before dealloc if suspended
[] Lock safety -- no os_unfair_lock as stored property, no semaphore as mutex
[] Operation KVO -- async operations override isExecuting/isFinished with thread-safe KVO
[] Main thread -- UI updates verified with dispatchPrecondition(.onQueue(.main))
[] Swift Concurrency coexistence -- no semaphore.wait() in async contexts
[] Background tasks -- endBackgroundTask called on every path

Companion Skills

Before refactoring GCD code to Swift Concurrency: load the swift-concurrency skill to understand actor isolation and Sendable constraints. Migration without that context leads to subtle bugs.

Scenario	Companion skill	Apply when
Migrating GCD patterns to async/await or actors	skills/swift-concurrency/SKILL.md	Converting completion handlers, replacing DispatchQueue with actors, adopting Swift 6
GCD used in UIKit MVVM ViewModels	skills/uikit-mvvm/SKILL.md	Refactoring Massive ViewControllers, extracting ViewModels, setting up Combine bindings

References

Reference	When to Read
references/rules.md	Do's and Don'ts quick reference: priority rules and critical anti-patterns
references/queue-creation.md	Queue types, QoS selection, target queue hierarchies, queue labeling
references/deadlocks.md	The 5 deadlock patterns, prevention with dispatchPrecondition, lock ordering
references/thread-safety.md	Lock selection (NSLock, OSAllocatedUnfairLock, Mutex), reader-writer barrier, @Atomic trap, singletons
references/thread-explosion.md	Thread explosion causes, priority inversion, thread starvation, throttling strategies
references/dispatch-primitives.md	DispatchGroup, DispatchWorkItem, DispatchSemaphore, DispatchSource timers, DispatchIO
references/operation-queue.md	AsyncOperation base class, KVO state management, cancellation, dependency graphs
references/data-races.md	Value type COW races, memory management, main thread violations, real-world fixes
references/debugging.md	Thread Sanitizer, dispatchPrecondition, Instruments, os_signpost, testing strategies
references/migration.md	GCD to Swift Concurrency mapping, what to migrate vs keep, bridging with continuations
references/refactoring-workflow.md	refactoring/ directory protocol, per-feature plans, PR sizing, verification checklist