Expose method to allow synchronous initialization

[d3lm]

This PR exposes helpers that will allow to synchronously initialize the WASM module. The helpers are only exported when compiling for web. But we could also export them for no-modules.

What I have done is to extract some of the functionality from init() into helper functions which are now exported.

This fixes #2698.

Todos

• Add documentation
• Do we only want to expose the helpers or maybe export a single function initSync()?

Background

At StackBlitz we are building WebContainer, a Node.js runtime for the browser, and we could benefit from this addition a lot because it would allow us to lazy load WASM modules on demand. Some features are split into separate WASM modules to improve load performance and those features are often not frequently used. By exposing these helpers we could synchronously instantiate modules in a worker like this then:

import { getImports, initMemory, finalizeInit } from 'my_wasm_module.js';

const imports = getImports();

initMemory(imports[, maybe_memory]);

const bytes = "<sync_fetch_bytes>";

const module = new WebAssembly.Module(bytes);
const instance = new WebAssembly.Instance(module, imports);

const wasm = finalizeInit(instance, module);

ℹ️ The above only really works in a Web Worker but that's ok IMO as the main thread disallows sync APIs for good reasons.

What do you think @alexcrichton? Is that what you were thinking of in #2698?

[alexcrichton]

This seems reasonable enough to me, thanks for the PR! Can you add some documentation for this as well?

[d3lm]

Yep, will add some documentation.

[d3lm]

@alexcrichton Do we want to expose an initSync that wraps the internals? Or do we only want to expose those internals?

[alexcrichton]

Honestly this is so far outside my expertise I don't really have an opinion. It's not "obviously wrong" but I know very little about all the myriad embeddings that JS can be run in, so I have no idea how to gauge which is better to provide. I'm basically leaving such a judgement call to you.

[d3lm]

ℹ️ I have noticed there was two newlines at the end of the generated JS so I removed one newline.

[d3lm]

Alright, I have added an example and a guide as well for this.

I have also decided not expose the internal helpers and instead expose a new initSync to make it easier to use. Exposing the helpers itself gives more flexibility but I think it's not really needed at this point. In order to lazy load a WASM module you'd have to either fetch the bytes snychronously or take the router via a postMessage and use a SAB to block and wait for the bytes to be written into the shared memory. Sharing the same WebAssembly.Module across multiple workers wouldn't work because it can't be serialized into shared memory. For now, each worker has to compile the module again. The only thing I have added is the additional (optional) maybe_memory parameter in case it's compiled for shared memory.

[d3lm]

ℹ️ I have noticed that if a module has no imports and we don't initialize the imports with the module_name (wbg) that it will break when it tries to initialize the memory, because it gets assigned to imports.wbg.memory.

[d3lm]

ℹ️ This function gets exported to synchronously initialize the module.

[d3lm]

@alexcrichton This PR is ready for review.

[alexcrichton]

Thanks!

[d3lm]

@alexcrichton Nice! When do you think an we release this as a new version? So that the wasm-bindgen book is also updated with the example etc.

[alexcrichton]

I'll look into doing a release next week

[alexcrichton]

Ok I'm doing a publish at #2935

[d3lm]

Thanks a lot!