Repository navigation
docs/test(gc): establish a current collector source of truth and remove deleted knobs from live gates #7877
Description
Activity
?Reopening after the v0.5.1473?v0.5.1481 re-audit: the new ?current source of truth? drifted in the same landing train that created it.
Current false/stale statements:
docs/src/internals/garbage-collector.mdsays full/fallback weak processing still walks the whole arena atomically and cites perf(gc): full/fallback weak processing is an unsliced O(total heap) atomic pause #7874. perf(gc): slice full weak processing by holder #7892 replaced that with registry-scoped, holder-sliced processing and closed perf(gc): full/fallback weak processing is an unsliced O(total heap) atomic pause #7874.- The same page says the block pool is a 64 MiB per-thread allowance that critical pressure and device budgets do not drain/resize, citing memory(gc): critical pressure and device budgets do not drain or bound the per-thread 64 MiB block pool #7875. fix(gc): bound and drain recycled block pool #7889 made the cap process-wide and budget-scaled and added sticky critical-pressure drains, then closed memory(gc): critical pressure and device budgets do not drain or bound the per-thread 64 MiB block pool #7875.
docs/src/internals/memory-model.mdstill presents a fixedPROMOTION_AGE = 2and describes tenured objects as initially remaining physically in nursery pending telemetry-driven evacuation. Current copying GC has an adaptive 1?4 survival threshold (gc/tenuring.rs), promote-on-first-copy locking, direct survivor promotion to old-gen, and whole-block in-place promotion including the optional untraced path.- The current page does not document perf: shapes 0.139 -> 0.061 s (beats node) and pipeline 0.240 -> 0.175 s — a 2000-element array was born immortal, and this.vals[i]=v had no inline arm #7895's type-dependent born-old thresholds (16 KiB pointer-free vs 128 KiB pointer-bearing), even though that materially changes nursery/old-gen behavior and memory retention.
- The ratchet README still says
js_arena_statssums block offsets and labels that limitation ?UNCHANGED?; fix(gc): report live arena bytes after collection (#7879) #7886 routes it through the live census. That text now misdirects ratchet triage.
The new
check_gc_env_knobs.pygate is working and all its self/live checks pass on Windows. The remaining gap is architectural claim drift: later GC PRs can update code and close the cited issue without being required to update the current page/ratchet semantics.Suggested acceptance addition: add a PR checklist or cheap source-marker test for collector changes that touch
weakref.rs, pool policy, tenuring/promotion, or heap accounting, and require the current GC page plus ratchet metric definitions to be reviewed in the same PR. At minimum, remove issue-status prose that silently becomes false when the issue closes.One more concrete drift item:
memory-model.md's entire Source map still points to the deleted monolithiccrates/perry-runtime/src/gc.rs(including obsolete line numbers). The implementation is nowsrc/gc/mod.rsplus the split module tree, so none of those source links identifies a real file on currentmain.- added a commit that references this issue
on Aug 12, 2026
Summary
The GC documentation no longer has a reliable current entry point, and a deleted collector knob remains in an executable CI stress script. After ~200 GC-heavy commits in four days, several documents present mutually exclusive states as current.
Concrete drift on
main(79d2f59ed, v0.5.1473):docs/generational-gc-plan.mdopens with “proposed, pre-implementation” but ends with all implementation phases complete. It still specifies nonexistentPERRY_NURSERY_MBand repeatedly uses deletedPERRY_GEN_GC_EVACUATE.docs/statepoint-gc-experiment.mdopens with “Keep the shadow stack as the default” and later labels shadow as default, whiledocs/engine-plan.mdandgc-rooting-invariant.mdsay target-aware native statepoints are the shipped default.docs/engine-plan.mdcalls itself authoritative, points at closed tracker Engine plan tracker — GC correctness and performance (routing only; docs/engine-plan.md is authoritative) #7294, and is synced only through v0.5.1350; the repository is now v0.5.1473. It still says the statepoint lowering has no static root-dominance checker even though gc: teach the root-dominance checker to read statepoint relocation bundles #7663 and the current workflow added one.CLAUDE.mdpoints atcrates/perry-runtime/src/gc.rs; GC is now thesrc/gc/module tree.docs/src/testing/ci-gate-scheduling.mdandscripts/gate_freshness.jsonsay gate freshness runs hourly, while the workflow cron is every two hours.scripts/run_memory_stability_tests.sh, whose mode matrix and architecture workload environment containPERRY_GEN_GC_EVACUATE=1/0. That knob was deleted in gc: PERRY_GEN_GC_EVACUATE=0 moves zero cells on all 12 gc-ratchet probes — the knob's off-state is unexercised #7611, so those tokens claim a mode distinction that no longer exists.Evidence
Proposed structure
Create one short, current GC architecture/operations page covering:
Do not rewrite valuable experiment history. Put a prominent dated supersession banner and a current conclusion at the top, then link to the current page.
Acceptance criteria
PERRY_GEN_GC_EVACUATEfrom executable test environments, source docs, and generated translation source; replace each test arm with the actual knob/subject it intends to exercise.engine-plan.md.