pub fn set_soft_yield_min_boxes(boxes: usize)Expand description
Minimum boxes that must accumulate before the soft-RSS yield branch may fire (the box-budget branch is unaffected and still yields on its own).
The soft-RSS test is a LEVEL test with no hysteresis: rss > watermark. A
document whose irreducible resident floor sits above the watermark therefore
latches it on permanently and yields at every legal seam, accumulating
almost nothing between yields. Measured on the 131 MB witness at
--max-memory 48000 (watermark 12 GB, pass-1 RSS 13.3-14.9 GB — above it
for the entire run): 24,051,712 yields producing 459,579 segments
averaging 5.5 KB, against a box budget of ~2.0 M boxes that would on its
own have yielded ~12 times. The same binary on a witness that never crosses
its watermark yields 8 times.
A floor restores the trigger’s intent — “respond to memory pressure sooner than the box budget would” — without the degenerate per-seam case. 1024 boxes is ~2.5 MB of box memory at the measured 2416 B/box, i.e. negligible against any watermark large enough to matter, so the pressure response stays effectively immediate while the yield count drops by ~3 orders of magnitude.
The floor is waived under real pressure — see soft_yield_is_urgent.
The soft-RSS branch exists because “the box budget alone assumes a per-box
footprint; on content whose real cost per box is higher (math-dense trees),
RSS crosses the ceiling long before the box count does”. A floor that
applied unconditionally would blunt that valve for exactly the pathological
input it was added for: 1024 boxes of ordinary content is ~2.5 MB, but 1024
boxes of something pathological is unbounded, and the fuse could fire inside
one un-yielded window. So above a higher RSS mark the floor is ignored.
Env-overridable for calibration only (LATEXML_SOFT_YIELD_MIN_BOXES),
deliberately not a CLI flag — same reasoning as LATEXML_SPILL_AT_MIB.
Override the soft-RSS floor directly, bypassing the env lookup. For tests
that need to drive the degenerate (floor = 1) and fixed (floor = N) regimes
in one process — see 115_soft_yield_floor.