gc: function-entry polls at indirect entries and recursive SCCs (RFC deferred collection S5, polls)

[proggeramlug]

RFC deferred collection (#11528), step S5, the polls (decision 2). Stacked on #11630 (gc/s5-runtime-invariant): review that first. The diff here is the last commits.

Update (7daff50): class constructors no longer get an indirect-entry poll. new C() calls the constructor body directly, so an in-body poll made those call sites moving points, and the stale-register gate found 3 new stale uses (5 against a budget of 2, all new of AnonShape constructors). The stub design in the RFC is what makes constructor polls safe. Revalidation of this head is in progress (perrymaster:/root/s5/dom.log).

What it adds

• Indirect-entry polls. These go in closure bodies, instance and static methods (including constructors and accessors, which enter through the class tables), and the __perry_wrap_* forwarders that make a top-level function a callback value.
• Recursive-SCC polls. One entry poll per recursive SCC of the module's direct call graph, in the member with the most incoming edges from inside the SCC. See the refinement below.
• No poll at a non-recursive direct-call function. The census's reason for rejecting polls at every function entry was 12.18 M vs 7.39 M relocations.

How a poll is placed.

• Lowering emits a scaffold after parameters are rooted and before arguments materialisation (which can allocate). The scaffold is the armed-word load volatile, a branch, and call void @js_gc_entry_safepoint(). It is the back-edge poll under another symbol: same runtime body, same seeded-schedule candidacy, same PERRY_GC_SCHEDULE_ALLOC_KB pacing.
• The whole-module pass entry_polls::finalize_module keeps a scaffold only in a function that the module leaf analysis, with entry polls ignored, already proves collecting. So every call to it was already a statepoint, and no call changes classification (S5 must not; S6 does that). A dropped scaffold's load becomes a constant and LLVM folds the branch away.
• Both lowerings (RS4GC and shadow frames) use the same point, where the loop poll's rooting argument holds: parameters are rooted, and no temporary is live.
• A value wrapper has no root slots of its own. On the armed path only, it spills its arguments (the closure pointer boxed as an object) to an entry buffer. js_gc_entry_safepoint_args roots them across the collection and writes the relocated values back.

Kill switch. It is the loop polls' own, PERRY_GC_MOVING_LOOP_POLLS=0. There is no new knob.

S1 tables. js_gc_entry_safepoint and js_gc_entry_safepoint_args are Reenters in all three gc_effects/*.tsv files, and declared poll seeds in seeds.txt. The wasm ABI table is regenerated.

Proposed refinement of decision 2, with evidence

Decision 2 says "one poll per recursive SCC". Implemented literally, that put a poll in benchmarks/suite/05_fibonacci: fib's numeric fast clone and its boxed fallback form an SCC. The run cost +59.98% instructions, a poll on every call of a recursion that allocates nothing.

This PR therefore polls a recursive SCC only when the recursion itself allocates without a poll: some member has a collecting edge of its own, or calls out of the SCC to a function that may collect and does not poll at its entry. SCCs are visited callees first, so a callee's poll is known in time.

• An SCC whose only route to allocation goes through callees that bound their own allocation per call (they poll at entry) gets no second poll.
• A pure SCC gets none; the RFC already admits pure recursive SCCs as leaves.

Result:

program	literal placement	refined placement
05_fibonacci	+59.98% instructions	+0.00%
rectree (loop-free recursive allocator)	−52.59%	−52.72% instructions, peak RSS −60…−74% (it drains at its SCC poll instead of waiting for the 64 MiB valve)

The rule is stated as a proposal on #11528. The checker (scripts/gc_poll_coverage_check.py) applies the same definition, so a violation of either reading shows up there.

Poll-coverage checker

scripts/gc_poll_coverage_check.py, run over emitted IR:

• It reports every natural loop whose body may allocate but has no poll, and every allocating recursive SCC with no entry poll.
• --max-uncovered-loops / --max-uncovered-sccs turn the counts into a ratchet.
• --self-test proves it can fail.

It also answers the §2 open item: the specialized for / for-of / for-in lowerings named in the stmt/loops.rs comment are now measured rather than assumed.

Measurements

qb4, same base, same 32 programs as #11630, instructions as medians of 5.

Compute and RSS.

	this PR vs main
largest instruction delta, any program	+0.29% (probe_11)
05_fibonacci	+0.00%
rectree (loop-free recursive allocator)	−51.6% instructions, −62.6% peak RSS
worst single-program peak RSS	+1.68% (shared with #11630)
ratchet median peak RSS	+0.34% (same as #11630: the polls add none)

Poll counts and cost. From --statepoint-report=text, which now prints an entry polls: line:

program	kept of scaffolds	recursive-SCC polls
server fixture	6 of 10	0
09_method_calls	4 of 5	0
14_closure	1 of 2	0
05_fibonacci	2 of 3	1
rectree	9 of 10	4

• None of these reported an allocating SCC without a candidate.
• A kept poll's unarmed path is one volatile load, a compare and a not-taken branch. The programs with kept polls move ≤0.1% in instructions.

cc bundle (claude-code 2.1.112):

	Δ
binary size	+4.2 MB (+1.13%)
--version instructions	+0.002%
--help instructions	+0.002%
--version peak RSS	+0.00%
--help peak RSS	+0.60%

Compile wall (67 min) and compile peak RSS (37.8 GB) are equal to main. The cc poll count is not reported: that compile predates the report line.

Decision 3 (straight-line bodies). max_poll_wait_bytes is 0 on:

• a 20,000-statement allocating top-level chunk;
• a 20,000-statement retaining chunk;
• a 100,000-string pool initialiser.

The valve never fired on any of them, so no statement-boundary polls were added. The cc bundle's init chunks under a real session remain unmeasured until #11559 lets cc run -p turns.

Tests

• crates/perry/tests/gc_entry_polls_s5.rs (real TS → IR):
  • a self-recursive allocator polls;
  • a mutually recursive pair carries exactly one poll;
  • a non-recursive direct-call function (allocating or not) carries none;
  • an allocating method and closure poll, a non-allocating method does not;
  • the wrapper of an allocating function polls with spilled args, and the wrapper of a proven leaf does not;
  • the program's output is right;
  • the kill switch removes every entry poll;
  • runtime: a loop-free recursion reaches armed entry polls, drains at them, never fires the valve, and waits under 16 MiB for a poll.
• entry_polls.rs unit tests: Tarjan on cycles and self-loops, a 50k-deep chain without recursion, callees-first order.
• gc_poll_coverage_check.py --self-test.
• perry-codegen: two shadow_inline tests pin exact register numbers; their pins moved by the scaffold's two registers.

[coderabbitai]

Important

Draft PR not reviewed

Draft PRs are not automatically reviewed by default.

• Trigger a manual review

To automatically review draft PRs, update your CodeRabbit configuration:

reviews:
  auto_review:
    drafts: true

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[jdalton]

[P2] Cover allocating subcycles before marking the whole SCC polled

One selected member does not intersect every cycle in an SCC. For example, with direct edges a -> {a, b} and b -> {a, b}, and an allocation in each function, the tie-break selects a and removes b's scaffold. A branch repeatedly taking b -> b can then allocate without reaching an entry poll, even though both functions are inserted into polled. This leaves that path dependent on the allocation valve rather than providing the intended poll bound.

I reproduced the matching checker blind spot using this head's scripts: LLVM IR with that graph, a poll only in a, and a direct js_object_alloc call in each function exits 0 with --max-uncovered-sccs 0 (allocating=1 uncovered=0); removing the sole poll correctly exits 1. This is a source/checker reproduction, not a compiled runtime measurement.

Please retain enough polls to intersect every allocating recursive cycle (for example, recheck the remaining graph after cutting at polled entries), and add a subcycle negative control to the coverage checker. The same check is needed when an existing indirect-entry poll causes the whole SCC to be marked covered.