fixup! [js-api] Add support for exceptions.

Ms2ger · Ms2ger · commit eb92b3a21dce · 2020-06-05T16:16:10.000+02:00
diff --git a/document/js-api/index.bs b/document/js-api/index.bs
@@ -108,6 +108,7 @@ urlPrefix: https://webassembly.github.io/spec/core/; spec: WebAssembly; type: df
         text: ref.null
         text: ref.func
         text: ref.host
+        text: ref.exn
     text: function index; url: syntax/modules.html#syntax-funcidx
     text: function instance; url: exec/runtime.html#function-instances
     text: store_init; url: appendix/embedding.html#embed-store-init
@@ -144,6 +145,7 @@ urlPrefix: https://webassembly.github.io/spec/core/; spec: WebAssembly; type: df
     text: memory address; url: exec/runtime.html#syntax-memaddr
     text: global address; url: exec/runtime.html#syntax-globaladdr
     text: host address; url: exec/runtime.html#syntax-hostaddr
+    text: event address; url: exec/runtime.html#syntax-eventaddr
     url: syntax/types.html#syntax-numtype
         text: 𝗂𝟥𝟤
         text: 𝗂𝟨𝟦
@@ -153,9 +155,13 @@ urlPrefix: https://webassembly.github.io/spec/core/; spec: WebAssembly; type: df
         text: anyref
         text: funcref
         text: nullref
+        text: exnref
     text: function element; url: exec/runtime.html#syntax-funcelem
     text: import component; url: syntax/modules.html#imports
-    text: external value; url: exec/runtime.html#syntax-externval
+    url: exec/runtime.html#syntax-externval
+        text: external value
+        for: external value
+            text: event
     text: host function; url: exec/runtime.html#syntax-hostfunc
     text: the instantiation algorithm; url: exec/modules.html#instantiation
     text: module; url: syntax/modules.html#syntax-module
@@ -167,6 +173,8 @@ urlPrefix: https://webassembly.github.io/spec/core/; spec: WebAssembly; type: df
         text: 𝗍𝖺𝖻𝗅𝖾
         text: 𝗆𝖾𝗆
         text: 𝗀𝗅𝗈𝖻𝖺𝗅
+        for: externtype
+            text: event
     text: global type; url: syntax/types.html#syntax-globaltype
     url: syntax/types.html#syntax-mut
         text: var
@@ -178,6 +186,7 @@ urlPrefix: https://webassembly.github.io/spec/core/; spec: WebAssembly; type: df
     text: 𝗆𝗈𝖽𝗎𝗅𝖾; url: exec/runtime.html#syntax-frame
     text: 𝗆𝖾𝗆𝖺𝖽𝖽𝗋𝗌; url: exec/runtime.html#syntax-moduleinst
     text: sequence; url: syntax/conventions.html#grammar-notation
+    text: exception; for: eventtype/attribute; url: syntax/types.html#syntax-eventtype
 urlPrefix: https://heycam.github.io/webidl/; spec: WebIDL
     type: dfn
         text: create a namespace object; url: create-a-namespace-object
@@ -382,12 +391,18 @@ A {{Module}} object represents a single WebAssembly module. Each {{Module}} obje
             1. Note: [=module_instantiate=] invoked below will check the imported {{Memory}}'s size against the importing module's requirements.
             1. Let |externmem| be the [=external value=] [=external value|𝗆𝖾𝗆=]  |v|.\[[Memory]].
             1. [=Append=] |externmem| to |imports|.
-        1. Otherwise, |externtype| is of the form [=𝗍𝖺𝖻𝗅𝖾=] <var ignore>tabletype</var>,
+        1. If |externtype| is of the form [=𝗍𝖺𝖻𝗅𝖾=] <var ignore>tabletype</var>,
             1. If |v| is not a {{Table}} instance, throw a {{LinkError}} exception.
             1. Note: The table's length, etc. is checked by [=module_instantiate=] invoked below.
             1. Let |tableaddr| be |v|.\[[Table]]
             1. Let |externtable| be the [=external value=] [=external value|𝗍𝖺𝖻𝗅𝖾=] |tableaddr|.
             1. [=Append=] |externtable| to |imports|.
+        1. If |externtype| is of the form [=externtype/event=] |attribute| <var ignore>functype</var>,
+            1. Assert: |attribute| is [=eventtype/attribute/exception=].
+            1. If |v| does not [=implement=] {{Exception}}, throw a {{LinkError}} exception.
+            1. Let |tag| be |v|'s [=Exception/exception tag=].
+            1. Let |extern| be the [=external value=] [=external value/event=] |tag|.
+            1. [=Append=] |extern| to |imports|.
     1. Return |imports|.
 </div>
 
@@ -412,11 +427,17 @@ A {{Module}} object represents a single WebAssembly module. Each {{Module}} obje
             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 [=𝗍𝖺𝖻𝗅𝖾=] <var ignore>tabletype</var>,
+        1. If |externtype| is of the form [=𝗍𝖺𝖻𝗅𝖾=] <var ignore>tabletype</var>,
             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. If |externtype| is of the form [=externtype/event=] |attribute| <var ignore>functype</var>,
+            1. Assert: |attribute| is [=eventtype/attribute/exception=].
+            1. Assert: |externval| is of the form [=external value/event=] |eventaddr|.
+            1. Let [=external value/event=] |eventaddr| be |externval|.
+            1. Let |exception| be [=create an Exception object|a new Exception object=] created from |eventaddr|.
+            1. Let |value| be |exception|.
         1. Let |status| be ! [=CreateDataProperty=](|exportsObject|, |name|, |value|).
         1. Assert: |status| is true.
 
@@ -508,7 +529,8 @@ enum ImportExportKind {
   "function",
   "table",
   "memory",
-  "global"
+  "global",
+  "event"
 };
 
 dictionary ModuleExportDescriptor {
@@ -537,6 +559,7 @@ interface Module {
     * "table" if |type| is of the form [=𝗍𝖺𝖻𝗅𝖾=] tabletype
     * "memory" if |type| is of the form [=𝗆𝖾𝗆=] memtype
     * "global" if |type| is of the form [=𝗀𝗅𝗈𝖻𝖺𝗅=] globaltype
+    * "event" if |type| is of the form [=externtype/event=] <var ignore>event</var>
 </div>
 
 <div algorithm>
@@ -1003,14 +1026,8 @@ This slot holds a [=function address=] relative to the [=surrounding agent=]'s [
     1. Let (|store|, |ret|) be the result of [=func_invoke=](|store|, |funcaddr|, |argsSeq|).
     1. Set the [=surrounding agent=]'s [=associated store=] to |store|.
     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>.
-    1. If |ret| is exception [=exnref=] |exception|,
-        1. If |exception|'s [=exnref/exception tag=] is the [=JavaScript exception tag=], then
-            1. Let [=ref.extern=] |externaddr| be |exception|'s [=exnref/payload=].
-            1. Let |jsException| be the result of [=retrieving an extern value=] from |externaddr|.
-            1. Throw |jsException|.
-        1. Throw a {{RuntimeError}} exception.
-
-            Issue: Probably shouldn't be a {{RuntimeError}}.
+    1. If |ret| is exception |exnaddr|,
+        1. Throw [=ToJSValue=]([=ref.exn=] |exnaddr|).
     1. If |ret| is empty, return undefined.
     1. Otherwise, return [=ToJSValue=](|v|), where |v| is the singular element of |ret|.
 </div>
@@ -1041,7 +1058,7 @@ Note: Exported Functions do not have a \[[Construct]] method and thus it is not
         1. Let |result| be the result of [=run a host function|running a host function=] from |func|, |functype|, and |arguments|.
         1. Assert: |result|.\[[Type]] is <emu-const>throw</emu-const> or <emu-const>return</emu-const>.
         1. If |result|.\[[Type]] is <emu-const>throw</emu-const>, then:
-            1. Let |exception| be [=ToWebAssemblyValue=](|result|.\[[Value]], [=anyref=]).
+            1. Let |exception| be [=ToWebAssemblyValue=](|result|.\[[Value]], [=exnref=]).
             1. [=WebAssembly/Throw=] |exception| with the [=JavaScript exception tag=].
         1. Otherwise, return |result|.\[[Value]].
     1. Let |store| be the [=surrounding agent=]'s [=associated store=].
@@ -1060,6 +1077,11 @@ The algorithm <dfn>ToJSValue</dfn>(|w|) coerces a [=WebAssembly value=] to a Jav
 1. If |w| is of the form [=ref.null=], return null.
 1. If |w| is of the form [=ref.func=] |funcaddr|, return the result of creating [=a new Exported Function=] from |funcaddr|.
 1. If |w| is of the form [=ref.host=] |hostaddr|, return the result of [=retrieving a host value=] from |hostaddr|.
+1. If |w| is of the form [=ref.exn=] |exntag| |payload|, then
+    1. If |exntag| is the [=JavaScript exception tag=], then
+        1. Let « [=ref.extern=] |externaddr| » be |payload|.
+        1. Return the result of [=retrieving an extern value=] from |externaddr|.
+    1. Return a {{RuntimeException}} whose [=RuntimeException/internal exception=] is |exnaddr|.
 
 <!-- If the WebAssembly value is optional, then given `None`, return JavaScript value `undefined`. -->
 
@@ -1087,6 +1109,15 @@ The algorithm <dfn>ToWebAssemblyValue</dfn>(|v|, |type|, |error|) coerces a Java
 1. If |type| is [=𝖿𝟨𝟦=],
     1. Let |f64| be ? [=ToNumber=](|v|).
     1. Return [=𝖿𝟨𝟦.𝖼𝗈𝗇𝗌𝗍=] |f64|.
+1. If |type| is [=exnref=],
+    1. If |v| [=implements=] {{RuntimeException}},
+        1. Let |exnaddr| be |v|'s [=RuntimeException/internal exception=].
+    1. Otherwise,
+        1. Let |payload| be [=ToWebAssemblyValue=](|v|, [=anyref=]).
+        1. Let |exnaddr| be a new [=event address=] referencing |payload| and the [=JavaScript exception tag=].
+    1. Return [=ref.exn=] |exnaddr|.
+
+    Note: There is no way to compare [=exnref=] values by reference.
 1. Assert: |type| is a reference type.
 1. If |type| is [=anyref=],
     1. Do nothing.
@@ -1116,22 +1147,85 @@ The algorithm <dfn>ToWebAssemblyValue</dfn>(|v|, |type|, |error|) coerces a Java
 
 <h3 id="exceptions">Exceptions</h3>
 
-A new type <dfn>exnref</dfn> is introduced for references to exceptions.
-Values of this type have an <dfn for=exnref>exception tag</dfn> and a <dfn for=exnref>payload</dfn>
+Values of the [=exnref=] type have an <dfn for=exnref>exception tag</dfn> and a
+<dfn for=exnref>payload</dfn>
 (whose type is dependent on the value of the [=exnref/exception tag=]).
 The concrete representation of values of this type is undefined.
 
+<h4 id="runtime-exceptions">Exception types</h4>
+
+<pre class="idl">
+[LegacyNamespace=WebAssembly, Exposed=(Window,Worker,Worklet)]
+interface Exception {
+};
+</pre>
+
+An {{Exception}} value represents a type of exception.
+{{Exception}} values have an <dfn for=Exception>exception tag</dfn>.
+
+The <dfn for=Exception>payload types</dfn> of an {{Exception}} is the [=list=] of types of
+
+
+<h4 id="runtime-exceptions">Runtime exceptions</h4>
+
+<pre class="idl">
+[LegacyNamespace=WebAssembly, Exposed=(Window,Worker,Worklet)]
+interface RuntimeException {
+  constructor(Exception exceptionType, sequence&lt;any> payload);
+  sequence&lt;any> arguments(Exception exceptionType);
+};
+</pre>
+
+A {{RuntimeException}} value represents an [=exnref=] value.
+{{RuntimeException}} values have an <dfn for=RuntimeException>internal exception</dfn>, which
+is an [=event address=].
+
+Issue: Should it be possible to construct {{RuntimeException}} objects from JavaScript? Only with
+the [=JavaScript exception tag=] or also with others? How?
+<div algorithm>
+
+The <dfn constructor for=RuntimeException
+lt="RuntimeException(exceptionType, payload)">new RuntimeException(|exceptionType|, |payload|)</dfn>
+constructor steps are:
+
+1. Let |types| be |exceptionType|'s [=Exception/exception tag=]'s [=list=] of types.
+1. If |types|'s [=list/size=] is not |payload|'s [=list/size=],
+    1. Throw a {{TypeError}}.
+1. Let |wasmPayload| be « ».
+1. [=list/iterate|For each=] |value| and |resultType| of |payload| and |types|, paired linearly,
+    1. [=list/Append=] [=ToWebAssemblyValue=](|value|, |resultType|) to |wasmPayload|.
+1. Let |exception| be a new [=exnref=] with [=exnref/exception tag=] set to |exceptionType|'s
+    [=Exception/exception tag=], and [=exnref/payload=] |wasmPayload|.
+1. Set **this**'s [=RuntimeException/internal exception=] to |exception|.
+
+</div>
+
+<div algorithm>
+
+The <dfn method for="RuntimeException">arguments(|exceptionType|)</dfn> method steps are:
+
+1. Let |internal| be **this**'s [=RuntimeException/internal exception=].
+1. If |internal|'s [=exnref/exception tag=] is not equal to |exceptionType|'s [=Exception/exception tag=],
+    1. Throw a {{TypeError}}.
+1. Let |payload| be |internal|'s [=exnref/payload=].
+1. Let |result| be « ».
+1. [=list/iterate|For each=] |value| of |payload|,
+    1. [=list/Append=] [=ToJSValue=](|value|) to |result|.
+1. Return |result|.
+
+</div>
+
+<h4 id="js-exceptions">JavaScript exceptions</h4>
+
 The <dfn>JavaScript exception tag</dfn> is an [=exnref/exception tag=] reserved by this
 specification to distinguish exceptions originating from JavaScript.
 
-Issue: Should it be possible for `br_on_exn` to extract the payload from an exception with this tag.
+Issue: Should it be possible for `br_on_exn` to extract the payload from an exception with this tag?
 
 <div algorithm>
 
-To <dfn for=WebAssembly>throw</dfn> a WebAssembly value |payload| given an [=exception tag=] |tag|,
-perform the following steps:
+To <dfn for=WebAssembly>throw</dfn> an [=exnref=] |exception|, perform the following steps:
 
-1. Let |exception| be a new [=exnref=] value with |payload| and |tag|.
 1. Unwind the stack until reaching the *catching try block*.
 1. Push |exception| onto the operand stack.
 1. Transfer control to the catch block.
