Skip to content

docs(plan): both statepoint adoption gates are closed; record the platform matrix #7367

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(plan): both statepoint adoption gates are closed; record the platform matrix #7367

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
62 changes: 61 additions & 1 deletion docs/engine-plan.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -215,6 +215,65 @@ flipping it globally, and neither is correctness:
So the honest state is: *aarch64-viable, globally blocked on two pieces of scope
that are both already identified.*

### ★ Update 2026-08-04 — both adoption gates are closed; statepoints run everywhere

The section above closes with *"aarch64-viable, globally blocked on two pieces
of scope."* Both pieces are now done, so that sentence should not be carried
forward either.
Comment on lines +218 to +222

@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 | 🟡 Minor | ⚡ Quick win

Clarify the scope and status of the remaining adoption gates.

Lines [218]-[222] say both adoption gates are closed. Lines [271]-[275] then retain llvm-inprocess and root density as adoption conditions. Use “platform gates” in the heading if that is intended.

Also name the Cargo package. The supplied Cargo context shows llvm-inprocess is default in crates/perry-codegen/Cargo.toml but opt-in in crates/perry/Cargo.toml. State that adoption still requires the feature to become default in crates/perry and a decision on the root-density binary-size cost.

Also applies to: 271-275, 423-424

🤖 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 218 - 222, Update the "Update 2026-08-04"
section heading and content to clarify whether the closed gates are "platform
gates" or "adoption gates" rather than conflicting with the adoption conditions
still listed in sections 271-275 and 423-424. Remove the outdated sentence about
"aarch64-viable, globally blocked on two pieces of scope." Then explicitly name
the Cargo packages (crates/perry-codegen and crates/perry) and state that
adoption of llvm-inprocess still requires the feature to become default in
crates/perry along with a decision on the root-density binary-size cost. Ensure
the remaining adoption conditions are clearly distinguished from any fully
closed gates across all three affected sections.


**1. x86-64 is no longer blocked (#7333 → #7349).** The `_Unwind_GetGR(ctx, 7)`
segfault is real and unfixable as stated — libgcc tracks only the columns CFI
restores, and RSP is derived from the CFA rather than tracked. The fix was to
stop asking for it: #7349 derives the SP-relative base from `_Unwind_GetCFA`,
which does work, with a per-architecture return-address adjustment (x86-64's
`call` pushes a return address, aarch64's `bl` does not — 8 bytes vs 0).
x86-64 Linux is a first-class arm of `gc-native-roots`, not a pinned refusal;
`statepoints-refuse-x86` is deleted along with the job that hosted it.

**2. Windows works (#7354 → #7355).** `RtlVirtualUnwind` steps a `CONTEXT`
outward and yields `Rip`/`Rsp`/`Rbp` directly, so the CFA derivation above is
not needed there. It is the one walker with no Itanium unwinder beneath it.

**Platform status, measured rather than assumed:**

| shape | map | walker | state |
|---|---|---|---|
| aarch64 + Mach-O (macOS/iOS/iPadOS/tvOS) | `__PERRY_GCMAP` | x29 chain, unwinder fallback | ✅ CI arm |
| x86-64 + ELF | `.perry_gcmap` | unwinder + CFA-derived SP | ✅ CI arm |
| x86-64 + PE | `.pgcmap` | `RtlVirtualUnwind` | ✅ CI arm |
| aarch64 + ELF | `.perry_gcmap` | x29 chain | ✅ CI arm (#7360) |
| watchOS / visionOS | ready | ready | compiler-side ✅; see below |
| ARM64 Windows | refused | none | open |

watchOS and visionOS are **not** blocked by Perry. `cargo check -p perry-runtime`
succeeds on stable for both with any feature set excluding `dyn-eval`; with it,
they fail three crates away in `psm`, whose Mach-O guard enumerates
`darwin/macos/ios/tvos` and omits `watchos`/`visionos`, so both fall to the ELF
branch and emit `.type`/`.size`. Verified by patching that one line: both then
build with full default features. They regressed on 2026-07-18 when `dyn-eval`
joined `default` (#6584) — nothing about the platforms changed. #7364 pins the
whole Apple target set compiler-side.

**One mechanism, not two.** `PERRY_STATEPOINTS` is deleted and the plain-map
bridge with it; `PERRY_RS4GC` is the only spelling, and the last stale references
went in #7362. The kill-policy line above — *"a mode that still exists is a
decision that hasn't been made"* — no longer applies to this pair, because the
Comment on lines +257 to +260

@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

Update the binary-size experiment to use the current mode name.

Line [257] states that PERRY_STATEPOINTS was deleted and that PERRY_RS4GC is the only spelling. The binary-size section still labels the statepoint arm as PERRY_STATEPOINTS=1 at Lines [282]-[283]. Replace it with PERRY_RS4GC=1, or mark the old spelling as historical and provide the current equivalent.

🤖 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 257 - 260, Update the binary-size
experiment’s statepoint arm to use the current PERRY_RS4GC=1 mode name instead
of PERRY_STATEPOINTS=1, or explicitly label the old spelling as historical while
providing PERRY_RS4GC=1 as its equivalent.

losing mode stopped compiling.

**What the gate now proves.** Until 2026-08-04 the Unix arms reported
`frames_visited: 7, locations_visited: 0` — they would have passed with a walker
that visited nothing, since other root sources covered the probes. Windows
walked deep only by accident of heap sizing. `11_collect_at_depth` collects at
maximum recursion depth with one live root per frame (macOS 228/221, x86-64
Linux 231/221, both byte-matching the oracle), so `--require-locations` now
gates every arm (#7359).

**⇒ The remaining gate on adoption is `llvm-inprocess` becoming a default cargo
feature**, since RS4GC is the only invoke-capable backend. That is #7301's
scope and is in flight. Correctness and platform scope are no longer the
blockers; sequencing step 2 below (root density) is, because adopting today
would regress binary size on root-dense code.

### ★ Binary size, measured 2026-08-04 — it is a ROOT-DENSITY problem, not a metadata one

The note above says *"closing that axis needs **fewer roots**, not a tighter
Expand Down Expand Up @@ -361,7 +420,8 @@ landed (#7314) and became *reachable* (#7339) and *selectable* (#7340). The spin
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).
RS4GC is the only invoke-capable backend). ~~and x86-64 to work (#7333)~~ —
x86-64 landed in #7349 and Windows in #7355; see the 2026-08-04 update above.
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