From 274a08631e9af317e8ad9f76c656653fa256e943 Mon Sep 17 00:00:00 2001 From: Asumu Takikawa Date: Tue, 25 May 2021 15:56:37 -0700 Subject: [PATCH 1/3] Add JS API interfaces to overview --- proposals/exception-handling/Exceptions.md | 30 ++++++++++++++++++++++ 1 file changed, 30 insertions(+) diff --git a/proposals/exception-handling/Exceptions.md b/proposals/exception-handling/Exceptions.md index fecb3b15..b03367a5 100644 --- a/proposals/exception-handling/Exceptions.md +++ b/proposals/exception-handling/Exceptions.md @@ -395,6 +395,36 @@ specially mark non-catchable exceptions. be intercepted in JS, and types of exceptions generated from stack overflow and out of memory are implementation-defined.) +#### API additions + +The following additional classes are added to the JS API in order to allow JavaScript to interact with WebAssembly exceptions: + + * `WebAssembly.Exception` + * `WebAssembly.RuntimeException`. + +The `WebAssembly.Exception` class represents an exception defined in the event section and exported from a WebAssembly module. It allows querying the type of an exception following the [JS type reflection proposal](https://github.com/WebAssembly/js-types/blob/master/proposals/js-types/Overview.md). Constructing an instance of `Exception` creates a fresh exception tag, and the new exception can be passed to a WebAssembly module as an import. + +The `WebAssembly.RuntimeException` class represents an exception thrown from WebAssembly, or an exception that is constructed in JavaScript and is to be thrown to a WebAssembly exception handler. The `RuntimeException` constructor accepts an `Exception` argument and a sequence of arguments for the exception's data fields. The `Exception` argument determines the exception tag to use. The data field arguments must match the types specified by the `Exception`'s type. The `is` method can be used to query if the `RuntimeException` matches a given `Exception`'s exception tag. The `getArg` method allows access to the data fields of a `RuntimeException` if an `Exception` is passed with a matching exception tag. This last check ensures that without access to a WebAssembly module's exported exception, the associated data fields cannot be read. + +More formally, the added interfaces look like the following: + +``` +[LegacyNamespace=WebAssembly, Exposed=(Window,Worker,Worklet)] +interface Exception { + constructor(ExceptionType type); + ExceptionType type(); +}; + +[LegacyNamespace=WebAssembly, Exposed=(Window,Worker,Worklet)] +interface RuntimeException { + constructor(Exception exceptionType, sequence payload); + any getArg(Exception exceptionType, unsigned long index); + boolean is(Exception exceptionType); +}; +``` + +Where `type ExceptionType = {parameters: ValueType[]}`, following the format of the type reflection proposal (`ExceptionType` corresponds to a `FunctionType` without a `results` property). + ## Changes to the text format This section describes change in the [instruction syntax From 49daf997a7550f7b9e4442e2271e838a8f987cf7 Mon Sep 17 00:00:00 2001 From: Asumu Takikawa Date: Wed, 2 Jun 2021 17:52:33 -0700 Subject: [PATCH 2/3] Address feedback --- proposals/exception-handling/Exceptions.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/proposals/exception-handling/Exceptions.md b/proposals/exception-handling/Exceptions.md index b03367a5..aae324e4 100644 --- a/proposals/exception-handling/Exceptions.md +++ b/proposals/exception-handling/Exceptions.md @@ -408,7 +408,7 @@ The `WebAssembly.RuntimeException` class represents an exception thrown from Web More formally, the added interfaces look like the following: -``` +```WebIDL [LegacyNamespace=WebAssembly, Exposed=(Window,Worker,Worklet)] interface Exception { constructor(ExceptionType type); @@ -417,9 +417,9 @@ interface Exception { [LegacyNamespace=WebAssembly, Exposed=(Window,Worker,Worklet)] interface RuntimeException { - constructor(Exception exceptionType, sequence payload); - any getArg(Exception exceptionType, unsigned long index); - boolean is(Exception exceptionType); + constructor(Exception tag, sequence payload); + any getArg(Exception tag, unsigned long index); + boolean is(Exception tag); }; ``` From 030595d11d44bd19512fd3e9d71697b0491d9a42 Mon Sep 17 00:00:00 2001 From: Asumu Takikawa Date: Sat, 12 Jun 2021 11:16:03 -0700 Subject: [PATCH 3/3] Update for event -> tag changes --- proposals/exception-handling/Exceptions.md | 26 ++++++++++++---------- 1 file changed, 14 insertions(+), 12 deletions(-) diff --git a/proposals/exception-handling/Exceptions.md b/proposals/exception-handling/Exceptions.md index aae324e4..0d8270da 100644 --- a/proposals/exception-handling/Exceptions.md +++ b/proposals/exception-handling/Exceptions.md @@ -399,31 +399,33 @@ out of memory are implementation-defined.) The following additional classes are added to the JS API in order to allow JavaScript to interact with WebAssembly exceptions: - * `WebAssembly.Exception` - * `WebAssembly.RuntimeException`. + * `WebAssembly.Tag` + * `WebAssembly.Exception`. -The `WebAssembly.Exception` class represents an exception defined in the event section and exported from a WebAssembly module. It allows querying the type of an exception following the [JS type reflection proposal](https://github.com/WebAssembly/js-types/blob/master/proposals/js-types/Overview.md). Constructing an instance of `Exception` creates a fresh exception tag, and the new exception can be passed to a WebAssembly module as an import. +The `WebAssembly.Tag` class represents a typed tag defined in the tag section and exported from a WebAssembly module. It allows querying the type of a tag following the [JS type reflection proposal](https://github.com/WebAssembly/js-types/blob/master/proposals/js-types/Overview.md). Constructing an instance of `Tag` creates a fresh tag, and the new tag can be passed to a WebAssembly module as a tag import. -The `WebAssembly.RuntimeException` class represents an exception thrown from WebAssembly, or an exception that is constructed in JavaScript and is to be thrown to a WebAssembly exception handler. The `RuntimeException` constructor accepts an `Exception` argument and a sequence of arguments for the exception's data fields. The `Exception` argument determines the exception tag to use. The data field arguments must match the types specified by the `Exception`'s type. The `is` method can be used to query if the `RuntimeException` matches a given `Exception`'s exception tag. The `getArg` method allows access to the data fields of a `RuntimeException` if an `Exception` is passed with a matching exception tag. This last check ensures that without access to a WebAssembly module's exported exception, the associated data fields cannot be read. +In the future, `WebAssembly.Tag` may be used for other proposals that require a typed tag and its constructor may be extended to accept other types and/or a tag attribute to differentiate them from tags used for exceptions. + +The `WebAssembly.Exception` class represents an exception thrown from WebAssembly, or an exception that is constructed in JavaScript and is to be thrown to a WebAssembly exception handler. The `Exception` constructor accepts a `Tag` argument and a sequence of arguments for the exception's data fields. The `Tag` argument determines the exception tag to use. The data field arguments must match the types specified by the `Tag`'s type. The `is` method can be used to query if the `Exception` matches a given tag. The `getArg` method allows access to the data fields of a `Exception` if a matching tag is given. This last check ensures that without access to a WebAssembly module's exported exception tag, the associated data fields cannot be read. More formally, the added interfaces look like the following: ```WebIDL [LegacyNamespace=WebAssembly, Exposed=(Window,Worker,Worklet)] -interface Exception { - constructor(ExceptionType type); - ExceptionType type(); +interface Tag { + constructor(TagType type); + TagType type(); }; [LegacyNamespace=WebAssembly, Exposed=(Window,Worker,Worklet)] -interface RuntimeException { - constructor(Exception tag, sequence payload); - any getArg(Exception tag, unsigned long index); - boolean is(Exception tag); +interface Exception { + constructor(Tag tag, sequence payload); + any getArg(Tag tag, unsigned long index); + boolean is(Tag tag); }; ``` -Where `type ExceptionType = {parameters: ValueType[]}`, following the format of the type reflection proposal (`ExceptionType` corresponds to a `FunctionType` without a `results` property). +Where `type TagType = {parameters: ValueType[]}`, following the format of the type reflection proposal (`TagType` corresponds to a `FunctionType` without a `results` property). `TagType` could be extended in the future for other proposals that require a richer type specification. ## Changes to the text format