Minor heap sizing after the OCaml 5.x multicore GC transition: retuning -I for parallel workloads

Short answer

-I (or OCAMLRUNPARAM=i=...) sets the size of each domain's private minor heap arena — it is not a global budget. On OCaml 5.1+, the value does not need to shrink as you add domains; the correct mental model is "the 4.x heuristic, applied per domain, with total memory now scaling linearly with domain count." The old rule — grow the minor heap until major collections become rare — still works, but you evaluate it per domain and watch aggregate memory instead of a single heap.

Is -I per domain, and should it scale down with domain count?

Yes, per domain. Every domain allocates into its own minor heap arena and promotes survivors into the shared major heap, so eight domains at -I 256k words reserve roughly eight times the arena memory of one domain. That has two consequences:

• Throughput tuning: the optimal per-domain size is driven by each domain's allocation rate and object survival profile, not by the domain count. If a single domain was happy at 256k words on 4.x, each domain on 5.x likely wants something in the same range.
• Memory budget: if the host is memory-constrained, the knob you turn is the trade-off between domain count and per-domain arena size — not silently starving every domain. Halving -I across 16 domains to fit RAM usually costs more in minor GC churn than running fewer, well-fed domains.

Which Gc statistics point at minor heap size vs. synchronization?

Gc.stat aggregates counters across all domains, so normalize by active domain count (or use per-domain stats where your version exposes them) before comparing. The useful signals:

• Promotion ratio: promoted_words / minor_words. A persistently high ratio (roughly above 0.5) means too much survives each minor cycle — the arena is too small and you're paying promotion and major-heap pressure for it. Getting it under ~0.3 is a reasonable target for short-lived workloads.
• Collection counts: minor_collections climbing steeply while major_collections stays flat is the classic undersized-minor-heap signature. If minor collections are rare but major collections are frequent, your problem is major heap sizing or live data volume — enlarging -I won't fix it.
• Synchronization instead: if per-domain promotion ratios look healthy but latency spikes correlate with major slice work, suspect the stop-the-world phases of the parallel major GC rather than arena size. That shows up as flat minor stats with rising major_collections and compactions, plus wall-clock stalls that don't track allocation rate.

What actually changed from 4.x?

The promotion policy itself is conceptually familiar — survivors of a minor collection are copied to the major heap — but the structure changed: one global stop-the-world minor heap became per-domain arenas promoting into a shared major heap collected by a parallel mark-and-sweep. Two practical invalidations of 4.x folklore:

1. Any guide quoting a total minor heap size must be reinterpreted as a per-domain figure; applying the old number as a global total under-provisions every domain by a factor of N.
2. "Make minor collections cheap" is no longer the whole story — promotion now feeds a shared structure, so excessive promotion in one domain can amplify major GC work (and its synchronization) for all of them.

A defensible sizing procedure

1. Fix the domain count, snapshot Gc.stat at steady state, and compute per-domain promotion ratio and minor collection rate.
2. Sweep -I (e.g., 64k, 128k, 256k, 512k words) via OCAMLRUNPARAM=i=... and pick the smallest value where the promotion ratio drops below ~0.3 and minor collections plateau.
3. Confirm major_collections did not rise and that total arena memory (-I × domains) fits your host budget; if tracing is available in your build, check per-domain occupancy stays comfortably below the arena size.

One caveat worth flagging: exact counter semantics and the availability of per-domain statistics vary across 5.x point releases, so verify against the Gc module documentation for your specific compiler version before baking numbers into production config.