Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

[spec] Normative: Permit work in parallel during instantiation #745

Merged
merged 3 commits into from
Feb 17, 2023
Merged

[spec] Normative: Permit work in parallel during instantiation #745

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
66e15de
Editorial: Clarify the name of the instantiate algorithm.
littledan Mar 18, 2019
4693e59
Add notes to discourage using synchronous APIs.
littledan Mar 18, 2019
73ec120
[jsapi] Normative: Always queue a task during asynchronous instantiation
littledan Mar 18, 2019
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
33 changes: 20 additions & 13 deletions document/js-api/index.bs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -462,18 +462,20 @@ The verification of WebAssembly type requirements is deferred to the
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. Let |instanceObject| be a [=/new=] {{Instance}}.
1. [=initialize an instance object|Initialize=] |instanceObject| from |module| and |instance|.
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. Let |instanceObject| be a [=/new=] {{Instance}}.
1. [=initialize an instance object|Initialize=] |instanceObject| from |module| and |instance|.
If this throws an exception, catch it, [=reject=] |promise| with the exception, and terminate these substeps.
1. [=Resolve=] |promise| with |instanceObject|.
1. Return |promise|.
</div>

<div algorithm="instantiate">
To <dfn>instantiate a WebAssembly module</dfn> from a {{Module}} |moduleObject| and imports |importObject|, perform the following steps:
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.
Expand All @@ -487,14 +489,15 @@ The verification of WebAssembly type requirements is deferred to the

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 the {{WebAssemblyInstantiatedSource}} value «[ "{{WebAssemblyInstantiatedSource/module}}" → |module|, "{{WebAssemblyInstantiatedSource/instance}}" → |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 the {{WebAssemblyInstantiatedSource}} value «[ "{{WebAssemblyInstantiatedSource/module}}" → |module|, "{{WebAssemblyInstantiatedSource/instance}}" → |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>
Expand Down Expand Up @@ -592,6 +595,8 @@ interface Module {
1. If |module| is [=error=], throw a {{CompileError}} exception.
1. Set **this**.\[[Module]] to |module|.
1. Set **this**.\[[Bytes]] to |stableBytes|.

Note: Some implementations enforce a size limitation on |bytes|. Use of this API is discouraged, in favor of asynchronous APIs.
</div>

<h3 id="instances">Instances</h3>
Expand All @@ -610,6 +615,8 @@ interface Instance {
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. [=initialize an instance object|Initialize=] **this** from |module| and |instance|.

Note: The use of this synchronous API is discouraged, as some implementations sometimes do long-running compilation work when instantiating.
</div>

<div algorithm>
Expand Down