[js-api] Add specification. #86

Ms2ger · 2019-07-16T11:29:43Z

No description provided.

Ms2ger · 2019-07-17T08:34:05Z

This is based on what I understand the Chromium behaviour to be; it's not clear to me if that is the current consensus.

Probably this will need some text changes after the changes to func_invoke land in the core spec.

document/js-api/index.bs

Ms2ger · 2019-08-13T13:45:00Z

Any more thoughts on this, anyone?

aheejin · 2019-08-13T17:48:05Z

Could you split this PR into adding the existing base JS API and the modified part? It is hard to see the difference related to exceptions.

Ms2ger · 2019-08-14T08:14:01Z

The exceptions-related change is in the last commit.

aheejin · 2019-08-14T08:39:48Z

Thank you! But I still think splitting this is worth it, because it's possible we end up adding more commits to this, in which case it is hard to see only the related changes later. What do you think? @mstarzinger

mstarzinger · 2019-08-14T14:12:15Z

+1 on splitting out the unmodified import of of the js-api documents. Those should be uncontroversial and we could land them right away. All further delta are then easier to see and review I think.

Ms2ger · 2019-08-21T09:28:12Z

I've rebased and updated the PR to what I think the behaviour is; it's not very formal, but that'll need to wait until the core spec exists.

aheejin · 2019-10-31T09:02:52Z

I'm very sorry for long radio silence 😢

I think there are some issues to be resolved (regarding traps and such) before we finalize the JS API. Does this PR describe the current behavior of V8? If so, it is likely subject to change, how about waiting on landing this? I opened #89 to discuss some of the issues.

…embly#86) * Fix expected trap messages. The spec interpreter says "element segment dropped", rather than "elements segment dropped". * Fix "zero len, but dst offset out of bounds" test. Fix this test to test what it's comment says it's testing. * Add more tests for zero-length operations. * Update the Overview text to reflect the zero-length at-the-end semantics.

… (WebAssembly#87) Change the test generators to use `ref.func` and remove `passive`. At some point we'll want to remove the generators, but for let's try to maintain them.

aheejin · 2021-06-22T20:41:12Z

Is this up-to-date with the current spec? (It doesn't look like it) Are you planning to update this?

document/js-api/index.bs

ioannad

Apart from the two possible changes suggested, it LGTM.

Co-authored-by: Ioanna M Dimitriou H <[email protected]>

aheejin

Sorry that I wasn't able to review this at the time of merging! I'm not very familiar with bikeshed and WebIDL syntax, so I'm trying to understand the current EH JS API as written. Here are some questions:

aheejin · 2022-02-08T23:21:44Z

document/js-api/index.bs

+        1. If |result|.\[[Type]] is <emu-const>throw</emu-const>, then:
+            1. If |v| [=implements=] {{RuntimeException}},
+                1. Let |type| be |v|.\[[Type]].
+                1. Let |payload| be |v|.\[[Payload]].


I don't have time today to page #189 back in, but I'll try to work on it next week.

aheejin · 2022-02-09T10:09:15Z

document/js-api/index.bs

+        for: externtype
+            text: tag


Why is this externaltype/tag special and not just

text:tag

? And because they are differently defined they are used in different ways too:

externtype/table:

exception-handling/document/js-api/index.bs

Line 402 in ca2b715

1. If |externtype| is of the form [=table=] <var ignore>tabletype</var>,

externtype/tag:

exception-handling/document/js-api/index.bs

Line 407 in ca2b715

1. If |externtype| is of the form [=externtype/tag=] |attribute| <var ignore>functype</var>,

I think either way is fine, but do you think it'd be better to make them consistent? The same for external value/tag too.

It's basically namespacing - I don't recall if I had an actual conflict with "tag" or if I just thought it made more sense. I'd be happy to change the others as well, but I'd rather do that in the main spec repo directly.

aheejin · 2022-02-09T22:46:38Z

document/js-api/index.bs

+        1. If |externtype| is of the form [=externtype/tag=] |attribute| <var ignore>functype</var>,
+            1. Assert: |attribute| is [=tagtype/attribute/exception=].
+            1. If |v| does not [=implement=] {{Tag}}, throw a {{LinkError}} exception.
+            1. Let |tagaddr| be |v|.\[[Address]].


Which address is this? For tables and globals, it says |v|.\[[Table]] and |v|.[[Global]]. Is there a set of values that v contains?

This is the field set in "create a Tag object" algorithm below. The supported fields depend on the interface that the value implements, which is checked in the step above.

aheejin · 2022-02-09T23:32:56Z

document/js-api/index.bs

+            1. Let « [=ref.extern=] |externaddr| » be |payload|.
+            1. Throw the result of [=retrieving an extern value=] from |externaddr|.


Do we need these steps? Aren't these two steps cancelling each other?

I don't fully understand your question. The goal of the "JavaScript exception tag" check is to ensure an exception thrown from js → wasm → js maintains its identity.

Oh I think I was confused. I thought you apply ref.extern to the returned payload; I guess this means if the payload is the form « [=ref.extern=] |externaddr| », then we retrieve an extern value from externaddr. Right?

Yeah, exactly. If you have thoughts on how to make this destructuring assignment pattern more readable, I'd love to hear them.

aheejin · 2022-02-10T03:49:48Z

document/js-api/index.bs

 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/js-types/js-api/; spec: WebAssembly JS API (JS Type Reflection)
+    type: abstract-op; text: FromValueType; url: abstract-opdef-fromvaluetype


Where is this FromValueType? I can't find it in https://webassembly.github.io/js-types/js-api/#abstract-opdef-fromvaluetype. Also ToValueType is defined within this file; then why is only this method from the type reflection proposal?

Yeah, the publishing is broken - WebAssembly/js-types#23. js-types only needs one direction, but it seems risky to just copy/paste. I can turn the dependency in the other direction if that turns out to be helpful.

aheejin · 2022-02-10T06:33:51Z

document/js-api/index.bs

+To <dfn>create a RuntimeException object</dfn> from a [=tag address=] |tagAddress| and [=list=]
+of WebAssembly values |payload|, perform the following steps:


How are "create an Exception object" algorithm and "new Exception(exceptionTag, payload) constructor steps" algorithm different?

exception-handling/document/js-api/index.bs

Lines 1272 to 1283 in ca2b715

To <dfn>create an Exception object</dfn> from a [=tag address=] |tagAddress| and [=list=]

of WebAssembly values |payload|, perform the following steps:

1. Let |store| be the [=surrounding agent=]'s [=associated store=].

1. Let |types| be [=tag_parameters=](|store|, |tagAddress|).

1. Assert: |types|'s [=list/size=] is |payload|'s [=list/size=].

1. [=list/iterate|For each=] |value| and |resultType| of |payload| and |types|, paired linearly,

1. Assert: |value|'s type matches |resultType|.

1. Let |exception| be a [=new=] {{Exception}}.

1. Set |exception|.\[[Type]] to |tagAddress|.

1. Set |exception|.\[[Payload]] to |payload|.

1. Return |exception|.

exception-handling/document/js-api/index.bs

Lines 1289 to 1301 in ca2b715

The <dfn constructor for=Exception

lt="Exception(exceptionTag, payload)">new Exception(|exceptionTag|, |payload|)</dfn>

constructor steps are:

1. Let |store| be the [=surrounding agent=]'s [=associated store=].

1. Let |types| be [=tag_parameters=](|store|, |exceptionTag|.\[[Address]]).

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. Set **this**.\[[Type]] to |exceptionTag|.\[[Address]].

1. Set **this**.\[[Payload]] to |wasmPayload|.

Why do they exist separately?

"create an Exception object" is when you already have the wasm values; "new Exception" is the js-side constructor called from webidl. I don't see a super obvious way to share more code between them, unfortunately.

aheejin · 2022-02-10T06:34:40Z

document/js-api/index.bs

+1. Assert: |types|'s [=list/size=] is |payload|'s [=list/size=].
+1. [=list/iterate|For each=] |value| and |resultType| of |payload| and |types|, paired linearly,
+    1. Assert: |value|'s type matches |resultType|.


Here we assert for invariants, but in the constructor algorithm below we throw. What's the difference?

aheejin · 2022-02-10T06:35:30Z

document/js-api/index.bs

+    1. Assert: |value|'s type matches |resultType|.
+1. Let |exception| be a [=new=] {{RuntimeException}}.
+1. Set |exception|.\[[Type]] to |tagAddress|.
+1. Set |exception|.\[[Payload]] to |payload|.


In the constructor algorithm below, we run ToWebAssemblyValue on each payload value, but here we do not. What's the difference?

aheejin · 2022-02-10T07:11:27Z

document/js-api/index.bs

+For any [=associated store=] |store|, the result of
+[=tag_parameters=](|store|, [=JavaScript exception tag=]) must be « [=externref=] ».
+
+ Issue: Should it be possible for `catch <JS-exception-tag>` to extract the payload from an exception with this tag?


Why should it be not possible? Wasm's catch wouldn't be able to examine the internals of the externref payload, but that's true for all externrefs, no?

I don't feel strongly either way, but to support it, we need to expose the tag to core wasm somehow, right? I'm a bit fuzzy on how that would work.

I guess the only way wasm can catch JS exceptions is to import the JS exception tag. Can we define the tag in the JS side and make wasm import it?

Ping in case this was missed :) Do you think this would work?

aheejin · 2022-02-10T07:12:52Z

document/js-api/index.bs

+To <dfn for=WebAssembly>throw</dfn> with a [=tag address=] |type| and matching [=list=] of WebAssembly values |payload|, perform the following steps:
+
+1. Unwind the stack until reaching the *catching try block* given |type|.
+1. Invoke the catch block with |payload|.
+
+Note: This algorithm is expected to be moved into the core specification.


Is this specific to JS exceptions?

No, this is supposed to be basically equivalent to the throw instruction in core wasm. The core spec wasn't finished when I wrote this, so I put this here so I had an api to use in the rest of the spec.

Ms2ger

Thanks for the reply, I hope this clarifies. Let me know if anything is still confusing.

Ms2ger · 2022-02-10T16:37:54Z

document/js-api/index.bs

+        for: externtype
+            text: tag


It's basically namespacing - I don't recall if I had an actual conflict with "tag" or if I just thought it made more sense. I'd be happy to change the others as well, but I'd rather do that in the main spec repo directly.

Ms2ger · 2022-02-10T16:40:08Z

document/js-api/index.bs

 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/js-types/js-api/; spec: WebAssembly JS API (JS Type Reflection)
+    type: abstract-op; text: FromValueType; url: abstract-opdef-fromvaluetype


Yeah, the publishing is broken - WebAssembly/js-types#23. js-types only needs one direction, but it seems risky to just copy/paste. I can turn the dependency in the other direction if that turns out to be helpful.

Ms2ger · 2022-02-10T16:41:33Z

document/js-api/index.bs

+        1. If |externtype| is of the form [=externtype/tag=] |attribute| <var ignore>functype</var>,
+            1. Assert: |attribute| is [=tagtype/attribute/exception=].
+            1. If |v| does not [=implement=] {{Tag}}, throw a {{LinkError}} exception.
+            1. Let |tagaddr| be |v|.\[[Address]].


This is the field set in "create a Tag object" algorithm below. The supported fields depend on the interface that the value implements, which is checked in the step above.

Ms2ger · 2022-02-10T16:43:51Z

document/js-api/index.bs

+            1. Let « [=ref.extern=] |externaddr| » be |payload|.
+            1. Throw the result of [=retrieving an extern value=] from |externaddr|.


I don't fully understand your question. The goal of the "JavaScript exception tag" check is to ensure an exception thrown from js → wasm → js maintains its identity.

Ms2ger · 2022-02-10T16:53:32Z

document/js-api/index.bs

+To <dfn>create a RuntimeException object</dfn> from a [=tag address=] |tagAddress| and [=list=]
+of WebAssembly values |payload|, perform the following steps:


"create an Exception object" is when you already have the wasm values; "new Exception" is the js-side constructor called from webidl. I don't see a super obvious way to share more code between them, unfortunately.

Ms2ger · 2022-02-10T16:55:18Z

document/js-api/index.bs

+For any [=associated store=] |store|, the result of
+[=tag_parameters=](|store|, [=JavaScript exception tag=]) must be « [=externref=] ».
+
+ Issue: Should it be possible for `catch <JS-exception-tag>` to extract the payload from an exception with this tag?


I don't feel strongly either way, but to support it, we need to expose the tag to core wasm somehow, right? I'm a bit fuzzy on how that would work.

Ms2ger · 2022-02-10T16:56:49Z

document/js-api/index.bs

+To <dfn for=WebAssembly>throw</dfn> with a [=tag address=] |type| and matching [=list=] of WebAssembly values |payload|, perform the following steps:
+
+1. Unwind the stack until reaching the *catching try block* given |type|.
+1. Invoke the catch block with |payload|.
+
+Note: This algorithm is expected to be moved into the core specification.


No, this is supposed to be basically equivalent to the throw instruction in core wasm. The core spec wasn't finished when I wrote this, so I put this here so I had an api to use in the rest of the spec.

aheejin · 2022-02-12T01:41:34Z

@Ms2ger Thanks for the explanation!

mstarzinger reviewed Jul 17, 2019

View reviewed changes

document/js-api/index.bs Outdated Show resolved Hide resolved

Ms2ger mentioned this pull request Aug 6, 2019

Initial tests for WebAssembly exceptions. web-platform-tests/wpt#18294

Merged

Ms2ger force-pushed the spec-js-api branch 2 times, most recently from 58675fc to 1fe9cff Compare August 21, 2019 08:49

ioannad mentioned this pull request Dec 23, 2019

Merge 'document/' directory of 'WebAssembly/reference-types/master', excluding 'document/js-api/'. #91

Merged

RossTate mentioned this pull request Apr 23, 2020

[js-api] Should rethrow/br_on_exn trap on undefined? #109

Closed

Ms2ger force-pushed the spec-js-api branch 2 times, most recently from e841f94 to 789acfa Compare May 22, 2020 15:20

ioannad pushed a commit to ioannad/exception-handling that referenced this pull request Jun 6, 2020

[test] Update JS harnesses to match interpreter harness (WebAssembly#86)

c0f30ca

Ms2ger force-pushed the spec-js-api branch from 7b5c5fc to 5604392 Compare June 16, 2020 07:33

takikawa mentioned this pull request Mar 31, 2021

Details of the JS API for exception handling #150

Closed

takikawa mentioned this pull request May 25, 2021

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

Merged

Ms2ger force-pushed the spec-js-api branch 2 times, most recently from 114f619 to 0326ded Compare June 10, 2021 15:54

aheejin mentioned this pull request Jun 22, 2021

Advance to Phase 3? #163

Closed

Ms2ger force-pushed the spec-js-api branch from 0326ded to deb2800 Compare June 23, 2021 07:14

ioannad reviewed Jun 23, 2021

View reviewed changes

document/js-api/index.bs Outdated Show resolved Hide resolved

ioannad reviewed Jun 23, 2021

View reviewed changes

document/js-api/index.bs Outdated Show resolved Hide resolved

ioannad approved these changes Jun 23, 2021

View reviewed changes

[js-api] Add support for exceptions.

475f2d9

Co-authored-by: Ioanna M Dimitriou H <[email protected]>

Ms2ger force-pushed the spec-js-api branch from 91c9394 to 475f2d9 Compare June 23, 2021 14:48

Ms2ger merged commit 7159387 into WebAssembly:master Jun 23, 2021

Ms2ger deleted the spec-js-api branch June 23, 2021 14:59

aheejin reviewed Feb 10, 2022

View reviewed changes

Ms2ger commented Feb 10, 2022

View reviewed changes

		1. Let « [=ref.extern=] \|externaddr\| » be \|payload\|.
		1. Throw the result of [=retrieving an extern value=] from \|externaddr\|.

		To <dfn>create a RuntimeException object</dfn> from a [=tag address=] \|tagAddress\| and [=list=]
		of WebAssembly values \|payload\|, perform the following steps:

	To <dfn>create an Exception object</dfn> from a [=tag address=] \|tagAddress\| and [=list=]
	of WebAssembly values \|payload\|, perform the following steps:

	1. Let \|store\| be the [=surrounding agent=]'s [=associated store=].
	1. Let \|types\| be [=tag_parameters=](\|store\|, \|tagAddress\|).
	1. Assert: \|types\|'s [=list/size=] is \|payload\|'s [=list/size=].
	1. [=list/iterate\|For each=] \|value\| and \|resultType\| of \|payload\| and \|types\|, paired linearly,
	1. Assert: \|value\|'s type matches \|resultType\|.
	1. Let \|exception\| be a [=new=] {{Exception}}.
	1. Set \|exception\|.\[[Type]] to \|tagAddress\|.
	1. Set \|exception\|.\[[Payload]] to \|payload\|.
	1. Return \|exception\|.

	The <dfn constructor for=Exception
	lt="Exception(exceptionTag, payload)">new Exception(\|exceptionTag\|, \|payload\|)</dfn>
	constructor steps are:

	1. Let \|store\| be the [=surrounding agent=]'s [=associated store=].
	1. Let \|types\| be [=tag_parameters=](\|store\|, \|exceptionTag\|.\[[Address]]).
	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. Set this.\[[Type]] to \|exceptionTag\|.\[[Address]].
	1. Set this.\[[Payload]] to \|wasmPayload\|.

[js-api] Add specification. #86

[js-api] Add specification. #86

Conversation

Ms2ger commented Jul 16, 2019

Ms2ger commented Jul 17, 2019

Ms2ger commented Aug 13, 2019

aheejin commented Aug 13, 2019 • edited Loading

Ms2ger commented Aug 14, 2019

aheejin commented Aug 14, 2019

mstarzinger commented Aug 14, 2019

Ms2ger commented Aug 21, 2019

aheejin commented Oct 31, 2019

aheejin commented Jun 22, 2021

ioannad left a comment

Choose a reason for hiding this comment

aheejin left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Ms2ger left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

aheejin commented Feb 12, 2022

aheejin commented Aug 13, 2019 •

edited

Loading