Skip to content

Commit

Permalink
Update explainer on stack trace support in JS API
Browse files Browse the repository at this point in the history
This updates the explainer on
- We add stack trace option to `Exception` class in the JS API
- `Exception` can contain an optional `externref` to carry a stack trace
- `Exception` is not a subclass of JS `Error`

The WebIDL syntax is suggested by @eqrion in
WebAssembly#183 (comment)
and
WebAssembly#183 (comment).

Addresses WebAssembly#183 and WebAssembly#189.
  • Loading branch information
aheejin committed Feb 4, 2022
1 parent 76419ef commit b5349ab
Showing 1 changed file with 22 additions and 8 deletions.
30 changes: 22 additions & 8 deletions proposals/exception-handling/Exceptions.md
Original file line number Diff line number Diff line change
Expand Up @@ -394,13 +394,6 @@ within `()` after `delegate`s are the label operands in immediate values.

### JS API

#### Stack traces

When an exception is thrown, the runtime will pop the stack across function
calls until a corresponding, enclosing try block is found. Some runtimes,
especially web VMs may also associate a stack trace that can be used to report
uncaught exceptions. However, the details of this are left to the embedder.

#### Traps

The `catch`/`catch_all` instruction catches exceptions generated by the `throw`
Expand Down Expand Up @@ -455,6 +448,21 @@ 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.

The `Exception` constructor can take an optional `ExceptionOptions` argument,
which can optionally contain `traceStack` entry. When `traceStack` is `true`,
web VMs can attach a stack trace string to `Exception.stack` field, as in
JavaScript's `Error` class. While `Exception` is not a subclass of JavaScript's
`Error` and it can be used to represent normal control flow constructs,
`traceStack` field can be set when we use it to represent errors. The format of
stack trace strings conform to the [WebAssembly stack trace
conventions](https://webassembly.github.io/spec/web-api/index.html#conventions).
When `ExceptionOption` is not provided or it does not contain `traceStack`
entry, `traceStack` is considered `false` by default.

To preserve stack trace info when crossing the JS to Wasm boundary, `Exception`
can internally contain an optional `externref` value containing a stack trace
string, which is propagated when caught by `catch` and rethrown by `rethrow`.

More formally, the added interfaces look like the following:

```WebIDL
Expand All @@ -464,11 +472,17 @@ interface Tag {
TagType type();
};
[LegacyNamespace=WebAssembly, Exposed=(Window,Worker,Worklet)]
dictionary ExceptionOptions {
optional boolean traceStack;
};
[LegacyNamespace=WebAssembly, Exposed=(Window,Worker,Worklet)]
interface Exception {
constructor(Tag tag, sequence<any> payload);
constructor(Tag tag, sequence<any> payload, optional ExceptionOptions options);
any getArg(Tag tag, unsigned long index);
boolean is(Tag tag);
readonly attribute (DOMString or undefined) stack;
};
```

Expand Down

0 comments on commit b5349ab

Please sign in to comment.