Module parallel_budget 

How many workers independent items may use together, from the CPUs allowed, the memory free and a measured ceiling. What: How many workers a set of independent items may use together: the CPUs the process is allowed minus a margin, the memory that is free, an optional ceiling the shared storage was measured to need, and the person’s own cap. Why: Real jobs may use almost the whole host, so a bare constant is wrong in both directions: too low on a large host, too high inside a container with a quota or on a host whose memory other sessions already hold. The budget is derived from the facts of the moment, and the facts are a value so a control can state them.

In TS you’d write (pseudocode):

const workers = workerBudget({ items: 48, perItemMemory: 256 * MiB, ceiling: undefined, cap: undefined, host: readHost() });

Structs

BudgetRequest

What: What one budget asks for. Why: One value keeps the call sites short and names every input.

HostResources

What: The facts a budget is derived from. Why: Reading the host is one place and the arithmetic another, so a control states a host of any size.

Constants

PARALLEL_BREAK_EVEN_ENTRIES

The smallest number of entries at which creating them on several threads beat creating them on one, for the three places that make files by cloning: 16 entries. Measured with the copy stage (copy_manifest_entries), the install (install_snapshot with a recorder that syncs every batch) and clone_tree, each forced to 1, 2, 4 and 8 workers on reflinked trees of this repository (2026-11-03, medians of five runs in alternating orders, other sessions running, a debug build): clone_tree took 0.6 ms on one thread and 0.5 to 0.6 ms on 2, 4 and 8 for 10 entries, and 1.8 ms against 1.2 ms for 30; the copy stage 1.1 ms against 0.7 ms for 30, 3.6 ms against 1.9 ms for 90, 397.6 ms against 104.4 ms for 9,301; the install 1.6 ms against 1.3 ms for 30, 14.8 ms against 8.9 ms for 296, 500.2 ms against 244.9 ms for 9,301. The parallel path was never slower from 16 entries up. The coordinator’s pick under the owner’s delegation, open to the owner’s veto (doc/planning/cli-git-shipped-limits-audit.md, “Picked for these follow-ups”, thresholds of the copy stage and the install, option A).

SLICE_MEMORY

The bytes one slice of a file-copy or file-removal job holds at its peak: a batch of entries and the handles it opens, estimated at sixteen mebibytes. The estimate was checked against clone_tree: its resident size grew by 1.9 MiB over a pre-clone level of 21.6 MiB (peak 24,080 KiB) for 22,718 entries at 16 workers, so a slice holds far less than sixteen mebibytes. The estimate is kept as a conservative upper bound because the copy stage itself was not measured; the coordinator’s pick under the owner’s delegation, open to the owner’s veto.

Functions

control_group_path

The path of the unified (version 2) control group in /proc/self/cgroup text: the line that starts with 0::.

cpu_margin

The threads left free for everything else: an eighth of them, at least one, and none when the process may run only two.

headroom_from

The bytes a control group can still take under its limit: max minus current, nothing when there is no numeric limit.

memory_available_from

The MemAvailable figure of /proc/meminfo text, in bytes.

sliced_workers

What: The workers for file-tree jobs that split their entries into slices: the host’s budget up to a ceiling the filesystem was measured or chosen to use. Why: The copy, install and removal of a worktree’s files share the filesystem’s metadata locks, so a ceiling stays, but the CPUs left free for other sessions and the memory of the control group bound them too, which a bare min(available, 8) ignored.

worker_budget

What: The number of workers for independent items. Why: The least of the items, the CPUs minus the margin, the memory that is free over what one item holds, the ceiling the storage was measured to use, and the person’s cap; never fewer than one, so a starved host still makes progress.