Editorial review: Document Wasm JS Promise integration#44484
Conversation
github-actions
Bot
added
Content:wasm
chrisdavidmills
changed the title
eqrion
left a comment
eqrion
left a comment
There was a problem hiding this comment.
LGTM. Also, I think you're missing a page for WebAssembly.SuspendError [1] It's essentially the same thing as WebAssembly.CompileError, so I think you could just re-use that page. I've also mentioned the one place we throw a SuspendError.
[1] https://webassembly.github.io/js-promise-integration/js-api/#exceptiondef-suspenderror
| ### Return value | ||
|
|
||
| A `Promise` that fulfills with the return value of the exported function. | ||
|
|
||
| ### Exceptions |
There was a problem hiding this comment.
WebAssembly.promising actually returns a new function that wraps the original one and can be called. The resulting wrapper function takes the same arguments as the wrapped function, but returns a promise instead of the results.
So you do:
let original = wasmInstance.exports.foo;
let promisingWrapper = WebAssembly.promising(original);
assert(promisingWrapper instanceof Function);
assert(promisingWrapper(...) instanceof Promise);
There was a problem hiding this comment.
Cool, makes sense. I updated it to:
A function that wraps the original function passed into the
promising()call, and can itself be called. The wrapper function takes the same arguments as the wrapped function, and returns a promise that fulfills with the wrapped function's results.
| sidebar: webassemblysidebar | ||
| --- | ||
|
|
||
| The **`WebAssembly.Suspending()`** constructor creates a new [`Suspending`](/en-US/docs/WebAssembly/Reference/JavaScript_interface/Suspending) object instance representing a suspending function. |
There was a problem hiding this comment.
It's probably worth adding that the only purpose of WebAssembly.Suspending is to mark which imported functions are suspending functions. You can't do anything with a Suspending interface except pass it into the imports object for a wasm module. It's a weird design, but the least bad of the options we could find.
There was a problem hiding this comment.
I've added a note to the main WebAssembly.Suspending page rather than the constructor page, as I thought it was a better location:
Note
The only purpose of WebAssembly.Suspending is to mark which imported functions are suspending functions when passing them into a Wasm module imports object.
| }; | ||
| ``` | ||
|
|
||
| This creates a suspending function. No changes are necessary to use it inside the Wasm module: when it is called, execution is suspended until the `Promise` resolves, then resumed with the resolving value available on the stack. However, when exporting a Wasm function that relies on the suspending imported function back to the JavaScript host, you need to wrap the export in a `WebAssembly.promising()` call: |
There was a problem hiding this comment.
It might be good to mention that if you don't wrap the export in WebAssembly.promising, then you will get a WebAssembly.SuspendError when you try to suspend.
There was a problem hiding this comment.
OK, I've added an entry to the WebAssembly.Suspending() constructor's "Exceptions" section that reads:
WebAssembly.SuspendError- : The corresponding exported function was not wrapped in a
WebAssembly.promising()call.
- : The corresponding exported function was not wrapped in a
Comments answered, |
Awesome, cheers for the review! @pepelsbey, do you have time to review this one? |
Sure! Is it an editorial review now? I would wait for the technical one to be over first. |
chrisdavidmills
changed the title
Oops, yeah, sorry; marked as editorial now. |
pepelsbey
left a comment
pepelsbey
left a comment
There was a problem hiding this comment.
Looks good! Thank you 🙂
See suggestion below. Regarding the console.log(e instanceof…
I found a four more non-global WebAssembly demos that would fail if not prefixed with Webassembly: search for console.log(e instanceof in files/en-us/webassembly.
- files/en-us/webassembly/reference/javascript_interface/compileerror/compileerror/index.md
- files/en-us/webassembly/reference/javascript_interface/compileerror/index.md
- files/en-us/webassembly/reference/javascript_interface/linkerror/index.md
- files/en-us/webassembly/reference/javascript_interface/linkerror/linkerror/index.md
These two are prefixed:
- files/en-us/webassembly/reference/javascript_interface/runtimeerror/index.md
- files/en-us/webassembly/reference/javascript_interface/runtimeerror/runtimeerror/index.md
…ng_static/index.md Co-authored-by: Vadim Makeev <hi@pepelsbey.dev>
…ing/index.md Co-authored-by: Vadim Makeev <hi@pepelsbey.dev>
Co-authored-by: Vadim Makeev <hi@pepelsbey.dev>
…ng_static/index.md Co-authored-by: Vadim Makeev <hi@pepelsbey.dev>
…error/index.md Co-authored-by: Vadim Makeev <hi@pepelsbey.dev>
…error/suspenderror/index.md Co-authored-by: Vadim Makeev <hi@pepelsbey.dev>
Lovely, thanks for the reviews, @pepelsbey and @eqrion. |
4 participants
Description
Firefox 153 adds support for WebAssembly JS Promise Integration (JS-PI): see https://bugzilla.mozilla.org/show_bug.cgi?id=2044809.
This PR adds:
WebAssembly.Suspendingreference.WebAssembly.promising()reference.WebAssembly.SuspendErrorreference.Motivation
Additional details
Related issues and pull requests
See #44468 for tracking.