flowchart TB B["Process memory budget"] --> C["Reserved active compute"] B --> K["Opportunistic cache retention"] B --> P["Opportunistic prefetch retention"] C --> W["Inputs, outputs, live intermediates and scratch"] S["Compressed chunk storage"] --> K K --> W W --> O["Committed output chunks"]
Memory, caches and storage
Output-core size is only one term in a task’s working set. A filter can hold a halo-expanded input, output, additional channels and several intermediate arrays. FFT or model workspaces can exceed the final output size. Bounded processing requires every relevant lifetime and scratch allocation to be understood.
Account for what is live together
Decomposition estimates active bytes from the Chain evaluation and phase geometry. A sequential chain can release an intermediate after its last consumer; a branch may need several outputs live together unless Combine supports an incremental fold. A fetched source image remains an operand even if its values were not produced by the current phase.
Consider a 64-cube f64 core. It is 2 MiB. With an eight-voxel symmetric halo, the 80-cube input is about 3.91 MiB. Three equally sized temporary arrays already add about 11.72 MiB before the output, secondary inputs and decoder scratch. Multiplying the 2 MiB core by eight workers would miss most of the active memory. The exact shapes in a chain can differ; use its lifetime-aware estimate rather than assuming every intermediate equals the core.
FragmentOp::scratch_bytes declares extra block-local allocations outside the ordinary image buffers. A reduction can also create shared phase state. If that state grows with object count or retained boundary fragments, a small image block does not make it constant-sized. Whole-volume iterative state and application-owned arrays require separate consideration.
Budget leases coordinate cooperating components
MemoryCap resolves the process resource policy and reserve. MemoryBudget coordinates leases against its usable total. A Lease represents accounted ownership; dropping it returns the charge. It is not a custom allocator that can intercept every allocation made by Rust or a model backend.
Reserved compute and Class::Opportunistic retention serve different purposes. A cache or prefetcher may keep data only while opportunity exists. Through the Reclaim interface, a cooperating holder can evict entries and release leases when active computation needs space. The budget asks the holder to reclaim; it does not forcibly invalidate arbitrary borrowed memory.
Hints::memory controls ordinary task admission. Multiple tasks run when their charges fit together, and fewer run when memory is tight. Near-cap sampling via ResidentSampler helps account for process memory outside explicit leases and observed task charges that exceed estimates. This feedback can reduce later concurrency; it cannot make an already allocated oversized kernel fit.
The current ordinary executor admits a lone task even when its charge exceeds the budget, to avoid permanent admission deadlock. In contrast, strategy::price_under_budget rejects a planning candidate when one active block cannot fit. These are different contracts. A caller manually assembling a large block must not interpret successful admission as proof of a hard RSS cap. Some examples add conservative up-front checks for precisely this reason.
Chunk geometry and compute geometry are independent
ZarrEnvironment reads and writes chunk-backed images. Its storage chunks do not have to equal compute blocks. A block’s halo can overlap several chunks, and different blocks can revisit the same compressed chunk. The filesystem page cache may save physical I/O while still requiring decompression; an in-process decoded cache can avoid that additional work when reuse is real.
ChunkCache supports decoded and encoded retention under a shared budget. CachingSource adapts a region source to that cache path. A smaller cache is not necessarily a correctness problem; it can simply increase repeated fetches or decoding. Concurrent readers, element types and source identity must be part of the key so unrelated arrays do not reuse one another’s bytes.
Block geometry therefore trades arithmetic, I/O and cache reuse together. A coarse block can reduce duplicated halos but consume all space that might have retained neighboring chunks. A fine grid can expose parallelism while paying more repeated source work. Use measured cache statistics and source-read events to determine which resource dominates.
Prefetch is speculative retention, not a dependency
Prefetcher accepts declared future RegionRequest values through an AccessPlan. It performs reads on its own fetch workers and tries to retain results opportunistically. A request that cannot be retained must not block compute waiting for the same budget. Cancelled or reordered work can make those reads wasteful even when the prediction was valid when registered.
The existence of the component and a prefetch-depth hint does not mean every execution/storage route overlaps reads and computation. Verify construction and use on the chosen path. Prefetched bytes also do not establish producer completion: the task graph still determines when an intermediate is legal to read.
Storage lifetime is another budget
Each materialised phase creates a stored intermediate unless it writes only fragments. Internal images can be discarded after their last reader finishes. Hints::keep_images deliberately retains selected intermediates for diagnosis; Hints::release_images allows the caller to give up otherwise published images once they are no longer needed. Keeping every image can dominate disk use even when the active RAM working set is bounded.
Finally, transient fragments and persistent diagnostic outputs have different lifetimes. Releasing temporary state must preserve the final image metadata and outputs that another tool will read. The data model identifies those outputs; fusion explains when eliminating a materialised image is worth additional halo computation.