This is a mirror of the wiki at pascal.chat. Editing, history and sign-in are there.

WebAssembly/JS-Promise Integration

The WebAssembly JavaScript-Promise Integration Proposal is a proposed extension to the browser JavaScript API: 1 It allows calling asynchronous JavaScript functions from WebAssembly code as if they are synchronous, as well as calling WebAssembly functions asynchronously from JavaScript, even though they are implemented as synchronous.

Browser support

There is currently experimental support implemented in Chrome, Chromium and Edge. So far, browser support is only implemented on the x86_64 and aarch64 platforms. Minimum Chrome versions that support it are 110.0.5473.0 (macOS) / 110.0.5469.0 (Windows, Android) / 110.0.5478.4 (Linux). As an experimental feature, it is disabled by default. To enable it, go to the URL:

text

chrome://flags

Search for "Experimental WebAssembly JavaScript Promise Integration (JSPI)". Click on the box, select "enable", then restart the browser to enable the feature.

Free Pascal support

Free Pascal support for this extension was merged into the main FPC branch on Jun 26 2023.

Free Pascal language extensions

Suspending externals

Suspending externals allows calling JavaScript functions that are run asynchronously on the JavaScript side, even though they are called as if they are synchronous on the WebAssembly side. Example:

pascal

function compute_delta: double; external 'js' suspending;

Or:

pascal

function compute_delta: double; external 'js' suspending first;

Now we can implement this function asynchronously on the JavaScript side:

pascal

var compute_delta = () => 
  fetch('https://example.com/data.txt')
    .then(res => res.text())
    .then(txt => parseFloat(txt));

We then prepare the asynchronous function for use as a suspending WebAssembly external, like this:

pascal

var suspending_compute_delta = new WebAssembly.Function(
  {parameters:[externref],results:['f64']},
  compute_delta,
  {suspending:"first"}
)

We can the use this to form the complete import object:

pascal

var importObj = {js: {
    compute_delta:suspending_compute_delta}};

Note the extra externref parameter, as well as the extra attribute {suspending:"first"}. The extra externref parameter is automatically added, when a function is declared 'suspending'. It contains a special suspender object that is used internally by the WebAssembly JavaScript Promise Integration extension. For more details, see the spec. Free Pascal automatically adds the suspender as an extra first parameter for functions that are declared external suspending. There's also an option to add it as a last parameter. In this case, the declaration in Free Pascal needs to be changed to:

pascal

function compute_delta: double; external 'js' suspending last;

And on the JavaScript side, the value of the suspending attribute needs to be changed to: {suspending:"last"}.

Promising exports

In order for calls to suspending functions to work, WebAssembly code execution must be entered via an export, marked as 'promising'. Example:

pascal

var
  state: double;

function update_state: double;
begin
  state := state + compute_delta;  // this calls the suspending function 'compute_delta'
  update_state := state;
end;

exports
  update_state promising;

Once again, a promising export has an extra externref parameter automatically added. Here's how it can be wrapper correctly on the JavaScript side:

pascal

var sampleModule = WebAssembly.instantiate(demoBuffer,importObj);
var update_state = new WebAssembly.function(
  {parameters:[], results:['externref']},
  sampleModule.exports.update_state_export,
  {promising : "first"})

Alternatively, you can use promising last. If you export it like this in Pascal:

text

exports
  update_state promising last;

Then you can use {promising : "last"} instead of {promising : "first"} in JavaScript.

WebAssembly/JS-Promise Integration

Browser support

Free Pascal support

Free Pascal language extensions

Suspending externals

Promising exports

See Also