Skip to content

fix(jit): test ref.is_null on the ref payload, not the whole boxed word - #230

Merged
siyul-park merged 1 commit into
mainfrom
fix/228-jit-struct-null
Aug 31, 2026
Merged

siyul-park merged 1 commit into
mainfrom
fix/228-jit-struct-null

Conversation

@siyul-park

@siyul-park siyul-park commented Aug 31, 2026 •

Copy link
Copy Markdown
Owner

Closes #228.

The divergence

A heap slot's null is not always the BoxedNull bit pattern. struct.new_default zero-fills
((*types.Struct).Reset -> clear(s.Data)), so an unset KindRef field reads back as Boxed(0),
whose Kind() is KindF64 — not BoxRef(0), which carries the NaN tag.

The threaded lowering handles both: REF_IS_NULL is boxed.Ref() == 0, and Ref() is
int(int32(v & VMask)), so it tests the ref payload. The ARM64 lowering compared the whole
64-bit word against BoxedNull, so it called a default-initialized ref field non-null.

That is a wrong answer, not just a missed optimization. ref.is_null; br_if is exactly the guard a
nullable-node walker uses, so native execution fell through it into the ref.cast behind it and
trapped:

type mismatch: fn=2 ip=8 <- fn=2 ip=21 <- ... <- fn=0 ip=13

while threaded returned the right answer on the same program.

The fix

Heap values are not meant to exclude null, so the JIT is what changes. Mask the ref payload and
compare it against zero, matching boxed.Ref():

addr := ctx.assembler.Reg(asm.RegTypeInt, asm.Width64)
ctx.assembler.Emit(arm64.ANDI(addr, ref, maskI32))
ctx.assembler.Emit(arm64.CMPI(addr, 0))

Same instruction count as the LDI + CMP it replaces. maskI32 is the mask refOnly already uses
to extract a ref address from a boxed word.

Nothing else in the backend needed changing. refOnly gates retainBox/releaseBox on the kind
tag, so Boxed(0) is skipped there exactly as the interpreter's retainBox/releaseBox skip it.
refEq/refNe are full-word compares in both tiers already, so they agree. A null container reaching
structGet fails guardItab and side-exits, which is what threaded does too.

Tests

  • TestInterpreter_Run / "STRUCT_NEW_DEFAULT's default ref field agrees between threaded and JIT" —
    builds a small binary tree whose leaves reach ref.is_null through an unset ref field, and requires
    WithThreshold(-1) and WithThreshold(0) to return the same value. Verified it fails on the parent
    commit with the trap above and passes here.
  • A runTests case for struct.new_default -> struct.get -> ref.is_null, which the table runs in
    both standalone and fused modes.

Docs

  • docs/memory-model.md, under Heap index 0 is always null: a null ref is not always the BoxedNull
    bit pattern, null-ness is Boxed.Ref() == 0, and every consumer must use that rather than a
    whole-word compare.
  • docs/jit-internals.md: REF_IS_NULL tests the ref payload, cross-referencing the above.

Knock-on

This unblocks the struct half of #176, which #229 had to drop. With the fix in place,
StructTreeWalk and BinaryTrees pass in threaded, default, and jit with their Node params
declared as the concrete struct type. That retype is not in this PR — it belongs on #229 once this
lands.

Test plan

  • go test -race ./... — 19 packages green
  • make check-generated — clean
  • make lint — clean
  • make coverage-check — 73.1% vs 72.5% baseline
  • New test verified failing before the change

🤖 Generated with Claude Code

Summary by CodeRabbit

  • Bug Fixes

    • Corrected null-reference detection for default-initialized reference fields, ensuring they are consistently recognized as null across execution modes.
    • Improved handling of reference fields in ARM64 JIT execution.
  • Tests

    • Added coverage for null checks on unset reference fields.
    • Added a consistency test confirming threaded and JIT interpreters produce matching results for recursive programs.
  • Documentation

    • Clarified reference null semantics and heap index behavior in the memory model and JIT documentation.

A heap slot's null is not always the BoxedNull bit pattern. struct.new_default
zero-fills, so an unset KindRef field reads back as Boxed(0), whose Kind() is
KindF64. The threaded REF_IS_NULL lowering is boxed.Ref() == 0 -- a test on the
ref payload -- and reports both patterns as null. The ARM64 lowering compared
the whole 64-bit word against BoxedNull, so it reported a default-initialized
ref field as non-null.

The effect is a divergence, not just a missed guard: a slot declared with a
concrete struct type reaches a native plan, ref.is_null falls through its
br_if, and the ref.cast behind that guard traps with ErrTypeMismatch, where
threaded execution returns the right answer.

Heap values are not meant to exclude null, so the JIT is what changes: mask the
ref payload and compare it against zero, matching boxed.Ref().

Regression test builds a small binary tree whose leaves reach ref.is_null
through an unset ref field and requires threaded and JIT to agree; it fails
with `type mismatch: fn=2 ip=8` before this change. A runTests case covers
struct.new_default -> struct.get -> ref.is_null in standalone and fused modes.

This unblocks the struct half of #176: StructTreeWalk and BinaryTrees now pass
in all three modes with their Node params declared as the concrete struct type.

Closes #228
@coderabbitai

coderabbitai Bot commented Aug 31, 2026 •

Copy link
Copy Markdown
Contributor

Review Change Stack

Caution

Review failed

The pull request is closed.

ℹ️ Recent review info
⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 96bf8e14-7a57-4c91-926d-5396bdefe1d6

📥 Commits

Reviewing files that changed from the base of the PR and between 88e1dbd and 33a3a60.

📒 Files selected for processing (4)
  • docs/jit-internals.md
  • docs/memory-model.md
  • internal/jit/arm64/ref.go
  • interp/interp_test.go

📝 Walkthrough

Walkthrough

The change makes ARM64 REF_IS_NULL inspect the ref payload. Documentation records the null representation for zero-filled ref fields. Tests cover direct interpreter behavior and matching threaded and JIT execution.

Changes

Reference null handling

Layer / File(s) Summary
Null semantics and JIT lowering
docs/memory-model.md, docs/jit-internals.md, internal/jit/arm64/ref.go
Documentation defines null refs by payload value. ARM64 refIsNull masks the payload and compares it with zero.
Cross-tier null validation
interp/interp_test.go
Tests verify that default-initialized ref fields are null and that threaded and JIT execution return the same binary-tree result.

Estimated code review effort: 3 (Moderate) | ~20 minutes

✨ 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 fix/228-jit-struct-null

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

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

@siyul-park
siyul-park merged commit fe2917e into main Aug 31, 2026
2 of 3 checks passed
siyul-park added a commit that referenced this pull request Aug 31, 2026
…t slots (#231)

* test(benchmarks): declare the concrete node type on tree-kernel struct slots

StructTreeWalk and BinaryTrees declared every Node-holding local, return, and
param as `any` (types.TypeRef), so `struct.get` never reached its fused
container path. #229 had to leave them that way: declaring the concrete struct
type made the ARM64 JIT fault where threaded execution was correct. #230 fixed
that, so the declarations can now be what the Python sources say.

`left`/`right` stay `any` because the grammar cannot name a recursive type.
The `check`/`item_check` params may hold the null ref at a leaf, which is fine:
heap slots do not exclude null, `struct.new_default` leaves unset ref fields
null, and both tiers now agree on `ref.is_null` for them.

No interpreter code changes. Interleaved A/B, -benchtime=300ms -count=6,
Apple M4 Pro:

  Memory_BinaryTrees/threaded     1.145ms -> 1.059ms  -7.55% (p=0.002)
  Memory_BinaryTrees/default      1.187ms -> 1.104ms  -7.01% (p=0.002)
  Memory_BinaryTrees/jit          1.187ms -> 1.106ms  -6.85% (p=0.002)
  Memory_StructTreeWalk/default   160.5us ->  154.6us -3.69% (p=0.002)
  Memory_StructTreeWalk/threaded  153.0us ->  147.5us -3.58% (p=0.002)
  Memory_StructTreeWalk/jit       160.2us ->  155.7us -2.81% (p=0.002)

Control_Sieve and Numeric_NBody are flat in all three modes. B/op and
allocs/op are identical on every row.

* test(benchmarks): drop the redundant ref.cast from the tree walkers

`check` and `item_check` each downcast their node param with `ref.cast 0`
immediately after a `ref.is_null; br_if` guard. The cast only existed because
the param was declared `any`; with the param declared as the node struct type
it proves nothing the declaration does not already state, and neither Python
source has a cast.

It was not free. `REF_CAST` is bridged, so every node walk left native code for
the interpreter and came back, and the cast also split `local.get 0` from the
`i32.const N; struct.get` behind it, blocking that field read from fusing.

Interleaved A/B against the previous commit, -benchtime=300ms -count=6,
Apple M4 Pro:

  Memory_BinaryTrees/jit           1108.1us -> 752.7us  -32.08% (p=0.002)
  Memory_BinaryTrees/default       1102.7us -> 751.8us  -31.82% (p=0.002)
  Memory_StructTreeWalk/jit          156.0us -> 135.0us -13.43% (p=0.002)
  Memory_StructTreeWalk/default      154.8us -> 134.4us -13.20% (p=0.002)
  Memory_BinaryTrees/threaded      1055.9us -> 950.9us   -9.94% (p=0.002)
  Memory_StructTreeWalk/threaded     147.7us -> 138.1us  -6.52% (p=0.002)

Control_Sieve is flat in all three modes. B/op and allocs/op are unchanged.

* docs(benchmarks): re-measure the tree-kernel rows

StructTreeWalk and BinaryTrees moved when their node slots were declared
concretely and the redundant ref.cast was dropped. Both now run fastest under
default rather than threaded, so they leave that list, and minivm threaded
overtakes CPython on BinaryTrees.
@siyul-park
siyul-park deleted the fix/228-jit-struct-null branch November 7, 2026 10:20
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

perf(jit): a struct-typed slot that can hold null makes the JIT diverge from threaded

1 participant