From 3143f6040f0c2a2e9abff9414414de415df3d1d7 Mon Sep 17 00:00:00 2001 From: Jean Christophe Beyler Date: Mon, 7 Dec 2015 18:41:19 -0800 Subject: Adding the definition of a start method that would be a top-level module statement. --- Modules.md | 56 +++++++++++++++++++++++++++++++++++++++++++------------- 1 file changed, 43 insertions(+), 13 deletions(-) (limited to 'Modules.md') diff --git a/Modules.md b/Modules.md index 7526f96..f623f55 100644 --- a/Modules.md +++ b/Modules.md @@ -8,6 +8,7 @@ is determined by the module it was loaded from. A module contains: * a set of [imports and exports](Modules.md#imports-and-exports); +* an optional start method name or index; * a section defining [linear memory](Modules.md#linear-memory-section); * a section containing [code](Modules.md#code-section); * after the MVP, sections containing [debugging/symbol information](Tooling.md) or @@ -38,9 +39,10 @@ A module defines a set of functions in its [code section](Modules.md#code-section) and can declare and name a subset of these functions to be **exports**. The meaning of exports (how and when they are called) is defined by the host environment. For example, a minimal shell -environment might only probe for and call a `_start` export when given a module -to execute. Exports are exported by name, where the name is an arbitrary byte -string of a given length. The host may need to mangle these names. +environment might only probe for and call the start function defined by the start +node of the module when given a module to execute. Exports are exported by name, +where the name is an arbitrary byte string of a given length. The host may need +to mangle these names. A module can declare a set of **imports**. An import is a tuple containing a module name, the name of an exported function to import from the named module, @@ -100,18 +102,18 @@ Any non-builtin imports from within a WebAssembly module would be treated as if they were `import` statements of an ES6 module. If an ES6 module `import`ed a WebAssembly module, the WebAssembly module's exports would be linked as if they were the exports of an ES6 module. Once parsing and linking phases -were complete, a WebAssembly module would have its `_start` function called in -place of executing the ES6 module top-level script. By default, multiple -loads of the same module URL (in the same realm) reuse the same instance. It may -be worthwhile in the future to consider extensions to allow applications to -load/compile/link a module once and instantiate multiple times (each with a -separate linear memory). +were complete, a WebAssembly module would have its start function, defined +by the start module option, called in place of executing the ES6 module +top-level script. By default, multiple loads of the same module URL (in +the same realm) reuse the same instance. It may be worthwhile in the future +to consider extensions to allow applications to load/compile/link a module +once and instantiate multiple times (each with a separate linear memory). This integration strategy should allow WebAssembly modules to be fairly -interchangeable with ES6 modules (ignoring +interchangeable with ES6 modules (ignoring [GC/Web API](FutureFeatures.md#gc/dom-integration) signature restrictions of the WebAssembly MVP) and thus it should be natural to compose a single application -from both kinds of code. This goal motivates the +from both kinds of code. This goal motivates the [semantic design](AstSemantics.md#linear-memory) of giving each WebAssembly module its own disjoint linear memory. Otherwise, if all modules shared a single linear memory (all modules with the same realm? origin? window?—even the @@ -122,6 +124,34 @@ shared `malloc` and coordinated global address ranges). Instead, the [dynamic linking future feature](DynamicLinking.md) is intended to allow *explicitly* injecting multiple modules into the same instance. +## Module start function + +If the module has a start node defined, the function it refers should be called +by the loader after the instance is initialized and before the exported functions +are called. + +* The start function must not take any arguments or return anything +* The function can also be exported +* There can only be at most one start node per module + +For example, a start node in a module will be: + +```(start $start_function)``` + +or + +```(start 0)``` + +In the first example, the environment is expected to call the function $start_function +before calling any other module function. In the second case, the environment is +expected to call the module function indexed 0. + +A module can: +* Only have at most a start node +* If a module contains a start node, the function must be defined in the module +* The start function will be called after module loading and before any call to the module + function is done + ## Linear memory section A module may contain an optional section declaring the use of linear memory @@ -142,10 +172,10 @@ WebAssembly engine to optimize `grow_memory`. The linear memory section may optionally declare that the instance's linear memory is *externally aliasable*. How linear memory is aliased is up -to the host environment (as with all module exports). The +to the host environment (as with all module exports). The [Web](Web.md#aliasing-linear-memory-from-JS) would reflect exported linear memory to JS as an `ArrayBuffer`. The MVP does not currently provide for -*importing* linear memory though this may be added +*importing* linear memory though this may be added [in the future](FutureFeatures.md#importing-linear-memory). ## Code section -- cgit v1.2.3