lyng/notes/vm_fastpath_plan.md

VM Fast-Path Plan (Non-Suspending Ops)

Goal

Reduce suspend overhead by routing safe, local-only ops through non-suspending fast paths while preserving semantics for captured locals and dynamic objects.

Completed

• Local numeric/bool/conversion ops: add fast local variants and guard by non-captured locals.
• Local jumps: JMP_IF_TRUE/FALSE and fused int jumps fast path.
• Object arithmetic ops (ADD_OBJ/SUB_OBJ/MUL_OBJ/DIV_OBJ/MOD_OBJ): add fast-path for local numeric slots with fallback to slow path when non-numeric or captured.
• Full :lynglib:jvmTest green after changes.

In Progress / Next

• Object comparisons (CMP_*_OBJ) fast-path on local numeric slots (guarded, fallback to slow path).
• Local MOVE_OBJ safe fast-path (only if slot is not FrameSlotRef/RecordSlotRef, or add explicit unwrapping).
• Address ops (LOAD_*_ADDR / STORE_*_ADDR) non-suspend variants when addr already resolved.
• Confirm wasm/js behavior unchanged (if needed).

Guardrails

• Never treat captured locals as fast locals; route them through slow path.
• Fast path must only execute when slot types are primitive numeric/bool and stored directly in frame.
• If fast-path preconditions fail, fall back to suspend perform().

Test Gate

• ./gradlew :lynglib:jvmTest
• Benchmarks optional: ./gradlew :lynglib:jvmTest -Pbenchmarks=true --tests '*NestedRangeBenchmarkTest*'

A/B Benchmark (Representative)

• Baseline (fast-path stashed): 194 ms
• With fast-path changes: 186 ms
• Command: ./gradlew :lynglib:jvmTest -Pbenchmarks=true --tests '*RepresentativeBenchmarkTest*'

A/B Benchmark (Representative Object Ops)

• Baseline (fast-path stashed): 106 ms
• With fast-path changes: 108 ms
• Command: ./gradlew :lynglib:jvmTest -Pbenchmarks=true --tests '*RepresentativeObjectBenchmarkTest*'

A/B Benchmark (Representative Object Ops, extended comparisons)

• Baseline (ObjString only): 141 ms
• With ObjString + ObjInt/ObjReal compare ops: 137 ms
• Command: ./gradlew :lynglib:jvmTest -Pbenchmarks=true --tests '*RepresentativeObjectBenchmarkTest*'

A/B Benchmark (Representative Object Ops, object numeric compares)

• Baseline (no Obj* compare ops): 153 ms
• With ObjString + ObjInt/ObjReal compare ops: 149 ms
• Command: ./gradlew :lynglib:jvmTest -Pbenchmarks=true --tests '*RepresentativeObjectBenchmarkTest*'

A/B Benchmark (Trust type decls for Obj* compares)

• With ObjString + ObjInt/ObjReal compare ops + type-decl trust: 157 ms
• Command: ./gradlew :lynglib:jvmTest -Pbenchmarks=true --tests '*RepresentativeObjectBenchmarkTest*'