Embedding¶
A WebAssembly implementation will typically be embedded into a host environment. An embedder implements the connection between such a host environment and the WebAssembly semantics as defined in the main body of this specification. An embedder is expected to interact with the semantics in well-defined ways.
This section defines a suitable interface to the WebAssembly semantics in the form of entry points through which an embedder can access it. The interface is intended to be complete, in the sense that an embedder does not need to reference other functional parts of the WebAssembly specification directly.
Note
On the other hand, an embedder does not need to provide the host environment with access to all functionality defined in this interface. For example, an implementation may not support parsing of the text format.
Types¶
In the description of the embedder interface, syntactic classes from the abstract syntax and the runtime’s abstract machine are used as names for variables that range over the possible objects from that class. Hence, these syntactic classes can also be interpreted as types.
For numeric parameters, notation like
Errors¶
Failure of an interface operation is indicated by an auxiliary syntactic class:
In addition to the error conditions specified explicitly in this section, implementations may also return errors when specific implementation limitations are reached.
Note
Errors are abstract and unspecific with this definition. Implementations can refine it to carry suitable classifications and diagnostic messages.
Pre- and Post-Conditions¶
Some operations state pre-conditions about their arguments or post-conditions about their results. It is the embedder’s responsibility to meet the pre-conditions. If it does, the post conditions are guaranteed by the semantics.
In addition to pre- and post-conditions explicitly stated with each operation, the specification adopts the following conventions for runtime objects (
Every runtime object passed as a parameter must be valid per an implicit pre-condition.
Every runtime object returned as a result is valid per an implicit post-condition.
Note
As long as an embedder treats runtime objects as abstract and only creates and manipulates them through the interface defined here, all implicit pre-conditions are automatically met.
Store¶
¶
Return the empty store.
Modules¶
¶
If there exists a derivation for the byte sequence
as a according to the binary grammar for modules, yielding a module , then return .Else, return
.
¶
If there exists a derivation for the source
as a according to the text grammar for modules, yielding a module , then return .Else, return
.
¶
If
is valid, then return nothing.Else, return
.
¶
Try instantiating
in with external values as imports:
If it succeeds with a module instance
, then let be . Else, let
be .
Return the new store paired with
.
Note
The store may be modified even in case of an error.
¶
Pre-condition:
is valid with external import types and external export types .Let
be the imports .Assert: the length of
equals the length of .For each
in and corresponding in , do:
Let
be the triple .
Return the concatenation of all
, in index order.Post-condition: each
is valid.
¶
Pre-condition:
is valid with external import types and external export types .Let
be the exports .Assert: the length of
equals the length of .For each
in and corresponding in , do:
Let
be the pair .
Return the concatenation of all
, in index order.Post-condition: each
is valid.
Module Instances¶
¶
Assert: due to validity of the module instance
, all its export names are different.If there exists an
in such that name equals , then:Return the external value
.
Else, return
.
Functions¶
¶
Pre-condition:
is valid.Let
be the result of allocating a host function in with function type and host function code .Return the new store paired with
.
Note
This operation assumes that
Regular (non-host) function instances can only be created indirectly through module instantiation.
¶
Return
.Post-condition: the returned function type is valid.
¶
If it succeeds with values
as results, then let be . Else it has trapped, hence let
be .
Return the new store paired with
.
Note
The store may be modified even in case of an error.
Tables¶
¶
Pre-condition:
is valid.Let
be the result of allocating a table in with table type and initialization value .Return the new store paired with
.
¶
Return
.Post-condition: the returned table type is valid.
¶
Let
be the table instance .If
is larger than or equal to the length of , then return .Else, return the reference value
.
¶
Let
be the table instance .If
is larger than or equal to the length of , then return .Replace
with the reference value .Return the updated store.
¶
Return the length of
.
¶
Try growing the table instance
by elements with initialization value :If it succeeds, return the updated store.
Else, return
.
Memories¶
¶
Pre-condition:
is valid.Let
be the result of allocating a memory in with memory type .Return the new store paired with
.
¶
Return
.Post-condition: the returned memory type is valid.
¶
Let
be the memory instance .If
is larger than or equal to the length of , then return .Else, return the byte
.
¶
Let
be the memory instance .If
is larger than or equal to the length of , then return .Replace
with .Return the updated store.
¶
Return the length of
divided by the page size.
¶
Try growing the memory instance
by pages:If it succeeds, return the updated store.
Else, return
.
Globals¶
¶
Pre-condition:
is valid.Let
be the result of allocating a global in with global type and initialization value .Return the new store paired with
.
¶
Return
.Post-condition: the returned global type is valid.
¶
Let
be the global instance .Return the value
.
¶
Let
be the global instance .Let
be the structure of the global type .If
is not , then return .Replace
with the value .Return the updated store.