Guarded x86 Hot-Subset Dispatcher Benchmark

Historical source last updated, 2026-08-13. Runtime and implementation claims below describe that dated source; see current app notes and source for subsequent changes.

Date: 2026-08-12

Question

Can a generated br_table loop execute a corpus-hot subset of decoded x86 handlers while preserving the existing threaded interpreter as an exact fallback?

Implementation under test

The experimental runner preflights an entire decoded block before changing guest state. If every handler is supported, it executes the block in one br_table function. If any handler is unsupported, it restores the packet IP and runs the original $next/call_indirect chain. The production hook is disabled by default and is selected with X86_HOT_SUBSET=1.

The current subset contains 16 generic handler families used by the four-block AoE fixture. The benchmark also has an exact-operand direct-register variant, but the main-loop hook uses the safer generic-handler variant.

Correctness

The following passed against the rebuilt tail-call and compatibility modules:

PASS  AoE br_table hot subset falls back to x86 with exact state
PASS  AoE packet, stack, four-slot, and optimized blocks match x86 decoder
PASS  profile-guided exact handlers match generic threaded handlers
PASS  wasm-tools validate build/wine-assembly.wasm
PASS  wasm-tools validate build/wine-assembly.compat.wasm

The fallback test uses an unsupported mov eax,imm32; ret block and compares all general registers, EIP, and ESP. The broader AoE differential suite routes its block corpus through the main-loop hot-subset hook and compares registers, lazy flags, watched memory, and EIP.

Fixed-work benchmark

Command:

env BLOCKS=2000000 WARMUP_BLOCKS=2000000 TRIALS=9 WARM_ONCE=1 \
  VARIANTS=x86-threaded,brtable-generic-local-ip,brtable-subset-generic,brtable-direct-generic-alu,brtable-subset-direct \
  node tools/bench-aoe-recompile-loop.js

Results:

Variant Median ms Paired vs x86
x86 call_indirect 147.39 1.000x
generic br_table, no guard 63.33 2.254x
generic br_table + block preflight 123.61 1.166x
direct br_table, no guard 40.69 3.585x
direct br_table + exact-form preflight 129.28 1.103x

The production-shaped generic subset retained a 16.6% paired speedup, but repeated packet scanning consumed most of the guard-free upper bound.

Classify-once pointer-tag follow-up

The follow-up does not change the decoder or production cache. The benchmark harness tags already-decoded aligned packet pointers with bit zero. A benchmark-only selector pays one tag test, pointer mask, and branch; untagged packets fall directly into $next.

Hot-only command:

env BLOCKS=2000000 WARMUP_BLOCKS=2000000 TRIALS=31 WARM_ONCE=1 \
  VARIANTS=x86-threaded,brtable-generic-local-ip,brtable-subset-generic,brtable-cached-generic \
  node tools/bench-aoe-recompile-loop.js
Variant Median ms Paired vs x86
x86 call_indirect 142.46 1.000x
guard-free generic br_table 63.67 2.221x
rescan every block 109.53 1.301x
cached HOT tag 64.93 2.219x

Cached-HOT is effectively identical to the guard-free ceiling. The aggregate median is about 2% slower, while the paired ratios differ by only 0.1%.

Mixed-path command:

env BLOCKS=500000 WARMUP_BLOCKS=2000000 TRIALS=51 WARM_ONCE=1 \
  VARIANTS=x86-threaded,brtable-subset-generic,brtable-cached-mixed \
  node tools/bench-aoe-recompile-loop.js

Only 0x00535c20 was tagged, so one of four block entries was hot and each cycle exercised both branches of the selector.

Variant Median ms Paired vs x86
x86 call_indirect 36.32 1.000x
rescan every block 28.12 1.314x
cached 25%-hot / 75%-cold 22.52 1.595x

The tagged block is longer than the other three fixture blocks, so this is a selector-cost proxy rather than an estimate of a 25%-covered application. It does show that the same selector remains profitable while naturally executing both hot and cold paths.

Full-browser profiles

All runs used headless Chrome, muted audio, HANDLER_HIST=0, HOTFORM_SPECIALIZE=0, 100,000 blocks per run slice, and a nominal ten-second measurement window.

AoE

Metric Baseline 1 Candidate 1 Delta Baseline 2 Candidate 2 Delta
runSlice average, ms 11.709 9.587 -18.1% 9.264 9.506 +2.6%
completed slices 593 679 +14.5% 695 685 -1.4%
guest/unwrapped total, ms 6065.3 5764.3 -5.0% 5673.0 5777.7 +1.8%
present FPS 12.349 14.411 +16.7% 14.622 14.446 -1.2%
repaint FPS 55.613 59.008 +6.1% 59.438 58.897 -0.9%
subset coverage - 26.1% - - 26.0% -

The first pair was strongly positive; the repeat was slightly negative. This does not meet the repeatability requirement for a production optimization.

RCT cold-fallback stress

RCT hit no supported blocks in this subset.

Metric Baseline Candidate Delta
runSlice average, ms 2249.54 2244.22 -0.24%
completed slices 5 5 0.0%
guest/unwrapped total, ms 11247.7 11221.1 -0.24%
hot blocks 0 0 -
fallback blocks 0 500000 -

The matched pair is effectively neutral, so this run found no measurable cold-fallback penalty.

Decision

Keep the experiment and tests, but keep it disabled by default. The next implementation below classifies each decoded block once and caches its hot/cold eligibility instead of rescanning the packet on every entry. Expand the generic handler subset from AoE and RCT corpus histograms and require at least three matched full-app pairs before considering default enablement.

Production cache-metadata prototype

The production-shaped follow-up stores one eligibility bit per decoded-cache slot in a parallel 512-byte bitmap for each emulator thread. Classification runs at cache_store, after the decoder has emitted the final packet, and accepts both generic handler IDs and the existing AoE/RCT exact-form aliases. The main loop performs its ordinary cache lookup once, checks the bit, and:

Cache replacement naturally overwrites the bit. Full cache clears, page invalidation, thread initialization, and feature toggles clear the corresponding metadata. Tests cover supported exact forms, unsupported fallback with exact guest state, colliding cache slots, invalidation, and toggling.

Fixed-work command:

env BLOCKS=2000000 WARMUP_BLOCKS=2000000 TRIALS=31 \
  VARIANTS=x86-threaded,x86-cached-subset-production \
  node tools/bench-aoe-recompile-loop.js
Variant Median ms Paired vs x86
x86 call_indirect 147.31 1.000x
production cached subset 73.59 1.998x

This still uses the four-block all-hot kernel. Its purpose is to verify that real cache insertion, exact-form decoding, the main run entry point, and cached dispatch retain most of the generated executor's isolated benefit.

The corrected full-browser AoE pair used 30 seconds of scripted campaign gameplay, muted audio, HANDLER_HIST=0, and HOTFORM_SPECIALIZE=1:

Metric Baseline Cached subset Delta
main.runSlice total 19820.7 ms 19238.7 ms -2.94%
guest/unwrapped total 17094.0 ms 16428.8 ms -3.89%
completed slices 1998 2112 +5.71%
present FPS 16.285 17.355 +6.57%
repaint FPS 58.652 59.415 +1.30%
hot block entries - 61,479,047 -
cold block entries - 149,711,927 -
hot coverage - 29.1% -

The candidate screenshot shows valid campaign gameplay. This is one positive full-app pair, not sufficient evidence to enable the feature by default.

A matched 30-second warmup plus 10-second measured RCT browser pair then routed 100% of the measured loop through generated dispatch:

Metric Baseline Expanded subset Delta
median main.runSlice 2134.0 ms 745.0 ms -65.1% / 2.864x
average main.runSlice 2153.1 ms 742.6 ms -65.5% / 2.899x
completed slices 5 14 2.80x throughput
hot block entries - 1,400,000 -
fallback entries - 0 -

This is a real full-browser RCT run with a visible RCT window, but the harness parks in a stable instruction-heavy loop at EIP=0x00850000; it is not yet interactive park gameplay. Treat the magnitude as evidence for this loop and for the dispatch mechanism, not as an end-user RCT frame-rate claim. A differential test covers every observed handler family, the three exact forms, memory/register/flag state, SIB addressing, and the 999-handler cutoff.

The feature remains disabled globally pending repeated full-app trials and a rendered, interactive RCT gameplay harness. It now has measured hot coverage in both profiled applications rather than requiring AoE-only gating.

The machine-readable summary is in docs/x86-hot-subset-benchmark-results.json. Original browser profiles were large temporary harness artifacts and are intentionally not committed.

Automatically generated whole-table control

The repository's own WAT S-expression parser now inventories the canonical thread table and mechanically clones handler bodies into one br_table dispatcher. It does not translate x86 semantics. It renames labels and locals, maps the handler parameter to the dispatcher operand, changes return_call $next into a dispatch-loop branch, changes ordinary returns into block exits, zeroes reused scratch locals, and preserves $next's decrement- before-dispatch 999-handler limit.

flowchart LR
    A[canonical 385 th_* functions] --> B[WAT S-expression analyzer]
    B --> C[335 continue]
    B --> D[37 terminal]
    B --> E[13 mixed exit]
    C --> F[rename locals and labels]
    D --> F
    E --> F
    F --> G[generated 385-case br_table]
    G --> H[X86_FULL_BRTABLE=1 benchmark]

All 385 table entries are structurally convertible in the current source. No handler has a non-tail call to $next, foreign tail call, unresolved function, or numeric local reference. The generated WAT is 279,880 bytes, shares at most 30 i32 and five i64 scratch locals, and increases the compiled primary Wasm from 381,917 to 411,122 bytes (+29,205 / 7.6%). The original functions remain only to provide the baseline and differential oracle while evaluating the architecture.

The direct three-way fixture command is:

env VARIANTS=x86-threaded,x86-full-brtable,x86-cached-subset-production \
  TRIALS=31 BLOCKS=2000000 WARMUP_BLOCKS=2000000 \
  node tools/bench-aoe-recompile-loop.js
Variant Median ms Paired vs x86
x86 call_indirect 223.78 1.000x
automatic 385-case br_table 161.06 1.362x
compact cached corpus subset 104.66 2.204x

The whole-table path therefore proves that dispatch conversion alone is profitable, but also that one giant function leaves substantial performance on the table versus a compact corpus-selected dispatcher.

A single 30-second full-browser AoE campaign pair showed the same mixed result:

Metric Baseline Whole table Delta
main.runSlice total 19820.7 ms 19974.6 ms +0.78%
guest/unwrapped total 17094.0 ms 16565.1 ms -3.09%
completed slices 1998 2003 +0.25%
present FPS 16.285 16.048 -1.46%
repaint FPS 58.652 58.099 -0.94%
generated block entries - 200,289,197 -

The screenshot shows valid campaign gameplay. Guest CPU improved, but the end-to-end frame metrics do not justify preferring the giant dispatcher over the compact subset from this pair.

On RCT's stable warm loop, the whole table reduced median slices from 2134.0 to 1160.5 ms (1.839x) and average slices from 2153.1 to 1170.0 ms (1.840x), with 900,000 generated block entries. The compact RCT subset remains much faster at 745.0 ms median (2.864x). This remains the non-interactive parked RCT loop caveat described above.

The practical direction is therefore automated generation of several compact tables or a hot-table plus full-table fallback, rather than shipping one monolithic 385-case function. The new full-table mode makes that choice cheap to remeasure whenever handlers or browser engines change.