# 02 — The machine: Asyncify internals and control flows > **STATUS (2026-06-23):** the top-level `emscripten_set_main_loop(...,1)` `throw "unwind"` this doc treats as current **is gone** — it was fatal under native wasm-EH and was replaced by the Asyncify **de-park** rAF pump (`wxWasmParkMainLoop`); see [`../wasm-exceptions/09`](../wasm-exceptions/09-event-loop-deparking-plan.md). The de-park regressed the coroutine suite, and **Design B is now being built to fix it** ([`12`](12-design-b-asyncify-implementation-plan.md) + [`13`](13-design-b-engineering-spec.md)). Read below as the pre-de-park analysis (the internals are still accurate). This is the legible model: what suspends, who owns the single slot, and exact line-by-line control flow for the park, the hang, the crash, and **de-parking**. --- ## §0. One-paragraph model Emscripten Asyncify has **two global registers**: `Asyncify.state` (`Normal=0 / Unwinding=1 / Rewinding=2`) and `Asyncify.currData` (pointer to *the* save buffer). They describe **"the single suspension currently in flight."** The runtime assumes **at most one** suspension is live and that it **fully rewinds before the next begins.** KiCad-WASM breaks that because **three subsystems drive those same two registers**: tool coroutines (libcontext → `emscripten_fiber_swap`), modal dialogs + clipboard (`EM_ASYNC_JS` → `handleSleep`), and the parked main loop. Overlap on the single slot → one context reads a buffer that is no longer its own → crash or hang. --- ## §1. What "sleeps" and what does not "Sleep" = an **Asyncify suspension**: the wasm stack is *unwound* into a buffer, control returns to JS, JS runs, then the stack is *rewound*. The only wasm exports involved are `_asyncify_start_unwind / stop_unwind / start_rewind / stop_rewind` (`pcbnew.js:15532-15538`); **all scheduling is JS glue.** C++ never writes `currData`/`state` — it only spills/restores locals when the JS-driven state says to. | Call | Sleeps? | Mechanism | Where | |---|---|---|---| | `emscripten_fiber_swap` (tool coroutine swap) | **YES** | unwind source fiber + rewind target fiber | `pcbnew.js:11557` | | `startModal` (`wxDialog::ShowModal`) | **YES** | `EM_ASYNC_JS` → `handleSleep`, awaits a Promise | `dialog.cpp:201` | | `js_clipboardHasText` (old `IsSupported`) | **YES** | `EM_ASYNC_JS`, `readText()` raced vs 2 s timeout | `clipbrd.cpp:118` | | `js_readTextFromClipboard` (paste) | **YES** | `EM_ASYNC_JS`, only on user gesture | `clipbrd.cpp:76` | | `js_writeTextToClipboard` / `js_clearClipboard` | **YES** | `EM_ASYNC_JS` | `clipbrd.cpp:38`, `:145` | | `js_enumerateFonts` | **YES** | `EM_ASYNC_JS` | `fontenum.cpp:33` | | `js_isClipboardAPIAvailable` / `js_isFontAccessAPIAvailable` | **NO** | synchronous `EM_JS` capability probe | `clipbrd.cpp:29`, `fontenum.cpp:25` | | `emscripten_async_call`, `emscripten_async_run_in_main_runtime_thread` | **NO** | timer/main-thread dispatch, not a suspend | `timer.cpp:80`, `utils.cpp:162/183` | | `ProcessEvents` (one main-loop tick) | **NO** by itself | plain C call on a fresh stack; sleeps only if something *inside* does | `evtloop.cpp:19` | | the rAF main-loop tick | **NO** | `requestAnimationFrame`/`setTimeout` re-enters wasm fresh each frame | `pcbnew.js:11342` | | `emscripten_set_main_loop(...,1)` "infinite loop" | **NO** (not a sleep!) | `throw "unwind"` — a *plain JS exception*, not Asyncify | `pcbnew.js:11392` | **The single most important correction:** the main loop's "park" is **not** an Asyncify suspension. It is a thrown JS string. This matters enormously (§7). The complete inventory of EM_ASYNC_JS "sleep" sites is **6**, all in `wxwidgets/src/wasm/` (the KiCad tree has **zero** EM_ASYNC_JS / `emscripten_sleep`): `dialog.cpp:201`, `clipbrd.cpp:38/76/118/145`, `fontenum.cpp:33`. This is why a fix can stay in the wasm layer. --- ## §2. The three suspension producers ### 2a. Tool coroutines = libcontext = emscripten fibers KiCad runs interactive tools as coroutines (`COROUTINE` in `kicad/include/tool/coroutine.h`). `Call`/`Resume`/`KiYield` switch stacks via `libcontext::jump_fcontext` (`coroutine.h:530`, `:548`). On wasm, libcontext is **not** native assembly — it is a shim over emscripten fibers (`libcontext.cpp`): `make_fcontext` → `emscripten_fiber_init` (`:287`); `jump_fcontext` → `emscripten_fiber_swap` (`:320`). So **"a tool fiber swap" is literally `emscripten_fiber_swap`, which drives `Asyncify.currData`/`state`.** Each `wasm_fcontext` embeds its **own** asyncify buffer (`libcontext.cpp:98` `char asyncify_stack[64*1024]`, `ASYNCIFY_STACK_SIZE` at `:34`), bound at `emscripten_fiber_init` (`:287`); the main stack is fiberized via `emscripten_fiber_init_from_current_context` (`:210-212`). libcontext keeps its own `g_current_context`, a per-context `resume_epoch` to detect "ghost resumes" (`:323`), and a `[[noreturn]]` trampoline `wasm_fcontext_entry` (`:228`) that loops forever so a finished coroutine swaps back instead of returning. `KICAD_DIAG_COROUTINE` (`kicad/include/kicad_wasm_diag.h`) logs every `jump-enter / save-slot / jump-swap / jump-resume / jump-ghost / entry-call / trampoline-swap`. ### 2b. Modal dialogs (and the old clipboard) = EM_ASYNC_JS = handleSleep `wxDialog::ShowModal` (`dialog.cpp:245`) must *block and return an `int`* (native semantics — hundreds of KiCad sites do `if( dlg.ShowModal()==wxID_OK )`). A browser main thread cannot block, so `startModal` (`dialog.cpp:201`) is an `EM_ASYNC_JS` that: suspends the C++ stack via Asyncify, runs a `setTimeout(17ms)` loop calling `ProcessEvents` so the UI stays live, and resolves when `EndModal` (`dialog.cpp:286`) fires `Module._endModal(code)`. **The modal is, structurally, a coroutine on `handleSleep`.** The old clipboard `IsSupported` (`clipbrd.cpp:288`) used the same road. ### 2c. The main loop "park" `wxGUIEventLoop::DoRun` (`evtloop.cpp:85`) ends with `emscripten_set_main_loop(ProcessEvents, 0, /*simulate_infinite_loop=*/1)` (`:107`). Dissected in §4 and §7. --- ## §3. The Asyncify engine (the JS glue) ### handleSleep — the EM_ASYNC_JS / sleep road (`pcbnew.js:10160`) - First entry, `state==Normal`: call `startAsync(wakeUp)`. If `wakeUp` is not called synchronously, a real suspend begins (`:10219`): `state=Unwinding; currData = allocateData(); MainLoop.pause(); start_unwind()`. - Promise resolves → `wakeUp(result)` (`:10169`): `state=Rewinding; start_rewind(currData); MainLoop.resume(); doRewind(currData)`. `doRewind` reads **field #8 of the buffer** to learn *which exported function to re-enter* (`getDataRewindFuncName`, `:10143`). **If `currData` is wrong or null here → garbage → `RuntimeError: index out of bounds`.** - Re-entry at `state==Rewinding` (`:10229`): `state=Normal; stop_rewind(); free(currData); currData=null`. > Asymmetry: the sleep road pauses/resumes `MainLoop` (`:10225`, `:10180`). The fiber road does > **not** touch `MainLoop`. ### fiber swap — the coroutine road (`pcbnew.js:11557`) ```js function _emscripten_fiber_swap(oldFiber, newFiber) { if (Asyncify.state === Asyncify.State.Normal) { // leaving a fiber Asyncify.state = Asyncify.State.Unwinding; var asyncifyData = oldFiber + 20; // OLD fiber's embedded buffer Asyncify.setDataRewindFunc(asyncifyData); Asyncify.currData = asyncifyData; // <-- writes the single slot _asyncify_start_unwind(asyncifyData); Fibers.nextFiber = newFiber; // schedule the rewind target } else { // landing back via rewind Asyncify.state = Asyncify.State.Normal; _asyncify_stop_rewind(); Asyncify.currData = null; } } ``` The actual rewind of the *target* is deferred to **`Fibers.trampoline`** (`pcbnew.js:11522`), invoked from **`maybeStopUnwind`** (`:10097`) once the unwind reaches bottom (`exportCallStack.length===0`) — `maybeStopUnwind` also `runtimeKeepalivePush()`es (`:10105`): ```js trampoline() { if (!Fibers.trampolineRunning && Fibers.nextFiber) { // GUARD Fibers.trampolineRunning = true; do { var f = Fibers.nextFiber; Fibers.nextFiber = 0; Fibers.finishContextSwitch(f); } while (Fibers.nextFiber); Fibers.trampolineRunning = false; // only reached if body returns } } finishContextSwitch(newFiber) { // the rewind half ... restore stack limits/pointer ... if (entryPoint !== 0) { Asyncify.currData = null; dynCall_vi(entryPoint, userData); } // first run else { var d = newFiber+20; Asyncify.currData = d; Asyncify.state = Rewinding; _asyncify_start_rewind(d); Asyncify.doRewind(d); } // resume } ``` **Two fragilities:** 1. `finishContextSwitch` re-enters wasm (`doRewind`/`dynCall_vi`). If that re-entered code itself unwinds before returning, the `do/while` is abandoned with `trampolineRunning===true` (the reset never runs). **Every future `Fibers.trampoline()` then fails the guard** → pending `nextFiber` never processed → **hang.** (This is the facet the pasted `try/finally` "self-heal" targets.) 2. fiber buffers come from `emscripten_fiber_init`, **not** `Asyncify.allocateData`, so the `handlesleep.js` shim is **blind to them.** ### The #9153 shim — what `handlesleep.js` is, and where it comes from `tests/apps/kicad/pcbnew.js` is **generated** (emscripten link, then post-processed; committed but overwritten by every build). The handleSleep override is **not** Emscripten's — its source of truth is **`scripts/common/shims/handlesleep.js`**, injected verbatim into `pcbnew.js` by **`scripts/common/inject-dyncall-shims.sh`** (`cat "$SHIM_DIR/handlesleep.js" >>`) right after the `_emscripten_fiber_swap.isAsync = true;` marker (~`pcbnew.js:11579`). Build order (`docker/build.sh:123-156`): **link → inject-dyncall-shims.sh → apply-finalize.sh → apply-asyncify.sh.** `inject-dyncall-shims.sh` injects, in order: (1) per-signature `dynCall_*` bindings, (2) six inline empty-callback fixes, (3) `handlesleep.js`, (4) optional `diagnostics.js` (only with `SHIM_DIAGNOSTICS=1` — source of the `[CLIP-DIAG]`/`[DIAG_SLEEP]` log lines). The trampoline self-heal is **not present today.** The asyncify pass itself (`apply-asyncify.sh`) uses imports `env.invoke_*,env.__asyncjs__*,env.emscripten_fiber_swap` (`:33`), a large-function removelist (`:37-50`), then a `-O2` shrink pass (`:72`). What the shim does: tag each `handleSleep` with the buffer it allocated, and in `wakeUp` restore `Asyncify.currData = thatBuffer` right before `start_rewind`/`doRewind` — so a fiber swap that clobbered the slot during the await doesn't make the sleep rewind the wrong buffer. **It fixes exactly one level of nesting, and only for sleeps (not fibers).** --- ## §4. Control flow — startup, and how the loop becomes "parked" ``` run() -> doRun() -> callMain() pcbnew.js:21346 └─ entryFunction(argc,argv) == wasmExports["__main_argc_argv"] (C main) └─ wxEntry -> wxEntryReal() init.cpp:464 ├─ wxTheApp->CallOnInit() (build UI, frames, tools…) │ └─ [STARTUP BURST: tool coroutines Call/Yield/Resume run here. │ Each is an emscripten_fiber_swap; currData churns Normal<->set<->null. │ These WORK because main's real C stack is on exportCallStack, │ so each unwind reaches bottom, trampoline fires, target rewinds.] ├─ class CallOnExit { ~CallOnExit(){ wxTheApp->OnExit(); } } callOnExit; init.cpp:488 └─ return wxTheApp->OnRun() └─ MainLoop() -> wxGUIEventLoop::DoRun() evtloop.cpp:85 └─ emscripten_set_main_loop(ProcessEvents,0,1) evtloop.cpp:107 └─ setMainLoop(...) pcbnew.js:11324 ├─ _emscripten_set_main_loop_timing(1,1) :11387 │ └─ runtimeKeepalivePush(); MainLoop.running=true :11270 │ (★ runtime now stays alive even if main "exits") ├─ MainLoop.scheduler() -> schedules first rAF tick └─ if (simulateInfiniteLoop) throw "unwind"; :11392 <-- THE PARK ``` The `throw "unwind"` propagates **as a plain JS exception** out through every wasm frame of `OnRun/DoRun/...` (abandoned, *not* asyncify-saved, *no* C++ destructors) up to: ``` callMain catch(e) -> handleException(e) pcbnew.js:21362, 1391 └─ e == "unwind" -> return EXITSTATUS (swallowed silently) :1397 ``` **Result of the park:** - The native C stack of `main()` (and `wxEntryReal`/`OnRun`/`DoRun`) is **gone**. - **`CallOnExit::~CallOnExit()` (→ `OnExit()`) and `wxEntryCleanupReal()` NEVER RUN** — the app, frames, and tools stay alive. *This is the entire purpose of `simulate_infinite_loop=1`.* - The runtime stays alive purely via the keepalive counter (★). Each rAF tick re-enters wasm fresh through `MainLoop.runner → runIter → callUserCallback(ProcessEvents)` (`pcbnew.js:11342→11452→10003`) on a **brand-new C stack**. `ProcessEvents` (`evtloop.cpp:19`) pumps `ProcessPendingEvents` + `Paint` + every-third `ProcessIdle`, then returns. **No sleep in a quiet tick.** --- ## §5. Control flow — the HANG (first tool interaction after startup) ``` rAF tick -> ProcessEvents -> TOOL_MANAGER -> coroutine->Resume()/Call() └─ libcontext::jump_fcontext -> emscripten_fiber_swap(old,new) currData = old+20; start_unwind └─ unwind propagates out of ProcessEvents … └─ maybeStopUnwind (exportCallStack==0?) -> Fibers.trampoline() └─ finishContextSwitch(new): currData=new+20; start_rewind; doRewind(new) └─ tool body runs … yields/returns … swaps back to caller … ``` Healthy idle ends with `currData == null`. The measured bug state was **`state==Normal` but `currData != null`** — an unwind happened, its rewind was never issued; the swap parks forever; all post-idle tool interactivity dies. **Why the *first post-startup* swap?** Two credible mechanisms, both rooted in §4's `throw "unwind"` (not mutually exclusive): 1. **Dangling `currData` from the abnormal teardown.** The throw abandons the C stack **without** running `stop_unwind/stop_rewind` or resetting the Asyncify globals. If the startup burst left an in-flight / half-settled fiber context at the moment `DoRun` threw, `currData` stays non-null into idle. The next `emscripten_fiber_swap` enters the `state==Normal` branch and **overwrites** `currData` with `old+20`, orphaning the dangling buffer; the orphan can never be rewound → hang. 2. **Stuck trampoline guard.** If a swap inside `Fibers.trampoline`'s `do/while` unwound and never returned (§3 fragility #1), `trampolineRunning` is stuck `true`, so the first post-startup swap's `nextFiber` is scheduled but the trampoline early-returns → hang. > **Decisive diagnostic (cheap, no rebuild — JS-only):** log `Asyncify.currData`, > `Asyncify.state`, `Fibers.trampolineRunning` at (a) the last line of `DoRun` *before* the > throw, (b) the first rAF tick, (c) the entry of the first post-startup `emscripten_fiber_swap`. > Compare `currData` against `g_main_context`'s buffer and any live coroutine's `fiber+20`. That > tells you which of #1/#2 (or both) is in play — and whether a `currData` authority alone fixes > it or de-parking is required. --- ## §6. Control flow — the CRASH (clipboard), for contrast ``` post-load idle -> (wx paste-enable / GetClipboardUTF8) -> wxClipboard::IsSupported(wxDF_TEXT) └─ js_clipboardHasText (EM_ASYNC_JS) -> handleSleep: currData=bufA; MainLoop.pause(); start_unwind └─ PARKED up to 2 s awaiting readText() (headless => always full timeout) ├─ during the wait a modal tears down (EndModal:5100) -> emscripten_fiber_swap │ └─ currData = fiberF+20 <-- clobbers bufA in the single slot ├─ 2nd/3rd clipboard polls stack up (log: pendingSleeps->3, one ENTER at state=2) └─ bufA's Promise resolves -> handleSleep wakeUp: start_rewind(currData=null/F) └─ doRewind(null) -> reads garbage field#8 -> RuntimeError: index out of bounds ``` Same slot, opposite victim: a long-parked **sleep** clobbered by a **fiber swap** (crash) vs. in §5 a **fiber swap** stranded by a dirtied slot (hang). --- ## §7. "De-parking" in finest detail **What it means:** change `evtloop.cpp:107` to `emscripten_set_main_loop(ProcessEvents, 0, /*simulate_infinite_loop=*/0)`. Then `setMainLoop` does **not** throw (`pcbnew.js:11391` skipped); it **returns normally** into `DoRun`, which returns up the C++ stack. Asyncify globals are left in the clean state ordinary C++ returns produce — removing mechanism §5#1 at the source. **The lifecycle trap it creates (why `=1` exists):** if `DoRun` returns, the C++ unwind runs the teardown the park was hiding: ``` DoRun returns -> OnRun returns -> wxEntryReal: ├─ ~CallOnExit() -> wxTheApp->OnExit() init.cpp:488 └─ wxEntry -> wxEntryCleanupReal() init.cpp:433 ├─ wxTheApp->CleanUp() (deletes ALL top-level windows, pending objects) ├─ delete app; (destroys wxTheApp) init.cpp:448 └─ DoCommonPostCleanup() => then C main returns => callMain: exitJS(ret, implicit=true) pcbnew.js:21360 └─ _proc_exit: keepRuntimeAlive()==true (keepalive ★) => does NOT abort :1383 => runtime KEEPS RUNNING, rAF keeps firing ProcessEvents … … but wxTheApp + all windows are already FREED => next tick touches freed memory (this is also the null-IsModal/windowClosing close crash). ``` So the runtime survives (keepalive), but the app is torn down under the still-firing loop. **That is precisely the trap `simulate_infinite_loop=1` avoids — not by keeping the runtime alive (the keepalive counter already does that), but purely by preventing the C++ cleanup from running.** **A correct de-park is therefore two coupled changes:** 1. `emscripten_set_main_loop(..., 0)` so `DoRun` returns with clean Asyncify state, **and** 2. **suppress the destructive post-`MainLoop` teardown** so the live app isn't freed. Options: - **(2a)** a wasm-specific `OnRun`/event-loop path whose return does *not* fall into `~CallOnExit`/`wxEntryCleanupReal`, with real cleanup driven from **`UnloadCallback`** (`app.cpp:620`, registered `:694`) on `beforeunload`. - **(2b)** keep `wxEntryReal` but guard `wxEntryCleanupReal`/`OnExit` to no-op while the rAF loop is registered (a "main loop owns lifetime" flag), deferring real cleanup to unload. Either way the rAF loop becomes the sole owner of app lifetime; `ScheduleExit` (`evtloop.cpp:40`, `emscripten_cancel_main_loop`) is the one teardown path. **What de-parking fixes / doesn't:** - **Fixes:** the dangling-`currData`-at-idle mechanism (§5#1) and the null-`IsModal` close crash. - **Does not, by itself, fix:** the fundamental slot-sharing — two genuinely overlapping suspensions still contend for one `currData`. De-parking removes the *base occupant*; it does not make concurrent suspensions compose. The trampoline-guard facet (§5#2) is independent. **Cost:** `evtloop.cpp` + `app.cpp`/`init.cpp` change → full wx rebuild + relink, touches shutdown. A prior `CallAfter`-deferral of the call site was tried and reverted — evidence the problem is the *abandoned-unwind topology*, not the timing of when the loop is installed. --- ## §8. Why we can't just "make the modal not sleep" `ShowModal()` must hand KiCad a **blocking `int`** (native semantics; rewriting call sites is a KiCad change, against policy). In a single-threaded browser the only ways to "return later from a call that hasn't finished" are (a) block the thread — impossible, freezes the tab — or (b) suspend the stack (Asyncify/fiber). So the modal is **necessarily** a suspension. Re-homing it onto a fiber buys nothing (fibers are the same `currData` machine). The durable answer is to make suspensions **compose**, i.e. fix the slot — see [`03-solutions-and-prior-art.md`](03-solutions-and-prior-art.md).