wasi: improve JavaScript API

[cjihrig]

• Add WASI.start(). This calls _start() or __wasi_unstable_reactor_start(), if present.
• Export a valid wasi_unstable import. This can be included as part of an imports object passed to WebAssembly.instantiate(), etc.

Checklist

• make -j4 test (UNIX), or vcbuild test (Windows) passes
• tests and/or benchmarks are included
• documentation is changed or added
• commit message follows commit guidelines

[guybedford]

What happens if instance.memory !== options.memory passed to new WASI? Should this be considered an API hazard?

[cjihrig]

Since start() is a static method, I don't think that should matter, right?

[guybedford]

Right I see, but then should there be some memory binding in this method instead?

[cjihrig]

So, I'm assuming that WASI.start() is not the same thing as the API being discussed in #3. I'm thinking of WASI.start() as more of a building block API, and #3 as a higher level API.

With that assumption, consider the following example:

'use strict';
const fs = require('fs');
const { WASI } = require('wasi');
const pathname = '/path/to/something.wasm';
const buffer = fs.readFileSync(pathname);
const memory = new WebAssembly.Memory({ initial: 1 });
const wasi = new WASI({ args: [], env: process.env, memory });

(async () => {
  const compiled = await WebAssembly.compile(buffer);
  const importObject = { wasi_unstable: wasi.wasiImport };
  const instance = await WebAssembly.instantiate(compiled, importObject);

  WASI.start(instance);
})();

In this case, WASI.start() just attempts to call the _start() or __wasi_unstable_reactor_start() export if one exists. By this point, instance should have everything bound properly, or WebAssembly.instantiate() will fail.

[guybedford]

I see. For commands that export their memories, a memory injection API would still likely be needed though.

[cjihrig]

Agreed. I plan to have a WASI.prototype.setMemory() (or something along those lines) eventually.

[benjamingr]

If setMemory can take a SharedArrayBuffer that could be awesome (although I am not sure if that is allowed)

[cjihrig]

I just pushed up 2b0131c to this PR. It allows the memory passed to the WASI constructor to be a SharedArrayBuffer (or any other ArrayBuffer). Once setMemory() is added, it will also support SABs.

[benjamingr]

This is really cool and useful thanks :]