2.5 Modules¶
WebAssembly programs are organized into modules, which are the unit of deployment, loading, and compilation. A module collects definitions for types, functions, tables, memories, and globals. In addition, it can declare imports and exports and provide initialization in the form of data and element segments, or a start function.
Each of the vectors – and thus the entire module – may be empty.
2.5.1 Indices¶
Definitions are referenced with zero-based indices. Each class of definition has its own index space, as distinguished by the following classes.
The index space for functions, tables, memories and globals includes respective imports declared in the same module. The indices of these imports precede the indices of other definitions in the same index space.
Element indices reference element segments and data indices reference data segments.
The index space for locals is only accessible inside a function and includes the parameters of that function, which precede the local variables.
Label indices reference structured control instructions inside an instruction sequence.
Conventions¶
The meta variable \(l\) ranges over label indices.
The meta variables \(x, y\) range over indices in any of the other index spaces.
The notation \(\mathrm{idx}(A)\) denotes the set of indices from index space \(\mathit{idx}\) occurring free in \(A\). We sometimes reinterpret this set as the vector of its elements.
Note
For example, if \(\href{../syntax/instructions.html#syntax-instr}{\mathit{instr}}^\ast\) is \((\href{../syntax/instructions.html#syntax-instr-memory}{\mathsf{data.drop}}~x) (\href{../syntax/instructions.html#syntax-instr-memory}{\mathsf{memory.init}}~y)\), then \(\href{../syntax/modules.html#syntax-dataidx}{\mathrm{dataidx}}(\href{../syntax/instructions.html#syntax-instr}{\mathit{instr}}^\ast) = \{x, y\}\), or equivalently, the vector \(x~y\).
2.5.2 Types¶
The \(\href{../syntax/modules.html#syntax-module}{\mathsf{types}}\) component of a module defines a vector of function types.
All function types used in a module must be defined in this component. They are referenced by type indices.
Note
Future versions of WebAssembly may add additional forms of type definitions.
2.5.3 Functions¶
The \(\href{../syntax/modules.html#syntax-module}{\mathsf{funcs}}\) component of a module defines a vector of functions with the following structure:
The \(\href{../syntax/modules.html#syntax-func}{\mathsf{type}}\) of a function declares its signature by reference to a type defined in the module. The parameters of the function are referenced through 0-based local indices in the function’s body; they are mutable.
The \(\href{../syntax/modules.html#syntax-func}{\mathsf{locals}}\) declare a vector of mutable local variables and their types. These variables are referenced through local indices in the function’s body. The index of the first local is the smallest index not referencing a parameter.
The \(\href{../syntax/modules.html#syntax-func}{\mathsf{body}}\) is an instruction sequence that upon termination must produce a stack matching the function type’s result type.
Functions are referenced through function indices, starting with the smallest index not referencing a function import.
2.5.4 Tables¶
The \(\href{../syntax/modules.html#syntax-module}{\mathsf{tables}}\) component of a module defines a vector of tables described by their table type:
A table is a vector of opaque values of a particular reference type. The \(\href{../syntax/types.html#syntax-limits}{\mathsf{min}}\) size in the limits of the table type specifies the initial size of that table, while its \(\href{../syntax/types.html#syntax-limits}{\mathsf{max}}\), if present, restricts the size to which it can grow later.
Tables can be initialized through element segments.
Tables are referenced through table indices, starting with the smallest index not referencing a table import. Most constructs implicitly reference table index \(0\).
2.5.5 Memories¶
The \(\href{../syntax/modules.html#syntax-module}{\mathsf{mems}}\) component of a module defines a vector of linear memories (or memories for short) as described by their memory type:
A memory is a vector of raw uninterpreted bytes. The \(\href{../syntax/types.html#syntax-limits}{\mathsf{min}}\) size in the limits of the memory type specifies the initial size of that memory, while its \(\href{../syntax/types.html#syntax-limits}{\mathsf{max}}\), if present, restricts the size to which it can grow later. Both are in units of page size.
Memories can be initialized through data segments.
Memories are referenced through memory indices, starting with the smallest index not referencing a memory import. Most constructs implicitly reference memory index \(0\).
Note
In the current version of WebAssembly, at most one memory may be defined or imported in a single module, and all constructs implicitly reference this memory \(0\). This restriction may be lifted in future versions.
2.5.6 Globals¶
The \(\href{../syntax/modules.html#syntax-module}{\mathsf{globals}}\) component of a module defines a vector of global variables (or globals for short):
Each global stores a single value of the given global type. Its \(\href{../syntax/modules.html#syntax-global}{\mathsf{type}}\) also specifies whether a global is immutable or mutable. Moreover, each global is initialized with an \(\href{../syntax/modules.html#syntax-global}{\mathsf{init}}\) value given by a constant initializer expression.
Globals are referenced through global indices, starting with the smallest index not referencing a global import.
2.5.7 Element Segments¶
The initial contents of a table is uninitialized. Element segments can be used to initialize a subrange of a table from a static vector of elements.
The \(\href{../syntax/modules.html#syntax-module}{\mathsf{elems}}\) component of a module defines a vector of element segments. Each element segment defines a reference type and a corresponding list of constant element expressions.
Element segments have a mode that identifies them as either passive, active, or declarative. A passive element segment’s elements can be copied to a table using the \(\href{../syntax/instructions.html#syntax-instr-table}{\mathsf{table.init}}\) instruction. An active element segment copies its elements into a table during instantiation, as specified by a table index and a constant expression defining an offset into that table. A declarative element segment is not available at runtime but merely serves to forward-declare references that are formed in code with instructions like \(\href{../syntax/instructions.html#syntax-instr-ref}{\mathsf{ref{.}func}}\).
The \(\href{../syntax/modules.html#syntax-elem}{\mathsf{offset}}\) is given by a constant expression.
Element segments are referenced through element indices.
Note
In the current version of WebAssembly, only tables of element type \(\href{../syntax/types.html#syntax-reftype}{\mathsf{funcref}}\) can be initialized with an element segment. This limitation may be lifted in the future.
2.5.8 Data Segments¶
The initial contents of a memory are zero bytes. Data segments can be used to initialize a range of memory from a static vector of bytes.
The \(\href{../syntax/modules.html#syntax-module}{\mathsf{datas}}\) component of a module defines a vector of data segments.
Like element segments, data segments have a mode that identifies them as either passive or active. A passive data segment’s contents can be copied into a memory using the \(\href{../syntax/instructions.html#syntax-instr-memory}{\mathsf{memory.init}}\) instruction. An active data segment copies its contents into a memory during instantiation, as specified by a memory index and a constant expression defining an offset into that memory.
Data segments are referenced through data indices.
Note
In the current version of WebAssembly, at most one memory is allowed in a module. Consequently, the only valid \(\href{../syntax/modules.html#syntax-memidx}{\mathit{memidx}}\) is \(0\).
2.5.9 Start Function¶
The \(\href{../syntax/modules.html#syntax-module}{\mathsf{start}}\) component of a module declares the function index of a start function that is automatically invoked when the module is instantiated, after tables and memories have been initialized.
Note
The start function is intended for initializing the state of a module. The module and its exports are not accessible before this initialization has completed.
2.5.10 Exports¶
The \(\href{../syntax/modules.html#syntax-module}{\mathsf{exports}}\) component of a module defines a set of exports that become accessible to the host environment once the module has been instantiated.
Each export is labeled by a unique name. Exportable definitions are functions, tables, memories, and globals, which are referenced through a respective descriptor.
Conventions¶
The following auxiliary notation is defined for sequences of exports, filtering out indices of a specific kind in an order-preserving fashion:
\(\href{../syntax/modules.html#syntax-exportdesc}{\mathrm{funcs}}(\href{../syntax/modules.html#syntax-export}{\mathit{export}}^\ast) = [\href{../syntax/modules.html#syntax-funcidx}{\mathit{funcidx}} ~|~ \href{../syntax/modules.html#syntax-exportdesc}{\mathsf{func}}~\href{../syntax/modules.html#syntax-funcidx}{\mathit{funcidx}} \in (\href{../syntax/modules.html#syntax-export}{\mathit{export}}.\href{../syntax/modules.html#syntax-export}{\mathsf{desc}})^\ast]\)
\(\href{../syntax/modules.html#syntax-exportdesc}{\mathrm{tables}}(\href{../syntax/modules.html#syntax-export}{\mathit{export}}^\ast) = [\href{../syntax/modules.html#syntax-tableidx}{\mathit{tableidx}} ~|~ \href{../syntax/modules.html#syntax-exportdesc}{\mathsf{table}}~\href{../syntax/modules.html#syntax-tableidx}{\mathit{tableidx}} \in (\href{../syntax/modules.html#syntax-export}{\mathit{export}}.\href{../syntax/modules.html#syntax-export}{\mathsf{desc}})^\ast]\)
\(\href{../syntax/modules.html#syntax-exportdesc}{\mathrm{mems}}(\href{../syntax/modules.html#syntax-export}{\mathit{export}}^\ast) = [\href{../syntax/modules.html#syntax-memidx}{\mathit{memidx}} ~|~ \href{../syntax/modules.html#syntax-exportdesc}{\mathsf{mem}}~\href{../syntax/modules.html#syntax-memidx}{\mathit{memidx}} \in (\href{../syntax/modules.html#syntax-export}{\mathit{export}}.\href{../syntax/modules.html#syntax-export}{\mathsf{desc}})^\ast]\)
\(\href{../syntax/modules.html#syntax-exportdesc}{\mathrm{globals}}(\href{../syntax/modules.html#syntax-export}{\mathit{export}}^\ast) = [\href{../syntax/modules.html#syntax-globalidx}{\mathit{globalidx}} ~|~ \href{../syntax/modules.html#syntax-exportdesc}{\mathsf{global}}~\href{../syntax/modules.html#syntax-globalidx}{\mathit{globalidx}} \in (\href{../syntax/modules.html#syntax-export}{\mathit{export}}.\href{../syntax/modules.html#syntax-export}{\mathsf{desc}})^\ast]\)
2.5.11 Imports¶
The \(\href{../syntax/modules.html#syntax-module}{\mathsf{imports}}\) component of a module defines a set of imports that are required for instantiation.
Each import is labeled by a two-level name space, consisting of a \(\href{../syntax/modules.html#syntax-import}{\mathsf{module}}\) name and a \(\href{../syntax/modules.html#syntax-import}{\mathsf{name}}\) for an entity within that module. Importable definitions are functions, tables, memories, and globals. Each import is specified by a descriptor with a respective type that a definition provided during instantiation is required to match.
Every import defines an index in the respective index space. In each index space, the indices of imports go before the first index of any definition contained in the module itself.
Note
Unlike export names, import names are not necessarily unique. It is possible to import the same \(\href{../syntax/modules.html#syntax-import}{\mathsf{module}}\)/\(\href{../syntax/modules.html#syntax-import}{\mathsf{name}}\) pair multiple times; such imports may even have different type descriptions, including different kinds of entities. A module with such imports can still be instantiated depending on the specifics of how an embedder allows resolving and supplying imports. However, embedders are not required to support such overloading, and a WebAssembly module itself cannot implement an overloaded name.