From 53c4677184044de8a9570e0cb32d0166d49d8fe1 Mon Sep 17 00:00:00 2001 From: Daniel Ehrenberg Date: Wed, 7 Mar 2018 19:10:34 +0100 Subject: [PATCH] [jsapi] Normative: Always queue a task during asynchronous instantiation 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: - Include notes about APIs whose use is discouraged/may be limited Closes #741 See also https://github.com/webpack/webpack/issues/6433 --- document/js-api/index.bs | 33 ++++++++++++++++++++------------- 1 file changed, 20 insertions(+), 13 deletions(-) diff --git a/document/js-api/index.bs b/document/js-api/index.bs index f6b89ed33a..b76c98296d 100644 --- a/document/js-api/index.bs +++ b/document/js-api/index.bs @@ -415,17 +415,19 @@ A {{Module}} object represents a single WebAssembly module. Each {{Module}} obje 1. Let |module| be |moduleObject|.\[[Module]]. 1. [=Read the imports=] of |module| with imports |importObject|, and let |imports| be the result. If this operation throws an exception, catch it, [=reject=] |promise| with the exception, and return |promise|. - 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 throws an exception, catch it, [=reject=] |promise| with the exception, and terminate these substeps. - 1. [=Create an instance object=] from |module| and |instance|, and let the result be |instanceObject|. - If this throws an exception, catch it, [=reject=] |promise| with the exception, and terminate these substeps. - 1. [=Resolve=] |promise| with |instanceObject|. + 1. Run the following steps [=in parallel=]: + 1. [=Queue a task=] to perform the following steps: + Note: Implementation-specific work may be performed here. + 1. [=Instantiate the core of a WebAssembly module=] |module| with |imports|, and let |instance| be the result. + If this throws an exception, catch it, [=reject=] |promise| with the exception, and terminate these substeps. + 1. [=Create an instance object=] from |module| and |instance|, and let the result be |instanceObject|. + If this throws an exception, catch it, [=reject=] |promise| with the exception, and terminate these substeps. + 1. [=Resolve=] |promise| with |instanceObject|. 1. Return |promise|.
- To instantiate a WebAssembly module from a {{Module}} |moduleObject| and imports |importObject|, perform the following steps: + To synchronously instantiate a WebAssembly module 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. @@ -438,14 +440,15 @@ A {{Module}} object represents a single WebAssembly module. Each {{Module}} obje 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|, and let |instance| be the result. If this throws an exception, catch it, [=reject=] |promise| with the exception, and abort these substeps. - 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. [=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.
@@ -541,6 +544,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 enforce a size limitation on |bytes|. Use of this API is discouraged, in favor of asynchronous APIs.

Instances

@@ -553,7 +558,9 @@ interface Instance {
- The Instance(|module|, |importObject|) constructor, when invoked, [=instantiate a WebAssembly module|instantiates the WebAssembly module=] |module| importing |importObject| and returns the result. + The Instance(|module|, |importObject|) 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.