Add REENTRANT_JSPI: a shadow stack per JSPI activation

C frames live on the shadow stack in linear memory, which JSPI does not
save across a suspension. When a promising activation ("fiber") resumes
while another one is suspended, its frames are pushed over the suspended
one's, so concurrent promising calls silently corrupt each other. That
rules out server-style programs handling requests concurrently under JSPI.

With -sREENTRANT_JSPI every fiber gets its own shadow stack, allocated
from the heap when the promising export is entered (JSPI_FIBER_STACK_SIZE
bytes, defaulting to STACK_SIZE) and released when it exits, with a small
per-thread pool of released stacks that is freed at thread exit. The stack
pointer is switched at the four lifecycle hooks: to the fiber's stack at
ENTER and RESUME, and back to whatever the host had at SUSPEND and EXIT,
including on the exceptional exits the hook wrappers already route
through. Since the frames never move, imports that write results through
pointers into a suspended fiber's frames (emscripten_promise_await, poll,
EM_ASYNC_JS out-parameters) keep working, and the host's own stack
allocations are never overlapped.

The four __jspi_* exports are now assembly shims around C implementations,
so that the stack pointer they install persists past their return; the
stack limits used by emscripten_stack_get_* and by STACK_OVERFLOW_CHECK=2
are switched the same way, after all C code has returned. A fiber stack
lives in the heap with no address-zero guard like the main stack, so the
setting defaults STACK_OVERFLOW_CHECK to 2 and an overflow traps at the
overflowing store; builds that explicitly opt out get a small guard region
below each stack (JSPI_FIBER_STACK_GUARD) with cookies checked whenever
the fiber suspends or exits. Fibers are
thread-affine and each thread has its own set. Dynamic linking is not
supported with the setting.

Also fixes the decorator order of test_async_ccall_promise, whose `jspi`
variant was running ASYNCIFY (mode decorators must be outermost); the new
`reentrant_jspi` test mode needs it.

Depends on the JSPI lifecycle hooks (<emscripten/jspi.h>).

Author: guybedford

ChangeLog.md

@@ -31,6 +31,11 @@ See docs/process.md for more on how version tagging works.
   and a JSPI export fetched from the table as a function pointer is no longer
   promised automatically. Independently of the setting, `invoke_*` imports are
   no longer treated as suspending under JSPI.
+- Added the experimental `-sREENTRANT_JSPI` setting, which runs every JSPI
+  promising activation on its own shadow stack so that any number of them may
+  be suspended at once and interleave, instead of corrupting each other's
+  frames. `JSPI_FIBER_STACK_SIZE` sets the per-activation stack size, and
+  `STACK_OVERFLOW_CHECK` defaults to 2 so that an overflow of one traps.
 - The SDL3 port is no longer considered experimental, and the compiler
   diagnostic warning has been removed. (#27646)
 - `WASM=0` and `WASM=2` (wasm2js) were marked as deprecated. (See #27608)

site/source/docs/porting/asyncify.rst

@@ -485,6 +485,45 @@ signature (an ``ASSERTIONS`` build reports the missing trampoline). Calling
 ``WebAssembly.promising`` on a wrapped export from your own JS is fine; only a
 raw table entry made promising bypasses the hooks.
 
+.. _reentrant_jspi_stacks:
+
+Concurrent JSPI activations
+###########################
+
+Every promising export starts a fiber that may suspend; while it is suspended
+another promising call may start, or an earlier one resume. The frames of C
+code live on the shadow stack in linear memory, which JSPI does not save, so by
+default a fiber that resumes while another is suspended pushes its frames over
+the other one's and corrupts it. That is fine for the common pattern of one
+promising call at a time, awaited before the next, but not for a server-like
+program that handles requests concurrently.
+
+:ref:`REENTRANT_JSPI` runs every fiber on its own shadow stack (allocated from
+the heap on entry, :ref:`JSPI_FIBER_STACK_SIZE` bytes each, released on exit)
+and switches the stack pointer at the :ref:`lifecycle hooks <jspi_hooks>`, so
+any number of fibers may be suspended at once and resume in any order. This
+also holds for a promising export entered synchronously from inside another
+fiber's import call, and for exceptions unwinding out of a suspended fiber.
+Fibers never move between threads, and each thread has its own set. Dynamic
+linking is not supported with it yet.
+
+Sizing: every live fiber, ``main`` included, holds a :ref:`JSPI_FIBER_STACK_SIZE`
+stack for as long as it is suspended, and a few released stacks are kept per
+thread for reuse, so tune it independently of ``STACK_SIZE`` (which it defaults
+to): a program built with ``-sSTACK_SIZE=8MB`` that serves requests
+concurrently would otherwise hold 8 MB per in-flight request. A fiber stack
+lives in the heap and has no hardware-style guard like the main stack has with
+``STACK_FIRST``, so ``REENTRANT_JSPI`` defaults ``STACK_OVERFLOW_CHECK`` to 2:
+the stack limits are switched per fiber and an overflow traps at the
+overflowing store itself. Setting ``STACK_OVERFLOW_CHECK`` explicitly to 1 or
+0 opts out; then a :ref:`JSPI_FIBER_STACK_GUARD` region (16KB by default) below
+each stack keeps an overflow of up to that size inside memory the runtime
+owns, reported when the fiber next suspends or exits.
+Hooks registered with ``jspi_register`` run on the fiber's stack for
+``JSPI_SUSPEND``/``JSPI_RESUME``/``JSPI_EXIT`` and on the caller's stack for
+``JSPI_ENTER``. A trap inside a fiber leaves its stack unreleased and the
+stack pointer undefined, as with any trap.
+
 Optimizing Asyncify
 ###################
 

site/source/docs/tools_reference/settings_reference.rst

@@ -1414,6 +1414,47 @@ function pointer is no longer made promising automatically. Requires
 
 Default value: false
 
+.. _reentrant_jspi:
+
+REENTRANT_JSPI
+==============
+
+Run each promising activation on its own shadow stack, so that any number
+of activations may be suspended at once on a thread and run interleaved
+(see :ref:`reentrant_jspi_stacks`). Requires ``JSPI`` and implies ``JSPI_HOOKS``;
+defaults ``STACK_OVERFLOW_CHECK`` to 2 so that a fiber stack overflow traps
+(set it explicitly to opt out); not supported with dynamic linking.
+
+.. note:: This is an experimental setting
+
+Default value: false
+
+.. _jspi_fiber_stack_size:
+
+JSPI_FIBER_STACK_SIZE
+=====================
+
+The size of the shadow stack given to each promising activation under
+``REENTRANT_JSPI``, in bytes. Every live activation holds one, so tune it
+independently of ``STACK_SIZE``, which it defaults to.
+
+Default value: 0
+
+.. _jspi_fiber_stack_guard:
+
+JSPI_FIBER_STACK_GUARD
+======================
+
+The size of the guard region below each ``REENTRANT_JSPI`` activation
+stack, in bytes, for builds that opt out of ``STACK_OVERFLOW_CHECK=2``: a
+stack overflow of up to this size stays inside memory the runtime owns and
+is reported when the activation next suspends or exits, instead of silently
+corrupting the heap below. Defaults to 0 with ``STACK_OVERFLOW_CHECK=2``
+(the bounds check traps at the overflowing store itself) and to 16KB
+otherwise; 0 disables the guard (the checks at suspension and exit remain).
+
+Default value: -1
+
 .. _exported_runtime_methods:
 
 EXPORTED_RUNTIME_METHODS

src/lib/libasync.js

@@ -483,6 +483,23 @@ addToLibrary({
 #endif
   },
 
+#if REENTRANT_JSPI
+  __jspi_fiber_stack_size__sig: 'p',
+  __jspi_fiber_stack_size: () => {{{ JSPI_FIBER_STACK_SIZE }}},
+  __jspi_fiber_stack_guard__sig: 'p',
+  __jspi_fiber_stack_guard: () => {{{ JSPI_FIBER_STACK_GUARD }}},
+  __jspi_stack_checked__sig: 'i',
+  __jspi_stack_checked: () => {{{ STACK_OVERFLOW_CHECK >= 2 ? 1 : 0 }}},
+  // The bounds the stack-check pass instruments against live in globals it
+  // generates, reachable only through its export.
+  __jspi_set_stack_limits__sig: 'vpp',
+  __jspi_set_stack_limits: (base, end) => {
+#if STACK_OVERFLOW_CHECK >= 2
+    ___set_stack_limits(base, end);
+#endif
+  },
+#endif
+
   emscripten_sleep__async: 'auto',
   emscripten_sleep: (ms) => new Promise((resolve) => setTimeout(resolve, ms)),
 

src/lib/libcore.js

@@ -1739,7 +1739,11 @@ addToLibrary({
     var end = _emscripten_stack_get_end();
     abort(`stack overflow (Attempt to set SP to ${ptrToString(requested)}` +
           `, with stack limits [${ptrToString(end)} - ${ptrToString(base)}` +
+#if REENTRANT_JSPI
+          ']). If you require more stack space build with -sSTACK_SIZE=<bytes> (or, inside a JSPI activation, -sJSPI_FIBER_STACK_SIZE=<bytes>)');
+#else
           ']). If you require more stack space build with -sSTACK_SIZE=<bytes>');
+#endif
   },
 #endif
 

src/settings.js

@@ -962,6 +962,31 @@ var JSPI_IMPORTS = [];
 // [experimental]
 var JSPI_HOOKS = false;
 
+// Run each promising activation on its own shadow stack, so that any number
+// of activations may be suspended at once on a thread and run interleaved
+// (see :ref:`reentrant_jspi_stacks`). Requires ``JSPI`` and implies ``JSPI_HOOKS``;
+// defaults ``STACK_OVERFLOW_CHECK`` to 2 so that a fiber stack overflow traps
+// (set it explicitly to opt out); not supported with dynamic linking.
+// [link]
+// [experimental]
+var REENTRANT_JSPI = false;
+
+// The size of the shadow stack given to each promising activation under
+// ``REENTRANT_JSPI``, in bytes. Every live activation holds one, so tune it
+// independently of ``STACK_SIZE``, which it defaults to.
+// [link]
+var JSPI_FIBER_STACK_SIZE = 0;
+
+// The size of the guard region below each ``REENTRANT_JSPI`` activation
+// stack, in bytes, for builds that opt out of ``STACK_OVERFLOW_CHECK=2``: a
+// stack overflow of up to this size stays inside memory the runtime owns and
+// is reported when the activation next suspends or exits, instead of silently
+// corrupting the heap below. Defaults to 0 with ``STACK_OVERFLOW_CHECK=2``
+// (the bounds check traps at the overflowing store itself) and to 16KB
+// otherwise; 0 disables the guard (the checks at suspension and exit remain).
+// [link]
+var JSPI_FIBER_STACK_GUARD = -1;
+
 // Runtime elements that are exported on Module by default. We used to export
 // quite a lot here, but have removed them all. You should use
 // EXPORTED_RUNTIME_METHODS for things you want to export from the runtime.

system/include/emscripten/jspi.h

@@ -24,6 +24,14 @@
 extern "C" {
 #endif
 
+// Hooks run synchronously inside the boundary call, on whatever stack the
+// fiber's code runs on: ENTER before the export body (the fiber is already
+// current), SUSPEND before the import is called with the fiber's frames still
+// live, RESUME after the import returned with the frames live again, and EXIT
+// after the export body returned, with the fiber still current. A trap inside
+// a fiber bypasses the hooks and leaves the JSPI state (and, with
+// REENTRANT_JSPI, the stack pointer) undefined.
+//
 // Events are bit flags so that they combine into the mask for jspi_register.
 typedef enum {
   // A promising export was called.