Blocks and memory

Choose blocks and concurrency together. A block is the core a task owns, while its input includes required neighborhoods and it may also hold extra sources, intermediate arrays and scratch. The core’s byte size alone is therefore a poor estimate of the memory needed to start another worker.

Quantify halo amplification first

For a cubic core edge b and symmetric halo radius r, an interior task reads approximately (b+2r)^3 voxels and owns b^3 outputs. The ratio is

\[ A = \frac{(b+2r)^3}{b^3}. \]

At radius eight, a 32-cube reads 3.375 times its core, whereas a 128-cube reads about 1.424 times its core. This is geometric amplification before considering compression, cache hits, true-image-edge clipping or algorithm-specific reuse. It is not a prediction that runtime changes by the same factor.

For anisotropic images, use each axis separately:

\[ A = \prod_{a\in\{z,y,x\}}\frac{b_a+\ell_a+h_a}{b_a}. \]

An operation with no z reach and a broad y/x neighborhood may benefit from z slabs that leave the in-plane axes wide. Tile-anchored FFT operations have an additional reason to choose particular edges: matching their tile stride avoids the extra unaligned reach described in halo kinds.

An illustrative working-set calculation

Suppose a task owns a 128-cube of f64 output, reads a radius-eight input, and needs one scratch array the size of that read. These are illustrative declared buffers, not the exact contract of a particular operation:

Buffer Shape Bytes expressed as MiB
Input including halo 144³ f64 22.78
Owned output 128³ f64 16.00
Read-sized scratch 144³ f64 22.78
Sum 61.56

Four concurrent tasks already account for about 246 MiB before shared caches, codec workspaces, extra channels, any wider chain intermediates and application allocations. A real operation may allocate an output wider than its final core, so even this table is not a universal formula for admission.

Changing the core to 256³ reduces relative halo overhead but makes the output alone 128 MiB. Adding workers without revisiting block size can therefore turn a previously feasible run into a memory problem.

State the process policy

MemoryCap::resolve chooses the cap from an explicit value, supported environment variables, a cgroup limit or a machine-derived fallback. A smaller applicable cgroup limit wins over a larger stated cap. The supported variables include BLOCKFLOW_MEMORY_CAP and the older BLOCKFLOW_MEMORY_BUDGET_BYTES. The resolved policy is installed with budget::set_process_cap.

A binding cap reserves an eighth, at least 128 MiB and no more than half the cap, for overhead outside active block work. At an explicit 1 GiB cap, this reserve is 128 MiB; it does not imply the remaining 896 MiB can all be allocated to the simple three-buffer estimate above.

The shared MemoryBudget uses leases for active work and opportunistic cache retention. Cache allocations can yield when work needs room. This is cooperative accounting, not an allocator that forcibly revokes arbitrary memory or a proof that every third-party allocation stays under process RSS.

flowchart TB
  A["Block shape, reach and source operands"] --> B["Input, output, intermediates and scratch"]
  B --> C["Per-task memory charge"]
  D["Process policy and shared retention"] --> E["Available compute budget"]
  C --> F["Admit tasks that fit"]
  E --> F
  F --> G["Completion releases resources"]
  G --> F
Figure 1: Geometry establishes a per-task requirement; available memory then limits how many tasks may be active together.

Let the grid chooser compare alternatives

strategy::choose_grid evaluates candidate grids against a Host and a CostModel. It builds the actual assembly for each grid, prices phase work and selects a feasible predicted makespan. The returned ChosenGrid::active records per-phase active sets; fewer blocks may run at once when all requested workers would not fit. This is more informative than counting logical CPUs.

If even one task cannot fit, reducing concurrency is insufficient. Change the grid, split a costly composition, use an algorithm with a bounded state route, or raise the cap. A whole-axis dependency may limit which dimension can shrink; a whole-volume solve cannot be made local by cutting its surrounding filters.

When an example exposes --block, --workers and --memory-mb, record them alongside the algorithm parameters. Those flags are CLI-specific; not every example uses the same names. Inspect the resulting phase geometry and measure a representative crop before choosing a full-image configuration.

For the complete calculation behind one actual-shaped task, see the execution story: it separates the owned core, requested halo region and full decoded source chunks. The automatic-choice guide distinguishes caller settings from planner selection and backend output chunking.