Concurrency

Concurrency

This page documents concurrency in the RawCullAIModels branch of RawCull and in the first-party Swift packages checked out beside it. The audit covers production source in the RawCull app, DecodeEncodeGeneric, ParseRsyncOutput, PhotoAIKit, PhotoAnalysisKit, RawCullCore, RawParserKit, RsyncArguments, RsyncProcessStreaming, and RsyncAnalyse.

RawCull uses concurrency to keep SwiftUI responsive while it scans folders, reads RAW metadata, extracts and caches previews, calculates sharpness, creates similarity artifacts, groups bursts, runs AI models, downloads model assets, and streams rsync output.

The rule: isolate work, do not guess about threads

A Swift Task is not a thread. Swift schedules tasks on executors, and executors use threads. At an await, a task may suspend and later resume on a different worker thread even when it resumes on the same actor. RawCull must never depend on the worker thread being unchanged.

In this document, hop means a change of actor, executor, or dispatch queue that is required or explicitly requested by the source code:

• Calling an actor-isolated method from outside that actor hops to the actor’s executor.
• @MainActor, MainActor.run, and Task { @MainActor in ... } hop to the main actor when the caller is elsewhere.
• @concurrent and Task { @concurrent in ... } explicitly move non-UI work off inherited actor isolation and onto the concurrent executor.
• A task-group child is independently scheduled so that sibling work can run in parallel.
• Task.detached creates an unstructured task that does not inherit actor isolation.
• DispatchQueue.async submits work to the named GCD queue.

None of await, Task.sleep, task priority, or cancellation alone requests an executor hop. They may cause suspension and a later change of worker thread, but that is scheduler behavior and must not be observed as application logic.

Every executor hop in RawCull must be intentional. Add an explicit isolation annotation or concurrency primitive and document the reason. A change of worker thread after suspension is neither an error nor a behavior RawCull may rely on.

Compiler concurrency model

swift-tools-version selects the PackageDescription API and minimum toolchain. It is not, by itself, proof of the package’s Swift language mode; packages that declare swiftLanguageModes: [.v6] do so explicitly.

Concurrency architecture

flowchart TD
    UI["SwiftUI and @MainActor state"]
    APP["RawCull background actors"]
    GROUPS["Bounded task groups and async let"]
    PARSER["RawParserKit actors and ImageIO bridge"]
    ANALYSIS["PhotoAnalysisKit workers"]
    AI["PhotoAIKit model and storage actors"]
    CORE["RawCullCore nonisolated Sendable values"]
    RSYNC["Rsync callbacks, StreamAccumulator actor, GCD drain queue"]
    GCD["GCD worker threads for blocking framework and pipe work"]

    UI -->|"await: intentional actor hop"| APP
    UI -->|"@concurrent: intentional exit from MainActor"| GROUPS
    APP --> GROUPS
    APP -->|"await"| PARSER
    GROUPS --> ANALYSIS
    GROUPS --> AI
    APP --> CORE
    UI --> RSYNC
    PARSER --> GCD
    RSYNC --> GCD
    GCD -->|"Task @MainActor"| UI

1. Main-actor concurrency

The main actor owns SwiftUI and user-visible mutable state. This is correctness isolation, not a way to make work parallel.

SwiftUI .task modifiers and button-created Task values inherit main-actor isolation when their synchronous prefix reads or mutates view state. That entry is intentional. They then hop only when awaiting a background actor or an explicitly concurrent function, and resume on the main actor before changing UI state.

DispatchQueue.main.async is used in the comparison filmstrip and vertical image table to defer scrollTo by one run-loop turn so lazy view IDs have entered scroll geometry. These calls do not exist merely to reach the main thread; they intentionally delay already-main-actor UI work.

2. Actors that serialize mutable state

An actor hop is wanted because it establishes exclusive access to the actor’s state. It may suspend the caller, but it does not promise a particular worker thread.

RawCull app actors

SharedMemoryCache deliberately exposes its NSCache instances through nonisolated(unsafe): NSCache supplies its own thread safety. Synchronous counters, eviction history, and memory-pressure samples use OSAllocatedUnfairLock. This avoids an actor hop in synchronous cache delegate callbacks while retaining an explicit synchronization invariant.

Package actors

PhotoAIKit’s Core AI model providers are actors because model loading and inference resources are shared and not safe to use concurrently without ownership. An await from a RawCull workflow to a provider is therefore an intentional provider-actor hop. The pinned coreai-models implementation may use its own async execution internally; RawCull does not assume which thread it uses.

3. Structured parallelism

Structured child tasks inherit cancellation and cannot outlive their scope. RawCull uses them when operations are independent and results must be joined.

Task-group children are scheduled independently of the actor running the group. That is the explicit parallelism boundary. Each child captures Sendable values and calls the actor or provider that owns mutable state.

4. Unstructured tasks and lifetime

RawCull creates unstructured tasks to bridge synchronous UI/callback entry points, coalesce duplicate requests, and retain cancellable long-running work.

Important stored tasks include catalog load, thumbnail preload, full-size cache warming, zoom extraction, burst analysis, similarity and semantic hydration, scoring, semantic search, model download, deep review, memory sampling, mask loading, and image-source loading. Their exact properties live with the owning view model or actor; ownership, not thread identity, defines their lifetime.

A bare Task { ... } inherits the surrounding actor. It does not hop away merely because it is asynchronous. This is wanted when its synchronous prefix accesses actor-owned state. If a new task has no actor work before its first await, use Task { @concurrent in ... } or call an explicitly @concurrent function so that leaving the main actor is visible in source.

5. Explicit concurrent-executor work

@concurrent is the Swift 6.2 spelling RawCull uses for work that must not inherit the caller’s actor. It is an executor hop, not a guarantee that a new OS thread will be created.

The PhotoAIKit disk-store tasks intentionally leave actor isolation, but @concurrent still uses Swift’s cooperative executor. It is appropriate for short bounded operations; any operation shown by profiling to block for a long time should use a dedicated blocking-I/O bridge like RawParserKit’s GCD continuation bridge.

6. Detached tasks and blocking work

Task.detached is used only where losing actor inheritance is deliberate. It does not inherit actor isolation or task-local values, and cancellation is not automatically structured unless the parent explicitly awaits and/or cancels it.

RawParserKit’s CancellableImageIOWork is the stronger escape hatch for blocking framework calls. It uses withCheckedThrowingContinuation and submits the operation to DispatchQueue.global(qos:). This is an intentional queue hop: blocking ImageIO/CoreImage work runs on a GCD worker rather than occupying a Swift cooperative-pool thread. ImageIOCancellationToken and WorkState use OSAllocatedUnfairLock so cancellation can race safely with exactly-once continuation resumption.

The queue submission may run on a different worker thread, but GCD does not promise a fresh thread or a stable thread identity. The guarantee RawCull relies on is queue/executor separation, not a thread number.

7. Async streams, callbacks, and continuations

8. GCD, locks, and framework callbacks

GCD remains where the source API is callback-based or blocking:

• RsyncProcessStreaming uses a named serial termination queue to wait briefly, drain stdout/stderr, clear handlers, and then creates Task { @MainActor in ... } to finalize process state. The first hop avoids blocking the main actor; the return hop protects main-actor process/UI state.
• PTY and pipe callbacks create main-actor tasks before accessing RsyncProcess.
• A short DispatchQueue.main.asyncAfter in PTY cleanup deliberately defers final drain/close; it is a timing boundary, not an accidental thread correction.
• RawParserKit’s ImageIO bridge uses a global GCD queue specifically for blocking decode work.
• The two SwiftUI DispatchQueue.main.async calls deliberately defer scrolling by one run loop.

Locks are limited to synchronous callback-compatible state:

• SharedMemoryCache and CacheDelegate use OSAllocatedUnfairLock for counters, pressure state, and eviction history.
• ImageIOCancellationToken uses it for the cancellation bit.
• WorkState uses it to enforce exactly-once continuation completion.

Code must never hold one of these locks across await, call arbitrary client code while holding it, or use it as a substitute for actor ownership of asynchronous mutable state.

9. Sendable and nonisolated data flow

Values crossing task and actor boundaries are immutable or explicitly Sendable:

• RawCullCore declares its catalog, EXIF, saliency, burst grouping, boundary, ranking, and review values nonisolated and Sendable. Its algorithms are synchronous and stateless; concurrency is supplied by callers.
• RawParserKit exposes Sendable metadata/value types and actor-owned loaders. Images are consumed inside their owning isolation domain or encoded to Data before crossing a detached-task boundary.
• PhotoAnalysisKit batch requests contain @Sendable async input providers. FocusMaskEngine is @unchecked Sendable under the documented invariant that its CIContext has no mutable model/UI state and every operation receives immutable configuration.
• PhotoAIKit contracts are Sendable values and @Sendable provider/progress closures. CoreAISAM3Provider temporarily marks upstream runtime types @unchecked Sendable; the documented invariant is that they never leave that actor, and the conformances should be removed when upstream supplies correct annotations.
• CachedThumbnail, rsync ProcessHandlers, and lock/continuation bridge state use @unchecked Sendable only with a local immutability or synchronization invariant.

nonisolated does not mean “background thread.” It means the declaration is not owned by an actor. A synchronous nonisolated function runs on the calling thread; an async one follows its declared/caller isolation rules. Use @concurrent when execution must explicitly leave inherited actor isolation.

Package coverage

The app also pins external packages through PhotoAIKit, including Apple’s coreai-models. Their source is not part of the first-party checkouts under /Users/thomas/GitHub/RawCull; RawCull treats their async APIs as suspension points and does not make thread-affinity claims about their internals.

Cancellation, stale results, and backpressure

Cancellation is cooperative. Long-running loops check Task.isCancelled or Task.checkCancellation() before expensive steps and after suspension points. Task groups call cancelAll() when abandoning partial work. Continuation-based limiters remove and resume cancelled waiters. Framework work receives an explicit cancellation token where the underlying synchronous API cannot observe Swift task cancellation directly.

Cancellation alone does not prevent an old operation from publishing late. Main-actor workflows also use task identity, generation counters, selected catalog IDs, source IDs, or current-query checks before applying results. RawCullViewModel.cancelCatalogLoad() cancels catalog-related tasks, tells actors to cancel their inner work, resets dependent analysis state, and releases the active security-scoped resource.

Backpressure is intentional:

• RAW thumbnail decoding is capped at 6 and full-size decoding at 2 in RawParserKit.
• App batch extraction uses max(1, activeProcessorCount * 2).
• PhotoAnalysisKit and PhotoAIKit batch APIs maintain a sliding window rather than enqueueing every file at once.
• ThumbnailLoader parks excess callers with continuations instead of blocking threads.

Hop audit checklist

Before adding or changing concurrent work, answer these questions in code review:

1. Who owns the mutable state? Use @MainActor for UI state and an actor for shared background state.
2. Does the synchronous prefix need that actor? Keep a bare inherited Task only when work before the first await uses actor-owned state. Otherwise make the exit explicit with @concurrent.
3. Is parallelism structured? Prefer async let or a bounded task group. Store an unstructured task only when a synchronous entry point or independently cancellable lifetime requires it.
4. Is the operation blocking? An actor or @concurrent prevents main-actor occupation but does not make blocking safe for Swift’s cooperative pool. Use the GCD continuation bridge for long ImageIO/CoreImage or pipe-drain work.
5. What causes each hop? Name the actor call, @concurrent, detached task, group child, MainActor.run, or dispatch queue. Do not write “await moves to a background thread.”
6. How does work return? UI publication must occur through main-actor isolation; continuation waiters resume on their required executor automatically.
7. What crosses the boundary? Transfer Sendable values. Encode non-Sendable images to Data, or consume them inside the actor that owns them.
8. How does it stop? Define task ownership, cancellation checks, continuation cleanup, and stale-result rejection.
9. Is a thread change being observed? Remove correctness logic based on Thread.current or thread IDs. Thread logging is diagnostic only.
10. Is every hop wanted? If no correctness, responsiveness, or parallelism reason can be written beside the boundary, remove the boundary rather than relying on an accidental scheduling effect.