Files
horizon-airdef/docs/culling-empty.md
T

2.1 KiB

Avoid allocating iterators for empty culling whitelists

A local game JFR found HashMap.KeySet iterator allocation in Entity Culling's dynamic entity/block-entity whitelist checks on CullThread. The pinned 1.11.2 methods create a set iterator before discovering that there are no handlers.

The optional hook returns the JDK's shared empty iterator while the live set is empty. It checks that set every call; it does not cache a whitelist, remember an empty state, skip a registered handler, or alter culling decisions. Nonempty sets use their original iterator, callback order, type guard and short circuit. No per-call callback object is introduced by the hook.

Use the culling-empty profile for an isolated comparison with m2-balanced. Both keep the same graphics, LOD radius, worker budget and other controller settings. The hook is opt-in, restricted to Entity Culling 1.11.2, and can be disabled with enabled=false in config/horizon-culling-empty.properties and a restart. Frame reports record empty_culling_whitelist; the CLI and offline viewer disclose a difference as an experiment variable.

python tools/test_culling_empty.py runs the actual publisher methods inside Fabric. It checks empty iterator dispatch, registration after initialization, duplicate registration, real block-entity callback order/short circuit, null and wrong-type inputs, and returning to an empty state. The menu-only fixture does not exercise callbacks using a valid world entity; nonempty entity iteration uses the original implementation. Private instrumentation and fixture JARs never enter release packs. Full game logs remain private.

A local warmed loop of four million empty checks allocated 128,001,248 bytes upstream versus 1,248 with the hook. CPU was 41 ms versus 33 ms in that single observation. These counts isolate this allocation path; JIT escape analysis can produce different results in other calling contexts. They are not game FPS, whole-game RAM, statistical speed estimates or Mac GPU results. Live culling thread profiles, matching workloads and repeated hardware tests remain needed.