[jsapi] Always queue a task during asynchronous instantiation

littledan · littledan · commit 4ad0aa23b3b4 · 2019-03-01T15:17:58.000+01:00
JSC will have to do asynchronous compilation work during some instantiations.
To be consistent, this PR always queues a task to complete instantiation,
except through the synchronous Instance(module) API, to ensure consistency
across platforms.

This patch also cleans up the specification in various surrounding ways:
- Factor out the algorithms for reading imports from the import obj, etc.
- Include notes about APIs whose use is discouraged/may be limited
diff --git a/document/js-api/index.bs b/document/js-api/index.bs
@@ -316,10 +316,8 @@ A {{Module}} object represents a single WebAssembly module. Each {{Module}} obje
     1. [=Asynchronously compile a WebAssembly module=] from |stableBytes| and return the result.
 </div>
 
-<div algorithm="instantiate">
-  To <dfn>instantiate a WebAssembly module</dfn> from a {{Module}} |moduleObject| and imports |importObject|, and optional algorithm |steps| is given |importObject| as a parameter, perform the following steps:
-    1. Let |module| be |moduleObject|.\[[Module]].
-    1. If |module|.[=𝗂𝗆𝗉𝗈𝗋𝗍𝗌=] is not an empty list, and |importObject| is undefined, throw a {{TypeError}} exception.
+<div algorithm>
+  To <dfn>read the imports</dfn> from a WebAssembly module |module| from imports object |importObject|, perform the following steps:
     1. Let |imports| be an empty [=list=] of [=external value=]s.
     1. For each (|moduleName|, |componentName|, |externtype|) in [=module_imports=](|module|), do
         1. Let |o| be ? [=Get=](|importObject|, |moduleName|).
@@ -364,59 +362,94 @@ A {{Module}} object represents a single WebAssembly module. Each {{Module}} obje
             2. Let |tableaddr| be |v|.\[[Table]]
             1. Let |externtable| be the [=external value=] [=external value|𝗍𝖺𝖻𝗅𝖾=] |tableaddr|.
             1. [=Append=] |externtable| to |imports|.
-    1. If |steps| is provided, user agents may either perform the following steps, or may perform additional work [=in parallel=] and then [=queue a task=] to perform the following steps. If |steps| is not provided, perform the following steps:
+    1. Return |imports|.
+</div>
+
+<div algorithm>
+  To <dfn>create an instance object</dfn> from a WebAssembly module |module| and instance |instance|, perform the following steps:
+    1. If |module|.[=𝗂𝗆𝗉𝗈𝗋𝗍𝗌=] is not an empty list, and |importObject| is undefined, throw a {{TypeError}} exception.
+    1. Let |exportsObject| be ! [=ObjectCreate=](null).
+    1. For each pair (|name|, |externtype|) in [=module_exports=](|module|),
+        1. Let |externval| be [=get_export=](|instance|, |name|).
+        1. Assert: |externval| is not [=error=].
+        1. If |externtype| is of the form [=𝖿𝗎𝗇𝖼=] |functype|,
+            1. Assert: |externval| is of the form [=external value|𝖿𝗎𝗇𝖼=] |funcaddr|.
+            1. Let [=external value|𝖿𝗎𝗇𝖼=] |funcaddr| be |externval|.
+            1. Let |func| be the result of creating [=a new Exported Function=] from |funcaddr|.
+            1. Let |value| be |func|.
+        1. If |externtype| is of the form [=𝗀𝗅𝗈𝖻𝖺𝗅=] <var ignore>globaltype</var>,
+            1. Assert: |externval| is of the form [=external value|𝗀𝗅𝗈𝖻𝖺𝗅=] |globaladdr|.
+            1. Let [=external value|𝗀𝗅𝗈𝖻𝖺𝗅=] |globaladdr| be |externval|.
+            1. Let |global| be [=create a global object|a new Global object=] created from |globaladdr|.
+            1. Let |value| be |global|.
+        1. If |externtype| is of the form [=𝗆𝖾𝗆=] |memtype|,
+            1. Assert: |externval| is of the form [=external value|𝗆𝖾𝗆=] |memaddr|.
+            1. Let [=external value|𝗆𝖾𝗆=] |memaddr| be |externval|.
+            1. Let |memory| be [=create a memory object|a new Memory object=] created from |memaddr|.
+            1. Let |value| be |memory|.
+        1. Otherwise, |externtype| is of the form [=𝗍𝖺𝖻𝗅𝖾=] |tabletype|,
+            1. Assert: |externval| is of the form [=external value|𝗍𝖺𝖻𝗅𝖾=] |tableaddr|.
+            1. Let [=external value|𝗍𝖺𝖻𝗅𝖾=] |tableaddr| be |externval|.
+            1. Let |table| be [=create a Table object|a new Table object=] created from |tableaddr|.
+            1. Let |value| be |table|.
+        1. Let |status| be ! [=CreateDataProperty=](|exportsObject|, |name|, |value|).
+        1. Assert: |status| is true.
+
+        Note: the validity and uniqueness checks performed during [=WebAssembly module validation=] ensure that each property name is valid and no properties are defined twice.
+    1. Perform ! [=SetIntegrityLevel=](|exportsObject|, `"frozen"`).
+    1. Return a new {{Instance}} object whose internal \[[Instance]] slot is set to |instance| and the \[[Exports]] slot to |exportsObject|.
+</div>
+
+<div algorithm>
+  To <dfn>instantate the core of a WebAssembly module</dfn> from a module |module| and imports |imports|, perform the following steps:
+
+      1. Let |store| be the [=surrounding agent=]'s [=associated store=].
       1. Let (|store|, |instance|) be [=instantiate_module=](|store|, |module|, |imports|).
       1. If |instance| is [=error=], throw an appropriate exception type:
           * A {{LinkError}} exception for most cases which occur during linking.
           * If the error came when running the start function, throw a {{RuntimeError}} for most errors which occur from WebAssembly, or the error object propagated from inner ECMAScript code.
           * Another error type if appropriate, for example an out-of-memory exception, as documented in <a href="#errors">the WebAssembly error mapping</a>.
-      1. Let |exportsObject| be ! [=ObjectCreate=](null).
-      1. For each pair (|name|, |externtype|) in [=module_exports=](|module|),
-          1. Let |externval| be [=get_export=](|instance|, |name|).
-          1. Assert: |externval| is not [=error=].
-          1. If |externtype| is of the form [=𝖿𝗎𝗇𝖼=] |functype|,
-              1. Assert: |externval| is of the form [=external value|𝖿𝗎𝗇𝖼=] |funcaddr|.
-              1. Let [=external value|𝖿𝗎𝗇𝖼=] |funcaddr| be |externval|.
-              1. Let |func| be the result of creating [=a new Exported Function=] from |funcaddr|.
-              1. Let |value| be |func|.
-          1. If |externtype| is of the form [=𝗀𝗅𝗈𝖻𝖺𝗅=] <var ignore>globaltype</var>,
-              1. Assert: |externval| is of the form [=external value|𝗀𝗅𝗈𝖻𝖺𝗅=] |globaladdr|.
-              1. Let [=external value|𝗀𝗅𝗈𝖻𝖺𝗅=] |globaladdr| be |externval|.
-              1. Let |global| be [=create a global object|a new Global object=] created from |globaladdr|.
-              1. Let |value| be |global|.
-          1. If |externtype| is of the form [=𝗆𝖾𝗆=] |memtype|,
-              1. Assert: |externval| is of the form [=external value|𝗆𝖾𝗆=] |memaddr|.
-              1. Let [=external value|𝗆𝖾𝗆=] |memaddr| be |externval|.
-              1. Let |memory| be [=create a memory object|a new Memory object=] created from |memaddr|.
-              1. Let |value| be |memory|.
-          1. Otherwise, |externtype| is of the form [=𝗍𝖺𝖻𝗅𝖾=] |tabletype|,
-              1. Assert: |externval| is of the form [=external value|𝗍𝖺𝖻𝗅𝖾=] |tableaddr|.
-              1. Let [=external value|𝗍𝖺𝖻𝗅𝖾=] |tableaddr| be |externval|.
-              1. Let |table| be [=create a Table object|a new Table object=] created from |tableaddr|.
-              1. Let |value| be |table|.
-          1. Let |status| be ! [=CreateDataProperty=](|exportsObject|, |name|, |value|).
-          1. Assert: |status| is true.
-
-          Note: the validity and uniqueness checks performed during [=WebAssembly module validation=] ensure that each property name is valid and no properties are defined twice.
-      1. Perform ! [=SetIntegrityLevel=](|exportsObject|, `"frozen"`).
-      1. Let |instanceObject| be a new {{Instance}} object whose internal \[[Instance]] slot is set to |instance| and the \[[Exports]] slot to |exportsObject|.
-    1. If |steps| is provided, perform |steps| given |instanceObject|.
-    1. Otherwise, return |instanceObject|.
+      1. Set the [=surrounding agent=]'s [=associated store=] to |store|.
+      1. Return |instance|.
+</div>
+
+<div algorithm="instantiate">
+  To <dfn>asynchronously instantiate a WebAssembly module</dfn> from a {{Module}} |moduleObject| and imports |importObject|, perform the following steps:
+    1. Let |module| be |moduleObject|.\[[Module]].
+    1. Let |promise| be [=a new promise=].
+    1. [=Read the imports=] of |module| with imports |importObject|, and let |imports| be the result. If this operation throws an exception, catch it, [=reject=]
+    1. Run the following steps [=in parallel=]:
+        Note: Implementation-specific work may be performed here.
+        1. [=Queue a task=] to perform the following steps:
+            1. [=Instantiate the core of a WebAssembly module=] |module| with |imports|, and let |instance| be the result. If this operation throws an exception, catch it, [=reject=] |promise| with the exception, and return |promise|.
+            1. [=Create an instance object=] from |module| and |instance|, and let the result be |instanceObject|. If this operation throws an exception, catch it, [=reject=] |promise| with the exception, and return |promise|.
+            1. [=Resolve=] |promise| with |instance|.
+    1. Return |promise|.
+</div>
+
+<div algorithm="instantiate">
+  To <dfn>synchronously instantiate a WebAssembly module</dfn> from a {{Module}} |moduleObject| and imports |importObject|, perform the following steps:
+    1. Let |module| be |moduleObject|.\[[Module]].
+    1. [=Read the imports=] of |module| with imports |importObject|, and let |imports| be the result.
+    1. [=Instantiate the core of a WebAssembly module=] |module| with |imports|, and let |instance| be the result.
+    1. [=Create an instance object=] from |module| and |instance|, and let the result be |instanceObject|.
+    1. Return |instanceObject|.
 </div>
 
 <div algorithm>
   To <dfn>instantiate a promise of a module</dfn> |promiseOfModule| with imports |importObject|, perform the following steps:
 
     1. Let |promise| be [=a new promise=]
     1. [=Upon fulfillment=] of |promiseOfModule| with value |module|:
-        1. [=instantiate a WebAssembly module|Instantiate the WebAssembly module=] |module| importing |importObject|, with the following steps given |instance|.  If this throws an exception, catch it, [=reject=] |promise| with the exception, and abort these substeps.
+        1. [=asynchronously instantiate a WebAssembly module|Instantiate the WebAssembly module=] |module| importing |importObject|, and let |innerPromise| be the result.
+        1. [=Upon fulfillment=] of |innerPromise| with value |instance|.
             1. Let |result| be a {{WebAssemblyInstantiatedSource}} dictionary with {{WebAssemblyInstantiatedSource/module}} set to |module| and {{WebAssemblyInstantiatedSource/instance}} set to |instance|.
             1. [=Resolve=] |promise| with |result|.
+        1. [=Upon rejection=] of |innerPromise| with reason |reason|:
+            1. [=Reject=] |promise| with |reason|.
     1. [=Upon rejection=] of |promiseOfModule| with reason |reason|:
         1. [=Reject=] |promise| with |reason|.
     1. Return |promise|.
-
-    Note: It would be valid to perform certain parts of the instantiation [=in parallel=], but several parts need to happen in the event loop, including JavaScript operations to access the |importObject| and execution of the start function.
 </div>
 
 <div algorithm>
@@ -428,10 +461,7 @@ A {{Module}} object represents a single WebAssembly module. Each {{Module}} obje
 
 <div algorithm>
   The <dfn method for="WebAssembly">instantiate(|moduleObject|, |importObject|)</dfn> method, when invoked, performs the following steps:
-    1. Let |promise| be [=a new promise=].
-    1. [=instantiate a WebAssembly module|Instantiate the WebAssembly module=] |moduleObject| importing |importObject|, with the following steps, given |instance|.  If this throws an exception, catch it, and [=reject=] |promise| with the exception.
-        1. [=Resolve=] |promise| with |instance|.
-    1. Return |promise|
+    1. [=asynchronously instantiate a WebAssembly module|Asynchronously instantiate the WebAssembly module=] |moduleObject| importing |importObject|, and return the result.
 </div>
 
 Note: A follow-on streaming API is documented in the <a href="https://webassembly.github.io/spec/web-api/index.html">WebAssembly Web API</a>.
@@ -515,6 +545,8 @@ interface Module {
     1. [=Compile a WebAssembly module|Compile the WebAssembly module=] |stableBytes| and store the result as |module|.
     1. If |module| is [=error=], throw a {{CompileError}} exception.
     1. [=Construct a WebAssembly module object=] from |module| and |stableBytes|, and return the result.
+
+Note: Some implementations may enforce a size limitation on |bytes|. Use of this API is discouraged, in favor of asynchronous APIs.
 </div>
 
 <h3 id="instances">Instances</h3>
@@ -527,7 +559,9 @@ interface Instance {
 </pre>
 
 <div algorithm>
-    The <dfn constructor for="Instance">Instance(|module|, |importObject|)</dfn> constructor, when invoked, [=instantiate a WebAssembly module|instantiates the WebAssembly module=] |module| importing |importObject| and returns the result.
+    The <dfn constructor for="Instance">Instance(|module|, |importObject|)</dfn> constructor, when invoked, [=synchronously instantiate a WebAssembly module|synchronously instantiates the WebAssembly module=] |module| importing |importObject| and returns the result.
+
+Note: The use of this synchronous API is discouraged, as some implementations sometimes do long-running compilation work when instantiating.
 </div>
 
 <div algorithm>
