Skip to content

Latest commit

 

History

History
839 lines (612 loc) · 41.7 KB

JS.md

File metadata and controls

839 lines (612 loc) · 41.7 KB

JavaScript API

Note: This document is no longer being updated. Please see the normative documentation.

In the MVP, the only way to access WebAssembly on the Web is through an explicit JS API which is defined below. (In the future 🦄, WebAssembly may also be loaded and run directly from an HTML <script type='module'> tag—and any other Web API that loads ES6 modules via URL—as part of ES6 Module integration.)

WebAssembly JS API declaration file for TypeScript can be found here which enable autocompletion and make TypeScript compiler happy.

Traps

Whenever WebAssembly semantics specify a trap, a WebAssembly.RuntimeError object is thrown. WebAssembly code (currently) has no way to catch this exception and thus the exception will necessarily propagate to the enclosing non-WebAssembly caller (either the browser or JavaScript) where it is handled like a normal JavaScript exception.

If WebAssembly calls JavaScript via import and the JavaScript throws an exception, the exception is propagated through the WebAssembly activation to the enclosing caller.

Because JavaScript exceptions can be handled, and JavaScript can continue to call WebAssembly exports after a trap has been handled, traps do not, in general, prevent future execution.

Stack Overflow

Whenever a stack overflow is happening in WebAssembly code, the same exception is thrown as for a stack overflow in JavaScript.

Out of Memory

Whenever validation, compilation or instantiation run out of memory, the same exception is thrown as for out of memory conditions in JavaScript.

The WebAssembly object

The WebAssembly object is the initial value of the WebAssembly property of the global object. Like the Math and JSON objects, the WebAssembly object is a plain JS object (not a constructor or function) that acts like a namespace and has the following properties:

WebAssembly [ @@toStringTag ] Property

The initial value of the @@toStringTag property is the String value "WebAssembly".

This property has the attributes { [[Writable]]: false, [[Enumerable]]: false, [[Configurable]]: true }.

Constructor Properties of the WebAssembly object

The following intrinsic objects are added:

Function Properties of the WebAssembly object

WebAssembly.validate

The validate function has the signature:

Boolean validate(BufferSource bytes)

If the given bytes argument is not a BufferSource, then a TypeError is thrown.

Otherwise, this function performs validation as defined by the WebAssembly specification and returns true if validation succeeded, false if validation failed.

WebAssembly.compile

The compile function has the signature:

Promise<WebAssembly.Module> compile(BufferSource bytes)

If the given bytes argument is not a BufferSource, the returned Promise is rejected with a TypeError.

Otherwise, this function starts an asynchronous task to compile a WebAssembly.Module as described in the WebAssembly.Module constructor. On success, the Promise is fulfilled with the resulting WebAssembly.Module object. On failure, the Promise is rejected with a WebAssembly.CompileError.

The asynchronous compilation is logically performed on a copy of the state of the given BufferSource captured during the call to compile; subsequent mutations of the BufferSource after compile return do not affect ongoing compilations.

WebAssembly.instantiate

The instantiate function is overloaded based on types of its arguments. If neither of the following overloads match, then the returned Promise is rejected with a TypeError.

dictionary WebAssemblyInstantiatedSource {
   required WebAssembly.Module module;
   required WebAssembly.Instance instance;
};

Promise<WebAssemblyInstantiatedSource>
  instantiate(BufferSource bytes [, importObject])

If the given bytes argument is not a BufferSource, the returned Promise is rejected with a TypeError.

This function starts an asynchronous task that first compiles a WebAssembly.Module from bytes as described in the WebAssembly.Module constructor and then queue a task to instantiate the resulting Module with importObject as described in the WebAssembly.Instance constructor. After the instantiation task runs and before any subsequent steps are taken, other unspecified asynchronous tasks may be run. On success, the Promise is fulfilled with a plain JavaScript object pair {module, instance} containing the resulting WebAssembly.Module and WebAssembly.Instance. The 2 properties module and instance of the returned pair are configurable, enumerable and writable.

On failure, the Promise is rejected with a WebAssembly.CompileError, WebAssembly.LinkError, or WebAssembly.RuntimeError, depending on the cause of failure.

The asynchronous compilation is logically performed on a copy of the state of the given BufferSource captured during the call to instantiate; subsequent mutations of the BufferSource after instantiate return do not affect ongoing compilations.

Promise<WebAssembly.Instance> instantiate(moduleObject [, importObject])

This description applies if the first argument is a WebAssembly.Module instance.

This function asynchronously queues a task that instantiates a WebAssembly.Instance from moduleObject and importObject as described in the WebAssembly.Instance constructor. After the instantiation task runs and before any subsequent steps are taken, other unspecified asynchronous tasks may be run. On success, the Promise is fulfilled with the resulting WebAssembly.Instance object. On failure, the Promise is rejected with a WebAssembly.CompileError, WebAssembly.LinkError, or WebAssembly.RuntimeError, depending on the cause of failure.

WebAssembly.Module Objects

A WebAssembly.Module object represents the stateless result of compiling a WebAssembly binary-format module and contains one internal slot:

  • [[Module]] : an Ast.module which is the spec definition of a module

WebAssembly.Module Constructor

The WebAssembly.Module constructor has the signature:

new Module(BufferSource bytes)

If the NewTarget is undefined, a TypeError exception is thrown (i.e., this constructor cannot be called as a function without new).

If the given bytes argument is not a BufferSource, a TypeError exception is thrown.

Otherwise, this function performs synchronous compilation of the BufferSource:

  1. The byte range delimited by the BufferSource is first logically decoded according to BinaryEncoding.md and then validated according to the rules in spec/valid.ml.
  2. The spec string values inside Ast.module are decoded as UTF8 as described in Web.md.
  3. On success, a new WebAssembly.Module object is returned with [[Module]] set to the validated Ast.module.
  4. On failure, a new WebAssembly.CompileError is thrown.

WebAssembly.Module.prototype [ @@toStringTag ] Property

The initial value of the @@toStringTag property is the String value "WebAssembly.Module".

This property has the attributes { [[Writable]]: false, [[Enumerable]]: false, [[Configurable]]: true }.

WebAssembly.Module.exports

The exports function has the signature:

Array exports(moduleObject)

If moduleObject is not a WebAssembly.Module, a TypeError is thrown.

This function returns a new Array every time it is called. Each such Array is produced by mapping each Ast.export e of moduleObject.[[Module]].exports to the Object { name: String(e.name), kind: e.ekind } where e.name is decoded as UTF8 and e.ekind is mapped to one of the String values "function", "table", "memory", "global".

Note: other fields like signature may be added in the future.

The returned Array is populated in the same order exports appear in the WebAssembly binary's exports table.

WebAssembly.Module.imports

The imports function has the signature:

Array imports(moduleObject)

If moduleObject is not a WebAssembly.Module, a TypeError is thrown.

This function returns a new Array every time it is called. Each such Array is produced by mapping each Ast.import i of moduleObject.[[Module]].imports to the Object { module: String(i.module_name), name: String(i.item_name), kind: i.ikind } where i.module_name and i.item_name are decoded as UTF8 and i.ikind is mapped to one of the String values "function", "table", "memory", "global".

Note: other fields like signature may be added in the future.

The returned Array is populated in the same order imports appear in the WebAssembly binary's imports table.

WebAssembly.Module.customSections

The customSections function has the signature:

Array customSections(moduleObject, sectionName)

If moduleObject is not a WebAssembly.Module, a TypeError is thrown.

Let sectionNameString be the result of ToString(sectionName).

This function returns a new Array every time it is called. Each such Array is produced by mapping each custom section (i.e., section with id 0) whose name field (decoded as UTF-8) is equal to sectionNameString to an ArrayBuffer containing a copy of the section's payload_data. (Note: payload_data does not include name or name_len.).

The Array is populated in the same order custom sections appear in the WebAssembly binary.

Structured Clone of a WebAssembly.Module

A WebAssembly.Module is a cloneable object which means it can be cloned between windows/workers and also stored/retrieved into/from an IDBObjectStore. The semantics of a structured clone is as-if the binary source, from which the WebAssembly.Module was compiled, were cloned and recompiled into the target realm. Engines should attempt to share/reuse internal compiled code when performing a structured clone although, in corner cases like CPU upgrade or browser update, this may not be possible and full recompilation may be necessary.

Given the above engine optimizations, structured cloning provides developers explicit control over both compiled-code caching and cross-window/worker code sharing.

WebAssembly.Instance Objects

A WebAssembly.Instance object represents the instantiation of a WebAssembly.Module into a realm and has one internal slot:

  • [[Instance]] : an Instance.instance which is the WebAssembly spec definition of an instance
  • [[Exports]] : the exports object created during instantiation

WebAssembly.Instance Constructor

The WebAssembly.Instance constructor has the signature:

new Instance(moduleObject [, importObject])

If the NewTarget is undefined, a TypeError exception is thrown (i.e., this constructor cannot be called as a function without new).

If moduleObject is not a WebAssembly.Module, a TypeError is thrown.

Let module be the Ast.module moduleObject.[[Module]].

If the importObject parameter is not undefined and Type(importObject) is not Object, a TypeError is thrown. If the list of module.imports is not empty and Type(importObject) is not Object, a TypeError is thrown.

Note: Imported JavaScript functions are wrapped as host function values in the following algorithm. For the purpose of the algorithm, a new host function value is always generated fresh and considered distinct from any other previously created host function value, including those wrapping the same JavaScript function object. Consequently, two closure values are considered equal if and only if:

  • Either they are both WebAssembly functions for the same instance and referring to the same function definition.
  • Or they are the same host function value.

Let funcs, memories and tables be initially-empty lists of callable JavaScript objects, WebAssembly.Memory objects and WebAssembly.Table objects, respectively.

Let imports be an initially-empty list of external values.

For each import i in module.imports:

  1. Let o be the resultant value of performing Get(importObject, i.module_name).
  2. If Type(o) is not Object, throw a TypeError.
  3. Let v be the value of performing Get(o, i.item_name)
  4. If i is a function import:
    1. If IsCallable(v) is false, throw a WebAssembly.LinkError.
    2. If v is an Exported Function Exotic Object:
      1. (The signature of v.[[Closure]] is checked against the import's declared func_type by Eval.init below.)
      2. Let closure be v.[[Closure]].
    3. Otherwise:
      1. Let closure be a new host function value of the given signature and the following behavior:
      2. If the signature contains an i64 (as argument or result), the host function immediately throws a TypeError when called.
      3. Otherwise, the host function calls v with an undefined receiver and WebAssembly arguments coerced to JavaScript arguments via ToJSValue. The result is returned by coercing via ToWebAssemblyValue.
    4. Append v to funcs.
    5. Append closure to imports.
  5. If i is a global import:
    1. Assert: the global is immutable by MVP validation constraint.
    2. If the global_type of i is i64 or Type(v) is not Number, throw a WebAssembly.LinkError.
    3. Append ToWebAssemblyValue(v) to imports.
  6. If i is a memory import:
    1. If v is not a WebAssembly.Memory object, throw a WebAssembly.LinkError.
    2. (The imported Memory's length and maximum properties are checked against the import's declared memory_type by Eval.init below.)
    3. Append v to memories.
    4. Append v.[[Memory]] to imports.
  7. Otherwise (i is a table import):
    1. If v is not a WebAssembly.Table object, throw a WebAssembly.LinkError.
    2. (The imported Table's length, maximum and element properties are checked against the import's declared table_type by Eval.init below.)
    3. Append v to tables.
    4. Append v.[[Table]] to imports.
    5. For each index i of v.[[Table]]:
      1. Let e be the ithe element of v.[[Table]].
    6. If e is a closure c:
      1. Append the ith element of v.[[Values]] to funcs.

Let instance be the result of creating a new instance by calling Eval.init given module and imports. If this terminates with a Link error, throw a WebAssembly.LinkError; if it causes a trap, throw a WebAssembly.RuntimeError; all other exceptions are propagated to the caller. Among other things, this function performs the following observable steps:

  • If, after evaluating the offset initializer expression of every Data and Element Segment, any of the segments do not fit in their respective Memory or Table, throw a WebAssembly.LinkError.

  • Apply all Data and Element segments to their respective Memory or Table in the order in which they appear in the module. Segments may overlap and, if they do, the final value is the last value written in order. Note: there should be no errors possible that would cause this operation to fail partway through. After this operation completes, elements of instance are visible and callable through imported tables, even if start fails.

  • If a start is present, it is evaluated. Any errors thrown by start are propagated to the caller.

The following steps are performed before the start function executes:

  1. For each table 't' in instance.tables:
    1. If there is no element in tables whose table.[[Table]] is t:
      1. Let table be a new WebAssembly.Table object with [[Table]] set to t and [[Values]] set to a new list of the same length all whose entries are null.
      2. Append table to tables.
    2. Otherwise:
      1. Let table be the element in tables whose table.[[Table]] is t
    3. (Note: At most one WebAssembly.Table object is created for any table, so the above table is unique, even if there are multiple occurrances in the list. Moreover, if the item was an import, the original object will be found.)
    4. For each index i of t:
      1. Let c be the ith element of t
      2. If c is a closure c:
        1. If there is an Exported Function Exotic Object in funcs whose [[Closure]] equals c:
          1. Let func be that function object.
        2. (Note: At most one wrapper is created for any closure, so func is uniquely determined. Moreover, if the item was an import that is already an Exported Function Exotic Object, then the original function object will be found. For imports that are regular JS functions, a new wrapper will be created.)
        3. Otherwise:
          1. Let func be an Exported Function Exotic Object created from c.
          2. Append func to funcs.
        4. Set the ith element of table.[[Values]] to func.

(Note: The table and element function objects created by the above steps are only observable for tables that are either imported or exported.)

Let exports be a list of (string, JS value) pairs that is mapped from each external value e in instance.exports as follows:

  1. If e is a closure c:
    1. If there is an Exported Function Exotic Object func in funcs whose func.[[Closure]] equals c, then return func.
    2. (Note: At most one wrapper is created for any closure, so func is unique, even if there are multiple occurrances in the list. Moreover, if the item was an import that is already an Exported Function Exotic Object, then the original function object will be found. For imports that are regular JS functions, a new wrapper will be created.)
    3. Otherwise:
      1. Let func be an Exported Function Exotic Object created from c.
      2. Append func to funcs.
      3. Return func.
  2. If e is a global v:
    1. Assert: the global is immutable by MVP validation constraint.
    2. If v is an i64, throw a WebAssembly.LinkError.
    3. Return ToJSValue(v).
  3. If e is a memory m:
    1. If there is an element memory in memories whose memory.[[Memory]] is m, then return memory.
    2. (Note: At most one WebAssembly.Memory object is created for any memory, so the above memory is unique, even if there are multiple occurrances in the list. Moreover, if the item was an import, the original object will be found.)
    3. Otherwise:
      1. Let memory be a new WebAssembly.Memory object created via CreateMemoryObject from m.
      2. Append memory to memories.
      3. Return memory.
  4. Otherwise e must be a table t:
    1. Assert: There is an element table in tables whose table.[[Table]] is t.
    2. Return that table.

Let exportsObject be a new frozen plain JS object with [[Prototype]] set to Null and with properties defined by mapping each export in exports to an enumerable, non-writable, non-configurable data property. Note: the validity and uniqueness checks performed during module validation ensure that each property name is valid and no properties are defined twice.

Let instanceObject be a new WebAssembly.Instance object setting the internal [[Instance]] slot to instance and the [[Exports]] slot to exportsObject.

Return instanceObject.

WebAssembly.Instance.prototype [ @@toStringTag ] Property

The initial value of the @@toStringTag property is the String value "WebAssembly.Instance".

This property has the attributes { [[Writable]]: false, [[Enumerable]]: false, [[Configurable]]: true }.

WebAssembly.Instance.prototype.exports property

This is an accessor property whose [[Set]] is Undefined and whose [[Get]] accessor function performs the following steps:

Let T be the this value. If T is not a WebAssembly.Instance, a TypeError is thrown.

Return T.[[Exports]].

Exported Function Exotic Objects

A function with function index index from an Instance inst is reflected to JS via a new kind of Exported Function Exotic Object. Like Bound Function Exotic Object, Exported Functions do not have the normal function internal slots but instead have:

  • [[Closure]] : the closure (index, inst)

as well as the internal slots required of all builtin functions:

Exported Functions also have the following data properties:

  • the length property is set to the exported function's signature's arity
  • the name is set to ToString(index)

WebAssembly Exported Functions have a [[Call]](this, argValues) method defined as:

  1. Let sig be the function type of the function's [[Closure]].
  2. If sig contains an i64 (as argument or result), a TypeError is thrown each time the [[Call]] method is invoked.
  3. Let args be an empty list of coerced values.
  4. Let inArity be the number of arguments and outArity be the number of results in sig.
  5. For all values v in argValues, in the order of their appearance:
  6. If the length ofargs is less than inArity, append ToWebAssemblyValue(v) to args.
  7. While the length of args is less than inArity, append ToWebAssemblyValue(undefined) to args.
  8. Let ret be the result of calling Eval.invoke passing [[Closure]], and args.
  9. If outArity is 0, return undefined.
  10. Otherwise, return ToJSValue(v), where v is the singular element of ret.

[[Call]](this, argValues) executes in the [[Realm]] of the callee Exported Function. This corresponds to the requirements of builtin function objects in JavaScript.

Exported Functions do not have a [[Construct]] method and thus it is not possible to call one with the new operator.

WebAssembly.Memory Objects

A WebAssembly.Memory object contains a single linear memory which can be simultaneously referenced by multiple Instance objects. Each Memory object has two internal slots:

  • [[Memory]] : a Memory.memory
  • [[BufferObject]] : the current ArrayBuffer whose [[ArrayBufferByteLength]] matches the current byte length of [[Memory]]

WebAssembly.Memory Constructor

The WebAssembly.Memory constructor has the signature:

new Memory(memoryDescriptor)

If the NewTarget is undefined, a TypeError exception is thrown (i.e., this constructor cannot be called as a function without new).

If Type(memoryDescriptor) is not Object, a TypeError is thrown.

Let initial be ToNonWrappingUint32(Get(memoryDescriptor, "initial")).

If HasProperty("maximum"), then let maximum be ToNonWrappingUint32(Get(memoryDescriptor, "maximum")). If maximum is smaller than initial, then throw a RangeError. Otherwise, let maximum be None.

Let memory be the result of calling Memory.create given arguments initial and maximum. Note that initial and maximum are specified in units of WebAssembly pages (64KiB).

Return the result of CreateMemoryObject(memory).

CreateMemoryObject

Given a Memory.memory m, to create a WebAssembly.Memory:

Let buffer be a new ArrayBuffer whose [[ArrayBufferData]] aliases m and whose [[ArrayBufferByteLength]] is set to the byte length of m.

Any attempts to detach buffer other than the detachment performed by m.grow shall throw a TypeError

Return a new WebAssembly.Memory instance with [[Memory]] set to m and [[BufferObject]] set to buffer.

WebAssembly.Memory.prototype [ @@toStringTag ] Property

The initial value of the @@toStringTag property is the String value "WebAssembly.Memory".

This property has the attributes { [[Writable]]: false, [[Enumerable]]: false, [[Configurable]]: true }.

WebAssembly.Memory.prototype.grow

The grow method has the signature:

grow(delta)

Let M be the this value. If M is not a WebAssembly.Memory, a TypeError is thrown.

Let d be ToNonWrappingUint32(delta).

Let ret be the current size of memory in pages (before resizing).

Perform Memory.grow with delta d. On failure, a RangeError is thrown.

Perform DetachArrayBuffer(M.[[BufferObject]]).

Assign to M.[[BufferObject]] a new ArrayBuffer whose [[ArrayBufferData]] aliases M.[[Memory]] and whose [[ArrayBufferByteLength]] is set to the new byte length of M.[[Memory]].

Return ret as a Number value.

WebAssembly.Memory.prototype.buffer

This is an accessor property whose [[Set]] is Undefined and whose [[Get]] accessor function performs the following steps:

If this is not a WebAssembly.Memory, a TypeError is thrown. Otherwise return M.[[BufferObject]].

WebAssembly.Table Objects

A WebAssembly.Table object contains a single table which can be simultaneously referenced by multiple Instance objects. Each Table object has two internal slots:

WebAssembly.Table Constructor

The WebAssembly.Table constructor has the signature:

new Table(tableDescriptor)

If the NewTarget is undefined, a TypeError exception is thrown (i.e., this constructor cannot be called as a function without new).

If Type(tableDescriptor) is not Object, a TypeError is thrown.

Let element be the result of calling Get(tableDescriptor, "element"). If element is not the string "anyfunc", a TypeError is thrown. (Note: this check is intended to be relaxed in the future 🦄 to allow different element types.)

Let initial be ToNonWrappingUint32(Get(tableDescriptor, "initial")).

If HasProperty("maximum"), then let maximum be ToNonWrappingUint32(Get(tableDescriptor, "maximum")). Otherwise, let maximum be None.

If maximum is not None and is smaller than initial, then throw a RangeError.

Let table be the result of calling Table.create given arguments AnyFuncType, initial and maximum.

Let values be a new empty array of initial elements, all with value null.

Return a new WebAssemby.Table instance with [[Table]] set to table and [[Values]] set to values.

WebAssembly.Table.prototype.length

This is an accessor property whose [[Set]] is Undefined and whose [[Get]] accessor function performs the following steps:

Let T be the this value. If T is not a WebAssembly.Table, a TypeError is thrown.

Return T.[[Values]].length.

WebAssembly.Table.prototype.grow

The grow method has the signature:

grow(delta)

Let T be the this value. If T is not a WebAssembly.Table, a TypeError is thrown.

Let d be ToNonWrappingUint32(delta).

Let ret be the current length of the table (before resizing).

Perform Table.grow, with delta d. On failure, a RangeError is thrown.

Return ret as a Number value.

WebAssembly.Table.prototype.get

This method has the following signature

get(index)

Let T be the this value. If T is not a WebAssembly.Table, a TypeError is thrown.

Let i be the result of ToNonWrappingUint32(index).

If i is greater or equal than the length of T.[[Values]], a RangeError is thrown.

Return T.[[Values]][i].

WebAssembly.Table.prototype.set

This method has the following signature

set(index, value)

Let T be the this value. If T is not a WebAssembly.Table, a TypeError is thrown.

If value is not an Exported Function Exotic Object or null, throw a TypeError.

Let i be the result of ToNonWrappingUint32(index).

If i is greater or equal than the length of T.[[Values]], a RangeError is thrown.

If value is null, let elem be Uninitialized; otherwise, let elem be value.[[Closure]].

Set T.[[Table]][i] to elem.

Set T.[[Values]][i] to value.

Return undefined.

WebAssembly.Table.prototype [ @@toStringTag ] Property

The initial value of the @@toStringTag property is the String value "WebAssembly.Table".

This property has the attributes { [[Writable]]: false, [[Enumerable]]: false, [[Configurable]]: true }.

ToJSValue

To coerce a WebAssembly value to a JavaScript value:

Assert: the WebAssembly value's type is not i64.

  1. given a WebAssembly i32 is interpreted as a signed integer, converted (losslessly) to an IEEE754 double and then returned as a JavaScript Number
  2. given a WebAssembly f32 (single-precision IEEE754), convert (losslessly) to a IEEE754 double, possibly canonicalize NaN, and return as a JavaScript Number
  3. given a WebAssembly f64, possibly canonicalize NaN and return as a JavaScript Number

If the WebAssembly value is optional, then given None, return JavaScript value undefined.

ToWebAssemblyValue

To coerce a JavaScript value to a given WebAssembly value type,

Assert: the target value type is not i64.

  1. coerce to i32 via ToInt32(v)
  2. coerce to f32 by first applying ToNumber(v) and then converting the resulting IEEE754 64-bit double to a 32-bit float using roundTiesToEven
  3. coerce to f64 via ToNumber(v)

If the value type is optional, then given None, the JavaScript value is ignored.

ToNonWrappingUint32

To convert a JavaScript value v to an unsigned integer in the range [0, UINT32_MAX]:

Let i be ToInteger(v).

If i is negative or greater than UINT32_MAX, RangeError is thrown.

Return i.

Sample API Usage

Given demo.was (encoded to demo.wasm):

(module
    (import "js" "import1" (func $i1))
    (import "js" "import2" (func $i2))
    (func $main (call $i1))
    (start $main)
    (func (export "f") (call $i2))
)

and the following JavaScript, run in a browser:

var importObj = {js: {
    import1: () => console.log("hello,"),
    import2: () => console.log("world!")
}};
fetch('demo.wasm').then(response =>
    response.arrayBuffer()
).then(buffer =>
    WebAssembly.instantiate(buffer, importObj)
).then(({module, instance}) =>
    instance.exports.f()
);