Repository navigation
docs/test(gc): establish a current collector source of truth and remove deleted knobs from live gates #7877
Copy link
Copy link
Labels
documentationImprovements or additions to documentationImprovements or additions to documentationtoolingDeveloper tooling, CI, tests, or release infrastructureDeveloper tooling, CI, tests, or release infrastructure
Description
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.- Most importantly, required CI still executes
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
- Contradictory status in the generational plan vs completion status
- Obsolete nursery knob and obsolete evacuation knob
- Statepoint experiment's obsolete top-level decision
- Current rooting doc says native/statepoint is the default
- “Authoritative” engine plan is 123 versions behind
- Deleted knob remains in live memory-stability modes and in the executable matrix
Proposed structure
Create one short, current GC architecture/operations page covering:
- shipped collector modes and actual env knobs;
- nursery/old-gen regions, copying vs fallback/full paths;
- root mechanism by target, barriers, weak processing, memory pressure, block pooling, and old-defrag status;
- the authoritative validation commands/workflows and which are required contexts;
- links to historical experiment journals clearly marked as historical/chronological evidence.
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
- A reader can identify the shipped GC/rooting defaults and supported knobs from one current page without reconciling chronological journals.
- Historical plans/experiments are labeled historical and no longer make an obsolete opening decision look current.
- Remove
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. - Add a cheap stale-knob check: executable scripts/docs claiming GC env knobs must match an allowlisted runtime/codegen parser (with explicit historical-doc exemptions).
- Correct the GC source path and freshness cadence.
- Update or retire the “authoritative” claim/tracker in
engine-plan.md.
Reactions are currently unavailable
Metadata
Metadata
Assignees
Labels
documentationImprovements or additions to documentationImprovements or additions to documentationtoolingDeveloper tooling, CI, tests, or release infrastructureDeveloper tooling, CI, tests, or release infrastructure
Activity
proggeramlug commentedon Aug 12, 2026
?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.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.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.docs/test(gc): re-derive the current collector page's claims instead …