WebAssembly Web API

This document builds off of the WebAssembly specification [WEBASSEMBLY] and the WebAssembly JavaScript embedding [WASMJS].

1. Streaming Module Compilation and Instantiation

partial namespace WebAssembly {
  Promise<Module> compileStreaming(Promise<Response> source);
  Promise<WebAssemblyInstantiatedSource> instantiateStreaming(
      Promise<Response> source, optional object importObject);
};

2. Serialization

Web user agents must augment the Module interface with the [Serializable] extended attribute.

The serialization steps, given value, serialized, and forStorage, are:

1. If forStorage is true, throw a "DataCloneError" DOMException

2. Set serialized.[[Bytes]] to the sub-serialization of value.[[Bytes]].

3. Set serialized.[[AgentCluster]] to the current Realm's corresponding agent cluster.

The deserialization steps, given serialized and value, are:

1. Let bytes be the sub-deserialization of serialized.[[Bytes]].

2. Set value.[[Bytes]] to bytes.

3. If targetRealm’s corresponding agent cluster is not serialized.[[AgentCluster]], then throw a "DataCloneError" DOMException.

4. Compile a WebAssembly module from bytes and set value.[[Module]] to the result.

Engines should attempt to share/reuse internal compiled code when performing a structured serialization, although in corner cases like CPU upgrade or browser update, this might not be possible and full recompilation may be necessary.

Note: The semantics of a structured serialization is as-if the binary source, from which the Module was compiled, is serialized, then deserialized, and recompiled into the target realm. Given the above engine optimizations, structured serialization provides developers explicit control over both compiled-code caching and cross-window/worker code sharing.

3. Developer-Facing Display Conventions

This section is non-normative.

Browsers, JavaScript engines, and offline tools have common ways of referring to JavaScript artifacts and language constructs. For example, locations in JavaScript source code are printed in stack traces or error messages, and are represented naturally as decimal-format lines and columns in text files. Names of functions and variables are taken directly from the sources. Therefore (for example) even though the exact format of implementation-dependent stack trace strings does not always match, the locations are easily understandable and the same across browsers.

To achieve the same goal of a common representations for WebAssembly constructs, the following conventions are adopted.

A WebAssembly location is a reference to a particular instruction in the binary, and may be displayed by a browser or engine in similar contexts as JavaScript source locations. It has the following format:

${url}:wasm-function[${funcIndex}]:${pcOffset}

Where

• ${url} is the URL associated with the module, if applicable (see notes).

• ${funcIndex} is the function index relative to the module.

• ${pcOffset} is the offset in the module binary of the first byte of the instruction, printed in hexadecimal with lower-case digits, with a leading 0x prefix.

Notes:

• The URL field may be interpreted differently depending on the context. When the response-based instantiation API is used in a browser, the associated URL should be used; or when the ArrayBuffer-based instantiation API is used, the browser should represent the location of the API call. This kind of instantiation is analogous to executing JavaScript using eval; therefore if the browser has an existing method to represent the location of the eval call it can use a similar one for WebAssembly.instantiate. For example if the browser uses foo.js line 10 > eval or eval at bar (foo.js:10:3) for eval, it could use foo.js line 10 > WebAssembly.instantiate or WebAssembly.instantiate at bar (foo.js:10:3), respectively. Offline tools may use a filename instead.

• Using hexadecimal for module offsets matches common conventions in native tools such as objdump (where addresses are printed in hex) and makes them visually distinct from JavaScript line numbers. Other numbers are represented in decimal.

While the "name" property of an Exported Function instance is specified by the JS API, synthesized function names are also displayed in other contexts like call stacks in debuggers and string representations of stack traces. If a WebAssembly module contains a name section, these names should be used to synthesize a function name as follows:

• If a function name subsection is present, the displayed name should be ${module_name}.${function_name} or ${function_name}, depending on whether the module name is present.

• Otherwise, the output can be context-dependent:

  • If the function name is shown alongside its location in a stack trace, then just the module name (if present) or an empty string can be used (because the function index is already in the location).

  • Otherwise, ${module_name}.wasm-function[${funcIndex}] or wasm-function[${funcIndex}] should be used to convey the function index.

Note that this document does not specify the full format of strings such as stack frame representations; this allows engines to continue using their existing formats for JavaScript (which existing code may already be depending on) while still printing WebAssembly frames in a format consistent with JavaScript.