Add jspi-hooks pass

[guybedford]

This implements a --jspi-hooks pass that wraps the JSPI entry/exit/suspend/resume boundaries of a module with calls to corresponding lifecycle hooks the module itself provides.

This is needed in Binaryen itself because it cannot be done at another layer of the system - suspension incurs a microtask, so that any JS wrappers around the suspend JS function will not be correct, and any exit wrapper on the WebAssembly.promising itself will also not have the correct timing.

Only by directly integrating the synchronous timing of the hooks into the Wasm can we get sound tracking of JSPI context switching.

The use cases are various here:

• Supporting stack save/restore for reentrant JSPI
• Checking if a suspension happened or not for a given fiber
• Giving JSPI "fibers" a unique identity
• Any async context associations associated with that ID
• Thread-local context switching if appropriate

The alternative to this approach would be to more heavily define JSPI instrumentation:

• Assuming the fiber identity model and creating our own ID system
• Assuming the stack switching model and handling that automatically instead of through hooks.

Given where JSPI is in its ecosystem adoption as an emerging convention, a general hooks-based approach feels like the best way to start on these problems for now.

The hooks are four function exports which must be provided by the binary for the transform to work:

__jspi_enter:   [] -> [i64 token]
__jspi_exit:    [i64 token, i32 error] -> []
__jspi_suspend: [] -> [i64 token]
__jspi_resume:  [i64 token, i32 error] -> []

They are called on every JSPI enter/exit/suspend/resume operation:

• token: opaque i64 - the wrapper passes the value the before hook returned to the matching after hook (enter→exit, suspend→resume) through a wasm local, which JSPI preserves across the suspension; the pass never interprets it. This is what supports passing e.g. fiber IDs / stack identifiers across the pairs.
• error: 1 on the after hooks when the wrapped call threw, else 0.

Then similar to the lines of asyncify, the PR here implements for Binaryen that contract as a transform pass:

• --pass-arg=jspi-exports@<patterns>: each matching export is retargeted to a wrapper calling __jspi_enter and __jspi_exit around it.
• --pass-arg=jspi-imports@<patterns>: each matching import is moved to a new import and the original function object becomes a wrapper calling __jspi_suspend and __jspi_resume and passing the token between them, so every existing use (calls, ref.func, element segments, exports) reaches the wrapper with no reference rewriting.
• --pass-arg=jspi-dyncalls (plus jspi-dyncall-sigs@ii,vi for extra signatures) also exports a wrapped __jspi_dyncall_<sig>(fptr, ...) trampoline around call_indirect per function signature in the table, so hosts that make function pointers promising (Emscripten's promising dynCall, embind async()) do not bypass the hooks. <sig> is the getSig() alphabet.

When instrumented:

• The wrappers are locals only and the pass enables EH and reference types so unwinds are fully supported.
• Every JSPI boundary crossing gets two extra direct calls, performance impact is expected to be negligible.
• Both error paths go through the hooks: a try_table (catch_all_ref) calls the after hooks with error=1, then throw_refs the exception unchanged, whatever its tag, so the pass needs no knowledge of any tag and no imports. Modules already using legacy EH get the legacy try/catch_all/rethrow form, since engines reject mixing the two; a module that already mixes them is rejected with a pointer to --translate-to-exnref.
• Multivalue results are supported (tuple local); pattern lists take *, comma/newline separators and @file response files like asyncify.

The actual behaviors of the JSPI system are otherwise entirely left to the hook runtime implementations, with Emscripten expected to support a C runtime implementation for interfacing with JSPI hooks and also using it to build REENTRANT_JSPI (PR which is based on this).

Due to the generality though, other runtimes could implement their own custom systems similarly.

Tests: lit coverage of import wrapping through direct calls, ref.func, element segments and exported imports; export retargeting with internal callers untouched; hook exclusion; features; response files; both EH forms; multivalue; trampolines with explicit signatures; the Fatal cases; --roundtrip/-O2 stability; and an engine-level test/lit/d8 run of the wrapped module under real JSPI (V8) checking the full event trace, exception identity through the rethrow, SuspendError reaching the resume hook, id forwarding across a real suspension, nested promising entry from a plain import, and a trampoline call.

Made with AI assistance under my review

[tlively]

Alternatively, we could also have 4 separate functions, but I wanted to try and keep the contract minimal here.

Using separate functions seems like it would be better for follow-up optimizations and seems like it might be simpler in the end than using opaque operation codes.

---

Stepping back, is the idea that this would be used for "advanced" JSPI usage like for fibers and multi-stack reentrancy? It seems that these use cases all boil down to some version of green threads. Will "plain" JSPI usage continue to not need this pass?

Would it simplify things at all if we can assume that there is only a single, blessed JSPI suspension import? All other "suspending" imports could simply take the returned promise as an externref and then pass it to the single suspend import to do the actual suspension.

cc @sbc100.

[guybedford]

Thanks for the feedback @tlively I've updated the PR to use 4 separate hook functions instead.

Stepping back, is the idea that this would be used for "advanced" JSPI usage like for fibers and multi-stack reentrancy? It seems that these use cases all boil down to some version of green threads. Will "plain" JSPI usage continue to not need this pass?

Exactly, in particular for Cloudflare we need to support reentrant JSPI with multiple Tokio runtimes via JSPI-scoped thread locals in the same Wasm instance so that durable objects can serve multiple IO-segmented requests. So yes exactly supporting green thread primitives or otherwise via these hooks.

Would it simplify things at all if we can assume that there is only a single, blessed JSPI suspension import? All other "suspending" imports could simply take the returned promise as an externref and then pass it to the single suspend import to do the actual suspension.

It might reduce the import interface at the cost of the double call and indirection. But imports are already a short list, and the problem is exports listing is the long one that would still be required so it wouldn't really fix the whole problem I don't think.

[tlively]

JSPI-scoped thread locals

Are these expected to literally be thread_local variables, or accessed via some new API? The former would require leaning all the way into each async task being modeled as a separate pthread, I think. That would be an interesting direction, but would require a significant amount of up-front design. For example, how would that interact with normal worker-backed threads? What changes would be necessary to support inter-task synchronization via mutexes and similar on the same browser thread?

[guybedford]

No plans to literally remap all thread locals. I suspect we'd want to introduce a new Rust macro utility like jspi_local! that would be enabled by these hooks that would then support arbitrary JSPI boundaries. This would be very useful for library and user code.

[sbc100]

How does this relate to the co-operative threading ABI that WASI is proposing: https://github.com/WebAssembly/wasi-sdk/blob/main/CoopThreading.md. Could JSPI piggyback on this instead of creating a separate standard?