jit: make W_TypeObject._version_tag quasi-immutable (method-cache pair 41 → 38 ops)

[youknowone]

Follow-up to #931. That PR closed the w_class half of the LOAD_METHOD method-cache pair by deduplicating a descr split; this closes the _version_tag half, and it turned out not to be a descr problem at all.

The hypothesis I started with was wrong

The plan was "apply the same bridge shape — the parentless descr blocks the fold". type_version_tag_descr() really did mint a fresh Arc on every call, at eight emit sites, with name: "", index_in_parent: 0, parent_descr: None.

It cost nothing. The read is always off the pinned type constant, and the constant path does not key on descr_identity; it slots by OptHeap::field_slot_index → Descr::index() → stable_field_index(offset, field_size, field_type, signed), which is content-derived. Two Arcs describing the same field land in the same slot, so the fold hit anyway. Measured on two natively-folded xs.append in one body: 2 _version_tag reads before opt → 1 in the steady body. Already deduped.

What it actually was

The pair survived only across a residual CALL_MAY_FORCE — and that flush is correct, because pyre modelled _version_tag as a plain mutable field. Two un-inlined method calls on one instance gave a 41-op steady body with ops 8/11-15 repeated verbatim as 22-27.

The control that settles it: op 26 in that repeat is W_ObjectObject.map, a group-backed descr with a real parent — and it duplicated too. The cause is the call flush, not the parentless spelling.

Upstream pays none of this: typeobject.py:177 _immutable_fields_ = ['_version_tag?']. The read becomes a QUASIIMMUT_FIELD marker plus one GUARD_NOT_INVALIDATED per trace, which no residual call can flush. type_version_tag_descr's own doc comment already named this as the convergence path, "once pyre wires that write barrier into mutated()".

The blocker was one function

QuasiimmutField is fully ported and live — state.rs:3394 emits it, heap.rs:3236-3280 records the dep and Removes the op, module globals already use it. But register_quasi_immutable_deps (pyre-jit/src/eval.rs) sent every dep to module_dict_register_version_watcher, which early-returns on a non-dict. A type-object dep had nowhere to register, so the flag was never flipped — which is exactly why the field had to stay mutable.

What this does

Ports rpython/jit/metainterp/quasiimmut.py's QuasiImmut — register_loop_token, compress_looptokens_list (compress_limit = 30, (len + 15) * 2), and invalidate (which empties the list) — onto a new W_TypeObject.quasi_immut_watchers. That field stands in for the hidden mutate__version_tag the rtyper synthesises upstream; pyre has no rtyper to synthesise it, so it is spelled out, allocated on first registration exactly like its sibling weak_subclasses. Pyre's per-artifact AtomicBool replaces looptoken.invalidated = True + cpu.invalidate_loop.

Four seams, deliberately one commit — the invalidation has to exist before the read is folded away:

1. type_version_tag_descr() → a LazyLock singleton carrying the quasi-immutable flag. Not optional: heap.rs:3274 keys quasi_immut_cache on field_cache_identity, which is the Arc pointer, so a per-call descriptor missed its own cache on every read.
2. The eight fold sites emit through a shared walker_pin_type_version_tag — no load, no GUARD_VALUE.
3. The invalidation hangs on w_type_set_version_tag, the field's only writer, so it covers mutated()'s fresh identity and both demotions to 0 without asking each caller to remember.
4. register_quasi_immutable_deps offers each dep to the type watcher as well as the module-dict one; both registrations self-filter on the object's kind.

Measurements

steady body	before	after
append loop (v_build)	33	32
two un-inlined method calls on one instance	41	38

Both _version_tag reads and both their guards are replaced by a single GuardNotInvalidated(), which sits inside the steady body — so it re-checks every iteration — and which the residual call between the two call sites no longer flushes.

Regression coverage, and proof it is not vacuous

New synth/method_reassign_after_warmup, four phases: rebind on the class, rebind again (so a stale second-generation trace is caught), rebind on a base of the warmed receiver's class (mutated()'s subclass walk), and rebind from inside the loop being traced. That last one is the case the old live read + guard_value used to catch for free; it is closed because the guard is per-iteration.

Commenting out the single w_type_notify_quasi_immut_watchers call makes the fixture return 1 1 1 10 10 — the stale methods survive. So the fixture is not vacuous and the invalidation is exactly load-bearing.

Its max-pypy-ratio is deliberately loose (60) and the header says why: pypy folds this loop to 0.01s at every N tried, so the denominator is collapsed and the ratio measures pypy's constant folding. The differential output is the gate.

Verification

• check.py: dynasm 355/355, cranelift 355/355
• cargo test --release -p pyre-object -p pyre-jit-trace -p majit-metainterp: 2152 passed, 0 failed, including two new QuasiImmut unit tests (invalidate flips + clears; register compresses dead tokens)
• w_subclass2, retag_force, v_build unchanged on both backends and under PYRE_NO_JIT
• Rebased onto current origin/main (jit-trace: bridge the codewriter's PyObject.w_class read to the walker descr (append loop 40 → 33 ops) #931 merged as f0627903782) and re-built, re-measured and re-gated on that base

Known, unchanged by this PR

W_TypeObject has no teardown path in this tree — weak_subclasses is never freed either — so the watcher box outlives a collected heap type. compress_looptokens_list bounds the growth that matters. Registration and notify are unsynchronised Vec operations, matching ModuleDictStrategy::register_version_watcher and w_type_add_subclass.

str_len_descr() still mints a fresh Arc per call. Same latent shape, currently unobservable — the reads get hoisted out of the loop entirely — so it is left alone rather than changed on speculation.

— authored by Claude

Summary by CodeRabbit

• Bug Fixes

  • Improved runtime correctness when methods or class attributes are rebound, preventing stale compiled behavior.
  • Ensured optimized execution paths invalidate cached assumptions when type versions change.

• Performance

  • Streamlined type-version checks and cache invalidation in optimized code paths.

• Tests

  • Added benchmark coverage for method rebinding after warmup, including superclass changes.
  • Added validation for watcher invalidation, cleanup, and bounded resource growth.

[coderabbitai]

Walkthrough

The change adds quasi-immutable type-version watchers, centralizes JIT type-version pinning, and registers type dependencies for loop invalidation. It also adds a PyPy benchmark for method rebinding after warmup and during traced execution.

Changes

Type-version invalidation

Layer / File(s)	Summary
Type watcher lifecycle pyre/pyre-object/src/typeobject.rs	W_TypeObject stores watcher state. Version-tag updates invalidate live loop flags. Tests cover cleanup, repeated invalidation, and bounded watcher growth.
Descriptor-backed dependency recording pyre/pyre-jit-trace/src/descr.rs, pyre/pyre-jit-trace/src/state.rs, pyre/pyre-jit/src/eval.rs	The version tag uses a cached quasi-immutable descriptor. JIT dependencies record the descriptor and register type watchers.
Centralized type-version pinning pyre/pyre-jit-trace/src/jitcode_dispatch/...	Inline calls and method, classmethod, bound-method, mapdict, exception, and subclass exception paths use walker_pin_type_version_tag.
Method-rebinding benchmark coverage pyre/bench/synth/method_reassign_after_warmup.py	The benchmark tests direct, inherited, and in-loop method rebinding after warmup. It prints totals and observed value transitions.

Estimated code review effort: 4 (Complex) | ~45 minutes

Sequence Diagram(s)

sequenceDiagram
  participant TracedLoop
  participant JITEval
  participant TypeObject
  participant QuasiImmutWatcher
  TracedLoop->>JITEval: record type-version dependency
  JITEval->>TypeObject: register quasi-immutable watcher
  TypeObject->>QuasiImmutWatcher: notify on version-tag change
  QuasiImmutWatcher->>TracedLoop: set invalidation flag
  TracedLoop-->>JITEval: retrace after invalidation

Loading

Possibly related PRs

• youknowone/pyre#319: Related quasi-immutable dependency and type-version watcher handling.
• youknowone/pyre#533: Related JIT invalidation and retracing changes.
• youknowone/pyre#904: Related quasi-immutable descriptor and type-version invalidation work.

Suggested reviewers: lifthrasiir

Poem

A rabbit warmed the traced-call lane,
Then changed a method in the rain.
The type tag changed; watchers stirred,
And fresh results replaced each word.
New values hopped through every loop. 🐇

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Docstring Coverage	✅ Passed	Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly describes the main change: making W_TypeObject._version_tag quasi-immutable to reduce method-cache operations.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch rewrite-tracer

---

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.}

[github-actions]

🤖 Codex parity review

Static analysis of this diff vs the local RPython/PyPy sources (commit 89b5ff0).
Updated: 2026-08-01T03:11:52.304Z

Files in the reviewed diff

pyre/bench/synth/method_reassign_after_warmup.py
pyre/pyre-jit-trace/src/descr.rs
pyre/pyre-jit-trace/src/jitcode_dispatch/inline_call.rs
pyre/pyre-jit-trace/src/jitcode_dispatch/mod.rs
pyre/pyre-jit-trace/src/jitcode_dispatch/specialize.rs
pyre/pyre-jit-trace/src/state.rs
pyre/pyre-jit/src/eval.rs
pyre/pyre-object/src/typeobject.rs

1. Regressions to PyPy parity introduced by this patch

None.

2. Other mismatches introduced by this patch

None.

3. Pre-existing mismatches (already present before this patch)

None.

4. Structural adaptations

• pyre/pyre-jit-trace/src/descr.rs:2165-2177 ↔ pypy/objspace/std/typeobject.py:177,506-510 — PyPy’s _version_tag? is represented through rtyper-generated quasi-immutable descriptors; pyre uses one static Rust descriptor shared by all type objects.

• pyre/pyre-object/src/typeobject.rs:763-870 ↔ rpython/jit/metainterp/quasiimmut.py:17-109 — PyPy stores a GC-managed QuasiImmut object in a hidden mutate__version_tag field; pyre stores a lazily allocated raw Box<QuasiImmut> pointer on W_TypeObject. The pointer is intentionally never reclaimed because the current type-object teardown path cannot free it.

• pyre/pyre-object/src/typeobject.rs:743-747 ↔ pypy/objspace/std/typeobject.py:285-286,293-301 — PyPy uses object-identity VersionTag values and None; pyre uses atomic u64 identities with 0 representing None.

• pyre/pyre-object/src/typeobject.rs:817-823 ↔ rpython/jit/metainterp/quasiimmut.py:84-105 — PyPy invalidation marks looptokens invalid and calls cpu.invalidate_loop; pyre flips per-artifact AtomicBool flags, relying on GUARD_NOT_INVALIDATED to observe invalidation.

• pyre/pyre-jit/src/eval.rs:5287-5291 ↔ rpython/jit/metainterp/pyjitpl.py:1081-1089 — PyPy registers the loop token through each QuasiImmutDescr; pyre performs post-compilation dependency registration against the concrete type/module object and the artifact’s invalidation flag.

• pyre/bench/synth/method_reassign_after_warmup.py:1-103 ↔ pypy/objspace/std/typeobject.py:266-291 — The benchmark is a pyre-specific CPython-compatible executable fixture exercising PyPy’s type mutation/version-tag semantics; there is no direct RPython/PyPy benchmark counterpart.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 5da0ba650c

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

Re-guard quasi-immutable values after invalidating calls

When a residual CALL_MAY_FORCE can mutate the receiver class and a second folded method lookup occurs later in the same iteration, heap-cache invalidation sets need_guard_not_invalidated but leaves the quasi_immut_known IndexSet populated, so this early return prevents walker_pin_type_version_tag from emitting the required post-call guard. If the call rebinds the method, the earlier guard has already passed and the second lookup uses the stale descriptor until the loop edge. Clear/version the known entry across such calls or consume the pending flag and emit another guard, as RPython's head-versioned heap-cache state does.

AGENTS.md reference: AGENTS.md:L194-L196

Useful? React with 👍 / 👎.

[youknowone]

Confirmed, and it is worse than "the flag is left populated" — the faithful port of this state already existed and was inert.

Pyre had two structures for the same thing:

structure	cleared by	used by
CacheEntry.quasiimmut_seen{,_refs} (heapcache.rs:78-79)	_clear_cache_on_write + _invalidate_unescaped — matches heapcache.py:70-77 / 121-129	nobody (dead fields)
HeapCache.quasi_immut_known: IndexSet<(OpRef,u32)>	reset() only, i.e. trace teardown	all four call sites

So clear_caches_varargs (heapcache.py:341-370) was already arming need_guard_not_invalidated and running invalidate_unescaped per entry for every general call — it just had nothing to clear.

Fixed by moving is_quasi_immut_known / quasi_immut_now_known onto the CacheEntry sets (heapcache.py:604-627), in upstream's (fielddescr, box) argument order, and deleting the flat set. Constant receivers key on getref_base() via quasiimmut_seen_refs, matching heapcache.py:609/622.

Measured on the two-un-inlined-method-calls fixture: the pre-opt block goes from one QuasiimmutField to two, and the optimized loop now carries two GuardNotInvalidated() with the CallMayForceR between them — heap.py:810-822's "one guard after every invalidating call". Steady body 38 → 39 ops; the 38 was unsound.

Three HeapCache unit tests cover the lifetime directly (per-descr/per-ref keying, cleared by the call invalidation, cleared by a store to the field).

Note this was pre-existing — module-global folds have relied on the flat set since they landed. It was masked here until this PR removed the live _version_tag read + GuardValue that re-proved the resolution at the second site.

— commented by Claude

[chatgpt-codex-connector]

Reject a version tag that changes while tracing

When a trace resolves a method and the class is rebound later in that same tracing iteration, this marker records only the type pointer and static field descriptor; it captures neither the version value nor the current watcher generation. The mutation therefore invalidates an empty watcher list, and post-compilation registration attaches the stale loop to the still-reused watcher with a false flag, allowing the loop to start with constants derived from the old method. RPython's QuasiImmutDescr snapshots both the value and watcher identity and is_still_valid_for rejects exactly this trace, so the port needs an equivalent generation/value validation rather than an object-only dependency.

AGENTS.md reference: AGENTS.md:L194-L196

Useful? React with 👍 / 👎.

[youknowone]

Confirmed. record_quasiimmut_field recorded only (obj, fielddescr), so nothing downstream could detect a change in the tracing→optimizing window. The vt_mutate_inloop fixture passing was not evidence the window is closed — it just never hit it.

Fixed by porting both halves of QuasiImmutDescr:

Value snapshot. The tracer now captures the field at record time (get_current_constant_fieldvalue, quasiimmut.py:135-143) through field_sanity_load, which is the cpu.bh_getfield_gc_{i,r,f} triple behind one field_type() dispatch. OptHeap re-reads the live value via get_runtime_field and returns InvalidLoop("quasi immutable field changed during tracing") on mismatch — heap.py:798-804.

Upstream hangs the snapshot on a QuasiImmutDescr minted per recorded op. Pyre's descrs are registry-indexed singletons, so a fresh one per read would mint a registry entry per read; the value rides on the op as arg(1) instead, the way the record_namespace_quasiimmut_field twin already carries its slot index. Struct-non-constant and no-snapshot both fall through to "keep the loop", matching heap.py:794-796, which ignores a QUASIIMMUT_FIELD whose struct did not fold.

Watcher identity. You are right that the instance was reused. w_type_notify_quasi_immut_watchers now unlinks quasi_immut_watchers before the sweep and drops the box — make_invalidation_function._invalidate_now (quasiimmut.py:129-134). A registration after an invalidation therefore allocates a fresh instance, exactly the qmut is not self.qmut signal upstream tests. It also makes the box's lifetime match upstream's, where the QuasiImmut becomes garbage as soon as the field is nulled.

Not covered by this change: the namespace (module-dict cell) twin has the same window, but its value lives behind a reader the optimizer layer cannot call without depending on pyre-object. That gap is pre-existing and is being tracked separately.

Verification: check.py 358/358 on dynasm and cranelift; 2214 Rust tests green.

— commented by Claude

[youknowone]

Parity review §4 — per-item disposition

Both P1 inline findings were real and are fixed (replies on the threads). Section 4's six items, each adjudicated rather than deferred by classification:

1. One static descr shared by all type objects (descr.rs:2165-2177) — won't-fix, correct as-is. The rtyper generates a quasi-immutable descr per STRUCT; pyre has exactly one W_TypeObject layout, so one descr is that set. The heapcache keys on (fielddescr, box) (heapcache.py:604), so distinct type objects stay distinct through the box, not the descr. Sharing it is also load-bearing: heap.rs:3274 keys quasi_immut_cache on the Arc pointer, so a per-call descr would miss its own cache on every read.

2. Raw Box<QuasiImmut> never reclaimed (typeobject.rs:763-870) — fixed-now. w_type_notify_quasi_immut_watchers now unlinks the field before the sweep and drops the box, which is make_invalidation_function._invalidate_now (quasiimmut.py:129-134). The lifetime now matches upstream's, where the instance becomes garbage the moment the hidden field is nulled. Residual: a type nobody has mutated since its last compile still holds one box — but it is owned by a W_TypeObject, which is immortal in this tree, so that is the type's own lifetime, not a growing leak. compress_looptokens_list bounds the part that would otherwise grow.

3. AtomicU64 tags with 0 for None (typeobject.rs:743-747) — won't-fix. Pre-existing, predates this PR; RPython object-identity VersionTag has no Rust counterpart that stays a plain field read.

4. AtomicBool flags instead of looptoken.invalidated + cpu.invalidate_loop (typeobject.rs:817-823) — won't-fix, correct as-is. The backend already routes GUARD_NOT_INVALIDATED through a per-artifact AtomicBool; flipping it is precisely what invalidate_loop buys. Same mechanism ModuleDictStrategy::notify_version_watchers already uses.

5. Post-compile dependency registration (eval.rs:5287-5291) — won't-fix, with the window now named. Upstream registers the loop token on qmutdescr.qmut, the instance captured at trace time; pyre re-looks it up after compiling. The gap between them is the optimize→register window, which is empty under a single mutator (pyre compiles synchronously on the executing thread, and upstream holds the GIL across the same span). It reopens only under free-threading — see below.

6. The benchmark fixture (method_reassign_after_warmup.py) — won't-fix. An executable differential fixture has no RPython counterpart by construction.

One item the report did not raise

QuasiImmut.looptokens_wrefs is registered, compressed and swept as an unsynchronised Vec. Upstream relies on the GIL; pyre targets free-threading. This is not specific to this PR — ModuleDictStrategy::version_watchers (celldict.rs:603) and W_TypeObject::weak_subclasses are the same shape, and fixing one in isolation does not make the mechanism thread-safe. Tracking it as follow-up work covering all three together, plus item 5's window, rather than growing this diff.

— commented by Claude