Skip to content

Commit b021045

Browse files
fgmccabefgmccabe
committed
Update to reflect upstream changes to index.bs
1 parent 7506990 commit b021045

File tree

1 file changed

+210
-15
lines changed

1 file changed

+210
-15
lines changed

‎document/js-api/index.bs‎

Lines changed: 210 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -36,6 +36,15 @@ urlPrefix: https://tc39.github.io/ecma262/; spec: ECMASCRIPT
3636
text: NativeError; url: sec-nativeerror-constructors
3737
text: TypeError; url: sec-native-error-types-used-in-this-standard-typeerror
3838
text: RangeError; url: sec-native-error-types-used-in-this-standard-rangeerror
39+
type: dfn;
40+
text: AbstractClosure; url: sec-abstract-closure
41+
text: CreateBuiltinFunction; url: sec-createbuiltinfunction
42+
text: PromiseCapabilityRecord; url: sec-promisecapability-records
43+
text: EvaluateCall; url: sec-evaluatecall
44+
text: ExecutionContext; url: sec-execution-contexts
45+
text: IsPromise; url: sec-ispromise
46+
text: PerformPromiseThen; url: sec-performpromisethen
47+
text: Execution Context Stack; url: execution-context-stack
3948
type: dfn
4049
url: sec-returnifabrupt-shorthands
4150
text: !
@@ -101,6 +110,8 @@ urlPrefix: https://webassembly.github.io/spec/core/; spec: WebAssembly; type: df
101110
text: func_alloc; url: appendix/embedding.html#embed-func-alloc
102111
text: func_type; url: appendix/embedding.html#embed-func-type
103112
text: func_invoke; url: appendix/embedding.html#embed-func-invoke
113+
text: evaluation_suspend; url: appendix/embedding.html#embed-evaluation-suspend
114+
text: evaluation_resume; url: appendix/embedding.html#embed-evaluation-resume
104115
text: table_alloc; url: appendix/embedding.html#embed-table-alloc
105116
text: table_type; url: appendix/embedding.html#embed-table-type
106117
text: table_read; url: appendix/embedding.html#embed-table-read
@@ -385,13 +396,18 @@ A {{Module}} object represents a single WebAssembly module. Each {{Module}} obje
385396
1. Let |o| be [=?=] [$Get$](|importObject|, |moduleName|).
386397
1. If [=Type=](|o|) is not Object, throw a {{TypeError}} exception.
387398
1. Let |v| be [=?=] [$Get$](|o|, |componentName|).
388-
1. If |externtype| is of the form [=external-type/func=] |functype|,
389-
1. If [$IsCallable$](|v|) is false, throw a {{LinkError}} exception.
390-
1. If |v| has a \[[FunctionAddress]] internal slot, and therefore is an [=Exported Function=],
391-
1. Let |funcaddr| be the value of |v|'s \[[FunctionAddress]] internal slot.
392-
1. Otherwise,
393-
1. [=Create a host function=] from |v| and |functype|, and let |funcaddr| be the result.
394-
1. Let |index| be the number of external functions in |imports|. This value |index| is known as the <dfn>index of the host function</dfn> |funcaddr|.
399+
1. If |externtype| is of the form [=func=] |functype|,
400+
1. If [$IsCallable$](|v|) is true
401+
1. If |v| has a \[[FunctionAddress]] internal slot, and therefore is an [=Exported Function=],
402+
1. Let |funcaddr| be the value of |v|'s \[[FunctionAddress]] internal slot.
403+
1. Otherwise,
404+
1. [=Create a host function=] from |v| and |functype|, and let |funcaddr| be the result.
405+
1. Otherwise, if |v| has a \[[wrappedFunction]] insternal slot
406+
1. Let |func| be the value of |v|'s \[[wrappedFunction]] internal slot.
407+
1. Assert: [$IsCallable$](|func|) is true
408+
1. [=Create a suspending function|create a suspending function=] from |func| and |functype|, and let |funcaddr| be the result.
409+
1. Otherwise, throw a {{LinkError}} exception.
410+
1. Let |index| be the number of external functions in |imports|. This value |index| is known as the <dfn>index of the host function</dfn> |funcaddr|.
395411
1. Let |externfunc| be the [=external value=] [=external value|func=] |funcaddr|.
396412
1. [=list/Append=] |externfunc| to |imports|.
397413
1. If |externtype| is of the form [=external-type/global=] <var ignore>mut</var> |valtype|,
@@ -408,6 +424,10 @@ A {{Module}} object represents a single WebAssembly module. Each {{Module}} obje
408424
1. Let |store| be the [=surrounding agent=]'s [=associated store=].
409425
1. Let (|store|, |globaladdr|) be [=global_alloc=](|store|, [=const=] |valtype|, |value|).
410426
1. Set the [=surrounding agent=]'s [=associated store=] to |store|.
427+
1. Otherwise, if |v| [=implements=] {{Global}},
428+
1. Let |globaladdr| be |v|.\[[Global]].
429+
1. Otherwise,
430+
1. Throw a {{LinkError}} exception.
411431
1. Let |externglobal| be [=external value|global=] |globaladdr|.
412432
1. [=list/Append=] |externglobal| to |imports|.
413433
1. If |externtype| is of the form [=external-type/mem=] <var ignore>memtype</var>,
@@ -1126,12 +1146,9 @@ This slot holds a [=function address=] relative to the [=surrounding agent=]'s [
11261146
</div>
11271147

11281148
<div algorithm>
1129-
To <dfn>call an Exported Function</dfn> with [=function address=] |funcaddr| and a [=list=] of JavaScript arguments |argValues|, perform the following steps:
1130-
1131-
1. Let |store| be the [=surrounding agent=]'s [=associated store=].
1132-
1. Let |functype| be [=func_type=](|store|, |funcaddr|).
1149+
To <dfn>coerce JavaScript arguments</dfn> from a |functype| and a [=list=] of JavaScript arguments |argValues|, perform the following steps
11331150
1. Let [|parameters|] → [|results|] be |functype|.
1134-
1. If |parameters| or |results| contain [=v128=] or [=exnref=], throw a {{TypeError}}.
1151+
1. If |parameters| or |results| contain [=v128=], throw a {{TypeError}}.
11351152

11361153
Note: the above error is thrown each time the \[[Call]] method is invoked.
11371154
1. Let |args| be « ».
@@ -1141,6 +1158,14 @@ This slot holds a [=function address=] relative to the [=surrounding agent=]'s [
11411158
1. Otherwise, let |arg| be undefined.
11421159
1. [=list/Append=] [=ToWebAssemblyValue=](|arg|, |t|) to |args|.
11431160
1. Set |i| to |i| + 1.
1161+
1. return |args|
1162+
</div>
1163+
1164+
<div algorithm>
1165+
To <dfn>call an Exported Function</dfn> with [=function address=] |funcaddr| and a [=list=] of JavaScript arguments |argValues|, perform the following steps:
1166+
1. Let |store| be the [=surrounding agent=]'s [=associated store=].
1167+
1. Let |functype| be [=func_type=](|store|, |funcaddr|).
1168+
1. Let |args| be the result of [=coerce JavaScript arguments|coercing arguments=] (|functype|,|argValues|)
11441169
1. Let (|store|, |ret|) be the result of [=func_invoke=](|store|, |funcaddr|, |args|).
11451170
1. Set the [=surrounding agent=]'s [=associated store=] to |store|.
11461171
1. If |ret| is [=error=], throw an exception. This exception should be a WebAssembly {{RuntimeError}} exception, unless otherwise indicated by <a href="#errors">the WebAssembly error mapping</a>.
@@ -1169,13 +1194,23 @@ Note: Exported Functions do not have a \[[Construct]] method and thus it is not
11691194

11701195
<div algorithm>
11711196
To <dfn>run a host function</dfn> from the JavaScript object |func|, type |functype|, and [=list=] of [=WebAssembly values=] |arguments|, perform the following steps:
1197+
1. Let [|parameters|] → [|resultTypes|] be |functype|.
1198+
1. Let |jsArguments| be the result of [=coerce WebAssembly arguments=](|parameters|,|arguments|)
1199+
1. Let |ret| be [=?=] [$Call$](|func|, undefined, |jsArguments|).
1200+
1. Return the result of performing [=coerce a JavaScript return=] on |resultTypes| and |ret|.
1201+
</div>
11721202

1173-
1. Let [|parameters|] → [|results|] be |functype|.
1174-
1. If |parameters| or |results| contain [=v128=] or [=exnref=], throw a {{TypeError}}.
1203+
<div algorithm>
1204+
To <dfn>coerce WebAssembly arguments</dfn> from a [=list=] of |parameterTypes| and a [=list=] of JavaScript arguments |arguments|, perform the following steps
1205+
1. If |parameterTypes| contain [=v128=], throw a {{TypeError}}.
11751206
1. Let |jsArguments| be « ».
11761207
1. [=list/iterate|For each=] |arg| of |arguments|,
11771208
1. [=list/Append=] [=!=] [=ToJSValue=](|arg|) to |jsArguments|.
1178-
1. Let |ret| be [=?=] [$Call$](|func|, undefined, |jsArguments|).
1209+
1. Return |jsArguments|
1210+
</div>
1211+
1212+
<div algorithm>
1213+
To <dfn>coerce a JavaScript return</dfn> from a JavaScript |ret| and a list of |results| types, perform the following steps:
11791214
1. Let |resultsSize| be |results|'s [=list/size=].
11801215
1. If |resultsSize| is 0, return « ».
11811216
1. Otherwise, if |resultsSize| is 1, return « [=?=] [=ToWebAssemblyValue=](|ret|, |results|[0]) ».
@@ -1190,6 +1225,18 @@ Note: Exported Functions do not have a \[[Construct]] method and thus it is not
11901225
1. Return |wasmValues|.
11911226
</div>
11921227

1228+
<div algorithm>
1229+
To <dfn>coerce a JavaScript exception</dfn> from a JavaScript exception |v|, perform the following steps:
1230+
1. If |v| [=implements=] {{Exception}},
1231+
1. Let |type| be |v|.\[[Type]].
1232+
1. Let |payload| be |v|.\[[Payload]].
1233+
1. Otherwise,
1234+
1. Let |type| be the [=JavaScript exception tag=].
1235+
1. Let |payload| be « ».
1236+
1. Let |opaqueData| be [=ToWebAssemblyValue=](|v|, [=externref=])
1237+
1. Return the triple |type|, |payload| and |opaqueData|.
1238+
</div>
1239+
11931240
<div algorithm>
11941241
To <dfn>create a host function</dfn> from the JavaScript object |func| and type |functype|, perform the following steps:
11951242

@@ -1329,6 +1376,154 @@ The algorithm <dfn>ToWebAssemblyValue</dfn>(|v|, |type|) coerces a JavaScript va
13291376

13301377
</div>
13311378

1379+
<h3 id="jspi">JavaScript Promise Integration</h3>
1380+
1381+
A {{Suspending}} object represents a JavaScript function whose calls via WebAssembly imports should be *suspended* when they return a Promise object.
1382+
Each {{Suspending}} object has a \[[wrappedFunction]] internal slot which holds a JavaScript function.
1383+
1384+
In addition, the {{promising}} function takes as argument a WebAssembly function and returns a JavaScript function that returns a Promise that is resolved when the WebAssembly function completes.
1385+
1386+
<pre class="idl">
1387+
[Exposed=*]
1388+
partial namespace WebAssembly {
1389+
Function promising(Function wasmFunc);
1390+
};
1391+
1392+
[LegacyNamespace=WebAssembly, Exposed=*]
1393+
interface Suspending {
1394+
constructor(Function jsFun);
1395+
};
1396+
</pre>
1397+
1398+
<div algorithm>
1399+
The <dfn method for="WebAssembly">promising(|wasmFunc|)</dfn> function, when invoked, performs the following steps:
1400+
1. If [$IsCallable$](|wasmFunc|) is false, throw a {{TypeError}}.
1401+
1. If |wasmFunc| does not have a \[[FunctionAddress]] internal slot, throw a {{TypeError}}.
1402+
1. Let |builder| be a new [=AbstractClosure=] with parameters that captures |wasmFunc| that, when invoked, performs [=run a Promising function=].
1403+
1. Returns [=CreateBuiltinFunction=](|builder|,1,"",<<>>)
1404+
</div>
1405+
1406+
<div algorithm>
1407+
The algorithm to <dfn>run a Promising function</dfn> from the JavaScript object |wasmFunc| and a [=list=] of [=WebAssembly values=] |arguments| consists of the following steps:
1408+
1. Let |promise| be a new [=PromiseCapabilityRecord=].
1409+
1. Let |funcaddr| be the value of |wasmFunc|'s \[[FunctionAddress]] internal slot.
1410+
1. Let |runner| be a new [=AbstractClosure=] of no arguments that captures |promise|, |funcaddr|, |arguments| that, when invoked, performs the following steps:
1411+
1. Let |store| be the [=surrounding agent=]'s [=associated store=].
1412+
1. Let |functype| be [=func_type=](|store|, |funcaddr|).
1413+
1. Let |args| be the result of [=coerce JavaScript arguments|coercing arguments=] (|functype|,|arguments|)
1414+
1. Let (|store|, |result|) be the result of [=func_invoke=](|store|, |funcaddr|, |args|).
1415+
1. Assert: if control reaches here, we have done waiting for suspended imports
1416+
1. Set the [=surrounding agent=]'s [=associated store=] to |store|.
1417+
1. If |result| is [=error=], throw an exception. This exception should be a WebAssembly {{RuntimeError}} exception, unless otherwise indicated by <a href="#errors">the WebAssembly error mapping</a>.
1418+
1. Otherwise, if |result| is of the form [=throw=] exnaddr,
1419+
1. Perform [=EvaluateCall=] (|promise|.\[[Reject]],|result|.,false).
1420+
1. Return UNDETERMINED
1421+
1. Otherwise, assert |result| is a [=list=] of WebAssembly values
1422+
1. Let |outArity| be the [=list/size=] of |result|.
1423+
1. If |outArity| is 0, return undefined.
1424+
1. Otherwise, if |outArity| is 1, let |jsReturnValue| be [=ToJSValue=](|result|[0]).
1425+
1. Otherwise,
1426+
1. Let |values| be « ».
1427+
1. [=list/iterate|For each=] |r| of |result|,
1428+
1. [=list/Append=] [=ToJSValue=](|r|) to |values|.
1429+
1. let |jsReturnValue| be [$CreateArrayFromList$](|values|).
1430+
1. Perform [=EvaluateCall=] (|promise|.\[[Resolve]],|jsReturnValue|,false)
1431+
1. Return UNDETERMINED
1432+
1. Let |con| be [=CreateBuiltinFunction=](|runner|,0,"",<<>>)
1433+
1. Perform [$Call$](|con|, undefined, <<>>)
1434+
1. Returns |promise|
1435+
</div>
1436+
1437+
Note: The extra |$Call$| in the above algorithm ensures that the creation of the Promise is separated from the fullfilling of that Promise. In effect, this allows suspension of the fullfillment to occur whilst allowing the creation of the Promise itself to continue.
1438+
1439+
<div algorithm>
1440+
The <dfn constructor for="Suspending">Suspending(|jsFun|)</dfn> constructor, when invoked, performs the following steps:
1441+
1. If [$IsCallable$](|jsFun|) is false, throw a {{TypeError}}.
1442+
1. Let |suspendingProto| be \[[%WebAssembly.Suspending.prototype%]]
1443+
1. Let |susp| be the result of [$OrdinaryObjectCreate$](|suspendingProto|)
1444+
1. Assign the \[[wrappedFunction]] internal slot of |susp| to |jsFun|
1445+
1. Return |susp|
1446+
</div>
1447+
1448+
<div algorithm>
1449+
To <dfn>create a suspending function</dfn> from a JavaScript function |func|, with type |functype| perform the following steps:
1450+
1451+
1. Assert: [$IsCallable$](|func|).
1452+
1. Let |stored settings| be the <a spec=HTML>incumbent settings object</a>.
1453+
1. Let |hostfunc| be a [=host function=] which performs the following steps when called with arguments |arguments|:
1454+
1. Let |realm| be |func|'s [=associated Realm=].
1455+
1. Let |relevant settings| be |realm|'s [=realm/settings object=].
1456+
1. Let |async_context| be the [=surrounding agent=]'s [=running execution context=].
1457+
1. [=Prepare to run script=] with |relevant settings|.
1458+
1. [=Prepare to run a callback=] with |stored settings|.
1459+
1. Let [|parameters|] → [|results|] be |functype|.
1460+
1. Let |jsArguments| be the result of [=coerce WebAssembly arguments=](|parameters|,|arguments|)
1461+
1. Let |ret| be [=?=] [$Call$](|func|, undefined, |jsArguments|).
1462+
1. [=Clean up after running a callback=] with |stored settings|.
1463+
1. [=Clean up after running script=] with |relevant settings|.
1464+
1. Assert: |ret|.\[[Type]] is <emu-const>throw</emu-const> or <emu-const>normal</emu-const>.
1465+
1. If |ret|.\[[Type]] is <emu-const>throw</emu-const>, then:
1466+
1. Let |type|, |payload| and |opaqueData| be the result of [=coerce a JavaScript exception|coercing the JavaScript exception=] |ret|.\[[Value]].
1467+
1. [=WebAssembly/Throw=] with |type|, |payload| and |opaqueData|.
1468+
1. Otherwise, if [=list/size=] of |ret| is 1 and [$IsPromise$](|ret|.\[[Value]][0]):
1469+
1. Let |promise| be |ret|.\[[Value]][0].
1470+
1. Perform the [=Pause=] procedure, returning a new continuation |k|.
1471+
1. Let |resolved| be an [=AbstractClosure=] with parameters (|v|) that captures |functype|, |k| and performs the following steps when called:
1472+
1. Let |resultsSize| be |results|'s [=list/size=].
1473+
1. If |resultsSize| is not 1, throw a {{TypeError}}.
1474+
1. Let |resultType| be [|results|].[0].
1475+
1. Let |returnValue| be [=ToWebAssemblyValue=](|v|, |resultType|).
1476+
1. Perform the [=Enter=] procedure, passing it the captured continuation |k| the coerced |returnValue| and |async_context|.
1477+
1. Return undefined.
1478+
1. Let |onResolved| be [=CreateBuiltinFunction=](|resolved|,1,"",[])
1479+
1. Let |rejected| be an [=AbstractClosure=] with parameters (|e|) that captures |async_context| and performs the following steps when called:
1480+
1. Perform the [=Reject=] procedure, passing it the captured continuation |k| the exception value |e| and |async_context|.
1481+
1. Return undefined.
1482+
1. Let |onRejected| be [=CreateBuiltinFunction=](|rejected|,1,"",[])
1483+
1. Perform [$PerformPromiseThen$](|promise|, |onResolved|, |onRejected|).
1484+
1. Return undefined
1485+
1. Return the result of performing [=coerce a JavaScript return=] on |results| and |ret|.
1486+
1. Let |store| be the [=surrounding agent=]'s [=associated store=].
1487+
1. Let (|store|, |funcaddr|) be [=func_alloc=](|store|, |functype|, |hostfunc|).
1488+
1. Set the [=surrounding agent=]'s [=associated store=] to |store|.
1489+
1. Return |funcaddr|.
1490+
</div>
1491+
1492+
<div dfn>
1493+
An [=execution context=] can be marked <dfn>Paused</dfn> to signal that the computation associated with the [=execution context=] has been paused.
1494+
</div>
1495+
1496+
<div algorithm>
1497+
The <dfn>Pause</dfn> abstract operation takes a currently executing algorithm and pauses it. The most important parameter |ec| of this operation is an
1498+
[=Execution Context=] which must be the most recent entry in the [=Execution Context Stack=] and which defines which operation is being paused.
1499+
The result of pausing an operation is a continuation |k| and a newly surfaced [=Execution Context=] -- which must be the [=Execution Context=] immediately
1500+
beneath the one on the [=Execution Context Stack=] that is [=Paused|paused=].
1501+
1502+
1. If |ec| is not the most recent entry on the [=Execution Context Stack=] then trap.
1503+
1. Let |k| be a continuation that represents the remainder of the computation associated with |ec|.
1504+
1. Remove |ec| from the [=Execution Context Stack=] and mark it as being [=Paused|paused=].
1505+
1. Assert that the [=Execution Context Stack=] is not empty.
1506+
1. Return |k|
1507+
</div>
1508+
1509+
<div algorithm>
1510+
The <dfn>Enter</dfn> abstract operation takes a continuation object |k|, a value object |v| and an [=execution context=] |ec|, and resumes the operations defined by |k|.
1511+
1. If |ec| is not marked as [=Paused|paused=] then trap.
1512+
1. Mark |ec| as not [=Paused|paused=].
1513+
1. Push |ec| on to the [=Execution Context Stack=], making |ec| the current execution context.
1514+
1. Resume the operations defined by |k|, passing |v| as the value of the last instruction being performed by |k|
1515+
1. Return undefined
1516+
</div>
1517+
1518+
<div algorithm>
1519+
The <dfn>Reject</dfn> abstract operation takes a continuation object |k|, an exception object |e| and an [=execution context=] |ec|, and resumes the operations defined by |k| by throwing an exception to the [=Paused|paused=] computation.
1520+
1. If |ec| is not marked as [=Paused|paused=] then trap.
1521+
1. Mark |ec| as not [=Paused|paused=].
1522+
1. Push |ec| on to the [=Execution Context Stack=], making |ec| the current execution context.
1523+
1. Let |type|, |payload| and |opaqueData| be the result of performing [=coerce a JavaScript exception=} on |e|
1524+
1. Resume the operations defined by |k|, performing [=WebAssembly/Throw=] with |type|, |payload| and |opaqueData|.
1525+
</div>
1526+
13321527

13331528
<h3 id="tags">Tags</h3>
13341529

0 commit comments

Comments
 (0)