flowchart TB
A["Unfinished producer counts"] --> B["Ready priority heap"]
B --> C{"Worker, phase limit and memory available?"}
C -- yes --> D["Read declared sources and compute"]
D --> E["Commit valid outputs"]
E --> F["Release task resources"]
F --> G["Decrement dependent counts"]
G --> B
C -- no --> H["Wait for an in-flight task to finish"]
H --> C
How the scheduler works
The scheduler has two independent gates. A task must have complete dependencies, and the executor must have capacity to run it. Priority ranks tasks that pass the dependency gate; it cannot make unfinished producer data safe to consume.
Constructing the ready set
TaskGraph contains one Task per phase/block pair. Ordinary dependencies come from region intersections: the valid regions written by producer tasks must cover the source region a consumer reads. Additional images have separate SourceDep lists so that readiness and coverage remain meaningful per operand.
The executor initializes an unfinished-dependency count for each task and an inverse map from producers to dependents. A task enters the ready set when its count reaches zero, subject to phase-wide gates. When a producer completes, the executor decrements the counts of its dependents and adds newly eligible work. It does not repeatedly scan every earlier image to rediscover readiness.
A task that reads a one-block halo may wait on several producer blocks. Even if its central producer finishes first, it cannot run until the neighbor outputs it needs are committed. Conversely, a local task need not wait for an unrelated faraway producer in an earlier phase unless a barrier says it must.
Ranking does not change legality
Hints supplies traversal preferences, concurrency and SchedulePriority. The ready set is a priority heap rather than a repeatedly sorted complete task list. SchedulePriority::PhaseMajor ranks earlier phases first; SchedulePriority::BlockMajor favors advancing available blocks through phases. Within those policies, spatial visit order changes locality.
The distinction is visible in a two-phase smoothing/threshold example. Once a threshold block’s smoothing producers finish, it may become ready before all smoothing tasks finish. Phase-major priority can still prefer remaining smoothing work. Block-major priority can prefer thresholding that block. Both answers must be identical because neither policy changes its source region or the operations evaluated there.
Ready-set priority is not kernel fusion and does not remove phase images. It also does not prove better cache behavior: moving farther through the pipeline can keep several images live and compete with other workers’ halo reads.
Resource admission streams work
The ordinary executor admits as many ready tasks as its worker slots and active memory policy permit. It waits for a completion, releases that task’s resources, and fills the newly available room. Tasks do not have to finish in fixed waves behind the slowest task in a batch.
An operation can add a BlockOp::max_in_flight limit. For example, a kernel with a scarce backend resource can restrict concurrent applications independently of the process’s CPU worker count. Per-phase counts enforce that restriction without pretending the entire workflow has fewer workers.
Hints::memory connects admission to a shared MemoryBudget. The estimated charge covers live chain buffers, additional source operands and declared scratch. Cache holders can be asked to reclaim opportunistic allocations when compute needs room. Near the cap, resident-set samples can raise the charge when observations exceed the modeled allocation.
There is an important progress fallback: the current executor can admit a single oversized task when nothing else is in flight. Admission is therefore not an allocator-enforced hard process limit. Automatic grid selection can reject such an oversized candidate earlier; manually supplied plans need their own honest workspace checks. See memory and storage.
Preparation and phase-wide work
FragmentOp::prepare can inspect declared metadata before ordinary pixel reads. BlockPreparation either provides a completed result or requests bounded work. A known-empty task can emit the required empty fragments or constant output without decoding its image window. Missing activity summaries must remain unknown, rather than being treated as evidence of emptiness.
A barrier phase holds its tasks until every earlier phase is complete. The executor then runs FragmentOp::reduce once and shares its result before the phase’s block applications enter the ready heap. The block applications can still run concurrently. Generic iterative image phases use their own coordinated substage loop; they cannot be dispatched as unrelated single-pass tasks.
Completion, lifetime and diagnostics
A task is complete after its required outputs are written, not after its kernel returns a temporary buffer. Only then may dependent tasks read it. Intermediate images become discardable after their final readers finish, subject to Hints::keep_images and published-output retention.
Failures stop new admission and allow in-flight work to settle before the error is returned. A task’s partial output is not a valid completed producer. In a distributed run, the coordinator applies corresponding ownership and committed visibility rules; parallel execution describes recovery.
Event records provide the evidence for diagnosis: readiness/admission, read, compute, write, waits and phase transitions answer different questions. A high worker count with idle CPU time may mean dependency starvation, memory admission, a backend concurrency limit or storage latency. Inspect those causes separately before changing the algorithm or its required halo.