pcbjam/docs/features/async/02-asyncify-internals.md

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. The de-park regressed the coroutine suite, and Design B is now being built to fix it (12 + 13). 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)

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):

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.