Skip to content

docs(gc): plan status after #7339/#7340/#7342 — the 0→2 spine is done #7345

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
proggeramlug merged 1 commit into from
Aug 4, 2026
Merged

docs(gc): plan status after #7339/#7340/#7342 — the 0→2 spine is done #7345

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
30 changes: 24 additions & 6 deletions docs/engine-plan.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -28,8 +28,8 @@ pointer has **three different homes**, each needing a different mechanism.
|---|---|---|---|---|
| **0** | *enabler* | — | **in-process LLVM** (#7241) | ✅ **landed** (#7301) |
| 1 | `perry-codegen` lowering code | #7192, #7206, #7211 | `Raw`/`Rooted` borrow discipline | proposed |
| 2 | emitted code's liveness | #7280, #7271, #7252, #7243 | statepoints (#7108, #7174) | ✅ **landed opt-in** (#7314) |
| 3 | `perry-runtime` hand-written Rust | #7249, #7239, #7226, #7231 | `RuntimeHandleScope`, non-optional | not started |
| 2 | emitted code's liveness | #7280, #7271, #7252, #7243 | statepoints (#7108, #7174) | ✅ **landed opt-in** (#7314), **usable** (#7339, #7340) |
| 3 | `perry-runtime` hand-written Rust | #7249, #7239, #7226, #7231 | `RuntimeHandleScope`, non-optional | mechanism exists (675 uses), **still optional**; 54 open catches (#7341) |
Comment on lines +31 to +32

@coderabbitai coderabbitai Bot Aug 4, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🗄️ Data Integrity & Integration | 🟠 Major | ⚡ Quick win

Make RuntimeHandleScope a real adoption gate.

Lines 31-32 use conflicting statuses: the mechanism is “non-optional”, but the status says “still optional”. Lines 362-364 then list only llvm-inprocess and x86-64 as adoption gates, although this document states that statepoints do not cover layer 3 and 54 catches remain.

Require RuntimeHandleScope integration before statepoints become the default, or define the safety boundary that permits adoption while those catches remain open.

Also applies to: 362-364

🤖 Prompt for AI Agents 
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@docs/engine-plan.md` around lines 31 - 32, Update the layer 3 status and the
adoption-gate guidance to use one consistent `RuntimeHandleScope` policy: either
require its integration before making statepoints the default, or explicitly
define the safety boundary that allows adoption while the 54 catches remain
open. Ensure the entries around the statepoints and `RuntimeHandleScope` rows,
including the later `llvm-inprocess` and x86-64 gates, reflect that policy
without contradictory “non-optional” and “still optional” statuses.


**Order is 0 → 2. Layers 1 and 3 are independent and can proceed now.**
#7108 measured statepoints viable but blocked: *"the text-IR-plus-stock-clang
Expand Down Expand Up @@ -342,8 +342,26 @@ only), but it means one published figure reproduces only inside the checkout.

## Sequencing

1. **Now, independent:** layer 1 and layer 3 rooting; #7286's index range proof.
2. **Next:** in-process LLVM (#7241) → statepoints (#7108/#7174).
3. **After the collector is trustworthy:** re-derive the RSS numbers (#7056).
4. **Do not** re-measure GC pacing, or update the README's performance table,
**Updated 2026-08-04.** Step 2 below is complete: layer 0 landed (#7301), layer 2
landed (#7314) and became *reachable* (#7339) and *selectable* (#7340). The spine
`0 → 2` is done, so the ordering that remains is:

1. ~~**Next:** in-process LLVM (#7241) → statepoints (#7108/#7174).~~ **Done.**
Comment on lines +345 to +349

@coderabbitai coderabbitai Bot Aug 4, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win

Fix the stale step reference.

Line 345 says “Step 2 below is complete”, but the current list marks item 1 as complete and item 2 as the root-density prerequisite. Change “Step 2” to “Step 1”, or remove the step number.

🤖 Prompt for AI Agents 
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@docs/engine-plan.md` around lines 345 - 349, Update the progress note in the
documentation to refer to “Step 1” instead of “Step 2,” matching the completed
item currently marked in the list; leave the surrounding ordering and completion
details unchanged.

2. **Reduce root density — now a PREREQUISITE, not a nice-to-have.** Statepoints
cost **+18.95% binary size on root-dense code and +0% on root-free code**
(measured, see Part 1), and 97% of that is `__text`. Adopting them as the
default today therefore *regresses* the owner's stated goal of minimal binary
size. Fewer roots fixes that, and it is the same lever #7296 already proved
worth 9.9× on `matmul`, so speed and size pull together here rather than
trading off. The plan predicted this lever but flagged it "expected, not
measured. Layer 2 must prove it first" — layer 2 has now landed, so it can be
measured.
3. **Layers 1 and 3, independent of the above.** Layer 3's instrument is now
aimed (#7342 arm 4) and has a 54-item worklist (#7341) whose dominant
signature is a stale `GC_TYPE_STRING` at minor #0.
4. **Then the adoption fork.** Flipping statepoints on by default additionally
needs `llvm-inprocess` to become a default cargo feature (#7301's scope, since
RS4GC is the only invoke-capable backend) and x86-64 to work (#7333).
5. **After the collector is trustworthy:** re-derive the RSS numbers (#7056).
6. **Do not** re-measure GC pacing, or update the README's performance table,
mid-cycle.
Loading