Supercharge WebAssembly with JavaScript Promises: A Deep Dive into JSPI

Are you struggling to integrate your synchronous WebAssembly applications with the asynchronous world of modern web APIs? The JavaScript Promise Integration (JSPI) API offers a powerful solution. This article explores JSPI's core capabilities, how to use it, and real-world examples to help you bridge the gap between synchronous and asynchronous JavaScript environments.

What is JSPI and Why Should You Care?

JSPI acts as a translator between synchronous WebAssembly code and asynchronous Web APIs. It suspends the WebAssembly application when it makes a synchronous API call and seamlessly resumes it once the asynchronous operation completes. This innovative approach allows you to leverage modern web functionalities with minimal changes to your existing WebAssembly codebase.

• Seamless Integration: Bridges synchronous WebAssembly with asynchronous JavaScript APIs.
• Minimal Changes: Requires very few modifications to your existing WebAssembly applications.
• Modern Web Compatibility: Enables WebAssembly to interact smoothly with modern, asynchronous web functionalities.

How JSPI Works: Bridging the Asynchronous Divide

JSPI intercepts Promises returned from asynchronous API calls. It suspends the WebAssembly application's main logic and returns a Promise from the export used to enter WebAssembly. When the asynchronous API completes, the WebAssembly application resumes, ready to process the results.

This is achieved through wrapping imports and exports during WebAssembly module instantiation. Function wrappers add the suspending behavior to asynchronous imports and route suspensions to Promise callbacks.

• Promise Interception: Catches Promises from asynchronous API calls.
• Suspension & Resumption: Pauses and restarts WebAssembly execution transparently.
• Function Wrappers: Adds suspending behavior to imports and manages Promise callbacks.

Performance Expectations: Minimal Overhead

JSPI's suspend and resume mechanisms operate in constant time, minimizing performance overhead. Propagating Promises and resuming WebAssembly execution introduce minimal delay, so you can unlock asynchronous web functionalities without sacrificing speed.

• Constant-Time Operations: Suspending and resuming WebAssembly modules are highly efficient.
• Minimal Overhead: Introduces minimal performance impact compared to other transformation approaches.
• Event Loop Dependency: Relies on the browser's event loop for waking up suspended WebAssembly applications.

Using JSPI Today: Experimentation and Setup

JSPI is currently experimental but available for testing on Intel x64 and ARM 64 architectures across Linux, macOS, Windows, and ChromeOS. To enable it locally, navigate to chrome://flags in Chrome, search for "Experimental WebAssembly JavaScript Promise Integration (JSPI)," and enable the flag.

You'll need Chrome version 110.0.5473.0 (macOS), 110.0.5469.0 (Windows, Android), or 110.0.5478.4 (Linux). For Emscripten users, version 3.1.28 or later is recommended.

• Enable via Chrome Flags: Activate the experimental feature in your Chrome browser.
• Minimum Version Requirements: Ensure you're using a compatible Chrome and Emscripten version.
• Experimental Status: Not for production use, but ideal for testing and exploration.

Limitations to Keep in Mind

While promising, JSPI has a few limitations in its current experimental phase:

• Architecture Support: Limited to x64 and arm64 architectures.
• Import/Export Restrictions: Only supports JS-to-Wasm exports and Wasm-to-JS imports.
• Fixed Stack Size: Each JSPI call runs on a separate stack with a fixed size. You can adjust the default size using the --wasm-stack-switching-stack-size flag.
• Debugging Limitations: Debugging support is minimal, but enhanced support is planned.

Demo: Calculating Fibonacci with JavaScript Promises

Let's explore a simple example: calculating Fibonacci numbers using JavaScript Promises for addition within a C program.

long promiseFib(long x) {
 if (x == 0)
 return 0;
 if (x == 1)
 return 1;
 return promiseAdd(promiseFib(x - 1), promiseFib(x - 2));
}
// promise an addition
EM_ASYNC_JS(long, promiseAdd, (long x, long y), {
 return Promise.resolve(x+y);
});

This code uses the EM_ASYNC_JS macro to define promiseAdd as a JavaScript function within the C program. Since standard JavaScript addition doesn't involve Promises, we force it using Promise.resolve(). The EM_ASYNC_JS macro handles the glue code, enabling JSPI to access the Promise's result as a normal function.

Compile this with:

emcc -O3 badfib.c -o b.html -s ASYNCIFY=2

The -s ASYNCIFY=2 flag is crucial, instructing Emscripten to generate code utilizing JSPI for JavaScript imports that return Promises.

Lazy Code Loading with JSPI: A Surprising Application

JSPI can also dynamically load code. Imagine fetching a module with needed code but delaying the load until the function is first called.

// This is a simple provider of forty-two
#include <stdio.h>

EMSCRIPTEN_KEEPALIVE long provide42(){
    return 42l;
}

Compile this with:

emcc p42.c -o p42.wasm --no-entry -Wl,--import-memory

The -Wl,--import-memory flag ensures the dynamically loaded module accesses the main module's memory.

Conclusion: Embracing the Future of WebAssembly

JSPI is a significant step toward bridging the gap between synchronous WebAssembly and asynchronous JavaScript. While still experimental, it opens exciting possibilities for leveraging modern web APIs within your WebAssembly applications. By enabling seamless integration and minimal performance overhead, JSPI promises to unlock a new era of WebAssembly development.

Join the discussion and contribute to the future of JSPI at the W3C WebAssembly Community Group repo.