Skip to content
This repository was archived by the owner on Apr 25, 2025. It is now read-only.

[js-api] Add description of interface additions to overview document #154

Merged
merged 3 commits into from
Jun 24, 2021
Merged
Changes from 1 commit
Commits
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
30 changes: 30 additions & 0 deletions proposals/exception-handling/Exceptions.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Why is this check necessary?

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I believe the issue is that it would give JS capabilities that the Wasm semantics is not intended to have. Specifically Wasm code cannot ever extract the values for a thrown exception if it doesn't have the tag for it. But if JS could do this via getArg then Wasm could also do it by calling out to JS.

(original discussion of this check is here #109 (comment))


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<any> 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
Expand Down