pcbjam/docs/features/wasm-exceptions/12-native-vs-jseh-benchmark.md

Benchmark: native-EH vs JS-EH (eeschema + pcbnew)

Measured 2026-07-01. Quantifies the WASM exception-handling migration (c1ef489, native -fwasm-exceptions) vs its parent (b8c8dee, legacy -fexceptions) for eeschema and pcbnew, across the post-link wasm-opt level (-O1 vs -O2), in Chrome + Firefox, headless and headed.

TL;DR

• native-EH ships much less to download — eeschema.wasm gzip 28.9 vs 37.2 MB (−22%); pcbnew.wasm gzip 52.4 vs 70.6 MB (−26%, −18 MB). pcbnew (bigger, far more exception-heavy) shows the stronger win, in both % and absolute MB.
• native-EH loads ~30–35% faster (Chrome cold) and opens documents 20–35% faster, with the gap widening under CPU throttle — i.e. it genuinely executes less CPU per operation.
• native-EH sustains higher interaction FPS under throttle (clearest in headed/real-GPU runs).
• Ship post-link -O1, not -O2. -O1 is the smaller download (it compresses better), ~4–15× faster to build, and faster to load. -O2 even has a pathology: native pcbnew -O2 takes ~11 s to load in Firefox (vs 3.8 s for -O1). -O2 buys nothing that matters.
• headed ≠ headless and both are informative: headed = real GPU/compositor (FPS pinned near the 120 Hz cap, throttle-resilient); headless = CPU-bound (FPS collapses under throttle, exposing raw render cost). Load/open are ~mode-independent.

Setup & methodology

	native-EH	JS-EH
commit	c1ef489 (the migration)	b8c8dee (its parent)
C++ exceptions	-fwasm-exceptions (legacy encoding)	-fexceptions (JS invoke + emscripten SjLj)
kicad submodule	032540ab	032540ab (identical)
wxWidgets	67f28fb3	cca8eed9
emsdk	4.0.2	4.0.2
Binaryen (asyncify + shrink)	v130	v130 (forced; see caveats)

• Clean, cold, from-scratch builds (per-version Docker Compose project → empty build-cache volume → deps incl. OpenCASCADE rebuilt; ccache verified 0% on the first build). Isolated git worktree, branch per submodule, main checkout untouched.
• Debug builds (-O1 compile). Release (-O2 compile) can't be built on this 64 GB machine — after asyncify a few functions carry tens of thousands of spilled locals and the mandatory wasm-opt CoalesceLocals shrink OOMs >64 GB even at 1 core (CI uses a 128 GB box). Debug is what the product ships anyway, so it's the representative artifact. Both sides carry -DDEBUG identically, so the native-vs-js deltas are valid; absolute FPS is lower than a release build.
• pcbnew built with BUILD_3D_VIEWER=ON on both sides (real CPU raytracer linked). The migration commit flips the 3D viewer on by default; holding it ON for both isolates the EH variable while testing the real, 3D-capable pcbnew. eeschema has no 3D viewer.
• O1/O2 axis = post-link wasm-opt level on the same opt-independent asyncified base. Compile is -O1 (debug) for all cells.
• Machine: Apple-Silicon Mac, 64 GB. Docker 10 CPU. Core counts identical across versions: container compile -j10; asyncify BINARYEN_CORES=8; shrink BINARYEN_CORES=2 (RAM ceiling — the build container is stopped for the host post-process; measured shrink peaks: e.g. js-pcb-O1 = 32 GB).
• Runtime: headless + headed Chromium (CDP CPU throttling 1/4/6×) and Firefox (load only — throttling is Chromium-only), served locally with COOP/COEP. Cold load = navigation → fully-booted editor (visible #canvas + populated wx registry + editor Frame + kicadOpenFile + GL canvas), median of 5 fresh contexts (all cells 5/5 OK). Interaction workload = the bundled demo.kicad_sch / demo.kicad_pcb. Input driven on #canvas (the emscripten input surface).

Build time (seconds)

stage (cores)	ee-native	ee-js	pcb-native	pcb-js
compile	654	677	365¹	384¹
asyncify (v130, c8)	14	24	75	65
shrink -O1 (c2)	191	292	198	421
shrink -O2 (c2)	840	961	3082	3295

¹ pcbnew reused the (identical) deps; native = app-only, js includes a ccache-fast wx rebuild I had to force (a rsync --delete wx-source quirk removed a generated pcre table). native-EH is faster at every stage (smaller module). -O2 shrink is 4× (eeschema) to ~15× (pcbnew) slower than -O1.

Bundle size — app.wasm (decimal MB, = 10⁶ bytes)

	ee-native-O1	ee-native-O2	ee-js-O1	ee-js-O2	pcb-native-O1	pcb-native-O2	pcb-js-O1	pcb-js-O2
raw	85.6	85.6	110.1	109.2	153.5	153.1	208.8	206.8
gzip	28.9	30.0	37.2	37.8	52.4	53.9	70.6	71.4
brotli	15.4	16.6	19.6	20.2	28.3	30.0	37.4	38.4

• native-EH vs JS-EH (gzip): eeschema −22% (−8.3 MB), pcbnew −26% (−18.2 MB). JS-EH's invoke_* trampolines + SjLj + heavier asyncify instrumentation are the cost (asyncified module: ee 146 vs 190 MB; pcb 250 vs 357 MB).
• -O1 vs -O2: -O2 yields a marginally smaller raw wasm but a larger compressed one (it cuts instructions but raises byte entropy). Since downloads are compressed, -O1 is the smaller download everywhere.

Runtime — cold load (median of 5, ms)

Headless shown (headed within ~3%). ↓ is better.

	Chrome	Firefox
ee-native-O1	1182	2656
ee-js-O1	1796	3172
ee-native-O2	1505	2622
ee-js-O2	2007	3098
pcb-native-O1	1689	3796
pcb-js-O1	2501	4531
pcb-native-O2	1998	11141 ⚠
pcb-js-O2	3060	4516

• native-EH loads ~30–35% faster on Chrome (ee 1182 vs 1796; pcb 1689 vs 2501), ~16–20% on Firefox.
• ⚠ -O2 Firefox pathology: native-pcb--O2 loads ~11 s in Firefox (all 5 samples 10.8–11.3 s) vs 3.8 s for -O1 — a ~3× penalty. Firefox's wasm compiler chokes on the large -O2 output; Chrome is unaffected (2.0 s). Another concrete reason to ship -O1.
• -O1 loads faster than -O2 across the board.

Runtime — open+render a document under CPU throttle (Chrome, openMs)

Time to open+process the demo doc (parse+build+render through the EH/asyncify paths). Headless, ms @1×/4×/6×:

	1×	4×	6×
ee-native-O1	695	1526	2085
ee-js-O1	878	2229	3191
pcb-native-O1	889	1950	2713
pcb-js-O1	1024	2585	3570

native-EH is 22% faster at 1× and ~24–35% faster at 6× — the advantage widens with throttle, proving less CPU per operation (not just a smaller module). O1 vs O2 open times are near-identical (ee-native-O2 743/1643/2299; pcb-native-O2 904/2041/2846).

Runtime — sustained pan/zoom FPS (Chrome, @1×/4×/6×)

Real-input pan/zoom, frames/sec. Headed = real GPU/compositor; headless = CPU-bound.

	headed 1/4/6×	headless 1/4/6×
ee-native-O1	120 / 107 / 84	102 / 58 / 39
ee-js-O1	120 / 90 / 69	101 / 47 / 34
pcb-native-O1	120 / 115 / 84	82 / 15 / 10
pcb-js-O1	120 / 103 / 77	81 / 45 / 11

• Headed (the meaningful GPU number): native-EH holds higher FPS under throttle — ee 84 vs 69 at 6× (+22%), pcb 84 vs 77 (+9%). At 1× everything pins to the ~120 Hz display cap (GPU does the work off the throttled CPU thread).
• Headless is CPU-bound: FPS collapses under throttle, and for the big pcbnew module the numbers get noisy (10–50 fps) — treat headless FPS as a rough CPU-render indicator and openMs as the clean compute metric. Note even at 1× pcbnew headless is ~81 fps (below cap) — its board render is genuinely heavier than a schematic.

Verdict

1. The native-EH migration is a clear, broad win — smaller download (−22% ee, −26% pcb), faster load (~30–35%), faster document open (widening under load), higher sustained FPS, and faster builds. Nothing regressed; every cell boots 5/5. pcbnew, the harder app, wins bigger.
2. Ship post-link -O1. Smaller download, 4–15× faster to build, faster to load (and no -O2 Firefox-compile pathology), for equal runtime. -O2's smaller-raw-wasm is a mirage once gzipped.

Caveats

• Debug, not release (release OOMs on 64 GB). Absolute FPS carries -DDEBUG overhead, but the native-vs-js and O1/O2 deltas are valid, and debug is what ships.
• Binaryen v130 forced on JS-EH (as-shipped it'd use emsdk v121, whose -O2 is ~9× slower) to isolate the EH variable from the toolchain. The v130 bump actually shipped with the migration.
• wxWidgets differs (part of the migration); kicad is byte-identical. pcbnew held at 3D-ON on both; the as-shipped native additionally defaults 3D on (already included here for both).
• Shrink ran at cores=2 for both (RAM ceiling); absolute shrink times would drop at more cores, but the comparisons are at matched settings.

Reproduce

Throwaway worktree (bench/native-eh @ c1ef489, bench/jseh @ b8c8dee), per-version Docker projects for clean isolated deps. Per cell: docker/build.sh <app> --debug --full/--clean-kicad --compile-only (pcbnew adds BUILD_3D_VIEWER=ON) → ASYNCIFY_ONLY=1 BINARYEN_CORES=8 … --postprocess-only (js-EH adds BINARYEN_VERSION=130) → wasm-opt -O{1,2} [-all] at BINARYEN_CORES=2. Perf via a headless/headed Playwright harness (COOP/COEP server, CDP CPU throttling).