[js-api] Add support for exceptions.

document/js-api/index.bs

@@ -181,6 +181,12 @@ urlPrefix: https://webassembly.github.io/spec/core/; spec: WebAssembly; type: df
 urlPrefix: https://heycam.github.io/webidl/; spec: WebIDL
     type: dfn
         text: create a namespace object; url: create-a-namespace-object
+
+urlPrefix: https://webassembly.github.io/reference-types/core/; spec: WebAssembly (reference types); type: dfn
+    url: exec/runtime.html#values
+        text: ref.extern
+urlPrefix: https://webassembly.github.io/reference-types/js-api/; spec: WebAssembly JS API (reference types); type: dfn
+    text: retrieving an extern value; url: #retrieving-an-extern-value
 </pre>
 
 <pre class='link-defaults'>
@@ -727,6 +733,8 @@ interface Table {
 };
 </pre>
 
+Issue: Should we support putting [=exnref=] values in tables?
+
 <div>
 A {{Table}} object represents a single [=table instance=]
 which can be simultaneously referenced by multiple {{Instance}} objects. Each
@@ -995,6 +1003,14 @@ 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 empty, return undefined.
     1. Otherwise, return [=ToJSValue=](|v|), where |v| is the singular element of |ret|.
 </div>
@@ -1024,7 +1040,9 @@ Note: Exported Functions do not have a \[[Construct]] method and thus it is not
     1. Let |hostfunc| be a [=host function=] which performs the following steps when called with arguments |arguments|:
         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 trigger a WebAssembly trap, and propagate |result|.\[[Value]] to the enclosing JavaScript.
+        1. If |result|.\[[Type]] is <emu-const>throw</emu-const>, then:
+            1. Let |exception| be [=ToWebAssemblyValue=](|result|.\[[Value]], [=anyref=]).
+            1. [=WebAssembly/Throw=] |exception| with the [=JavaScript exception tag=].
         1. Otherwise, return |result|.\[[Value]].
     1. Let |store| be the [=surrounding agent=]'s [=associated store=].
     1. Let (|store|, |funcaddr|) be [=func_alloc=](|store|, |functype|, |hostfunc|).
@@ -1096,6 +1114,32 @@ The algorithm <dfn>ToWebAssemblyValue</dfn>(|v|, |type|, |error|) coerces a Java
 </div>
 
 
+<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>
+(whose type is dependent on the value of the [=exnref/exception tag=]).
+The concrete representation of values of this type is undefined.
+
+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.
+
+<div algorithm>
+
+To <dfn for=WebAssembly>throw</dfn> a WebAssembly value |payload| given an [=exception tag=] |tag|,
+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.
+
+Note: This algorithm is expected to be moved into the core specification.
+
+</div>
+
 <h3 id="error-objects">Error Objects</h3>
 
 WebAssembly defines the following Error classes: <dfn exception>CompileError</dfn>, <dfn exception>LinkError</dfn>, and <dfn exception>RuntimeError</dfn>.