1417583 - Update WebAssembly tutorials and demos to utilize streaming methods

Status: RESOLVED FIXED

(Developer Documentation Graveyard :: API: DOM, enhancement, P2)

Description

[Chris Mills [:cmills]]

Now that compileStreaming()/instantiateStreaming() have been implemented, the Web has a much more convenient way of importing WASM modules. These methods were introduced in Firefox 58; when this version rides the trains to release, that will signal a good time to update our WebAssembly tutorials to use the new methods.

This bug will act as a reminder to do so!

For example, we can remove the fetchAndInstantiate() helper function (see https://github.com/mdn/webassembly-examples/blob/master/wasm-utils.js)

And we want to generally update our general examples (e.g. see https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/WebAssembly) to use instantiateStreaming(fetch('simple.wasm')) instead of the current two-step process.  This is the happy path we want everyone using by default (best performance in multiple dimensions, and moreso over time).

https://developer.mozilla.org/en-US/docs/WebAssembly/Loading_and_running also needs an update.

And probably other docs too.

Comment 1

[Luke Wagner [:luke]]

(Streaming APIs are now live.)

Comment 2

[Chris Mills [:cmills]]

OK! I have finished updating all the tuts, ref docs, and code examples to use the streaming methods where appropriate. 

Let me know if you see anything else that doesn't look quite right.

Luke, one thing in particular that I'd love you to cast your eye over quickly is your IDB caching code for wasm modules:

https://github.com/mdn/webassembly-examples/blob/master/wasm-utils.js

I updated it to get rid of the fetchAndInstantiate() helper altogether, and just use instantiateStreaming(). I think it works OK, but I'd love a 2nd pair of eyes.

Thanks!

Comment 3

[Luke Wagner [:luke]]

Thanks and great work!

OOC, is the "This is an experimental technology" banner used for all features that are effectively standardized, just not available in all browsers yet?

A few nits on a few pages:

https://developer.mozilla.org/en-US/docs/WebAssembly/Using_the_JavaScript_API
 - Could we put the instantiateStreaming() example first (before the ArrayBuffer API) and remove the compileStreaming() source/link?
 - Unrelated, but it looks like we can remove some boilerplate about the 'javascript.options.wasm' pref now that it's totally enabled everywhere and in other browsers

https://developer.mozilla.org/en-US/docs/WebAssembly/Loading_and_running
 - Similarly, could instantiateStreaming() go first (in the Using Fetch section, the header is fine)?

https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/WebAssembly/instantiate
 - Could you change it to no longer say instantiate() is the primary way to compile and instead forward to instantiateStream()?

https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/WebAssembly/instantiateStreaming
 - Could you change the header to indicate this is now the most optimized way to load wasm code?

https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/WebAssembly/Instance
 - Could you update where it says "the primary way to get an Instance" to point to instantiateStreaming?

> Luke, one thing in particular that I'd love you to cast your eye over
> quickly is your IDB caching code for wasm modules:
> 
> https://github.com/mdn/webassembly-examples/blob/master/wasm-utils.js

I made a tiny fix and a few tweaks to the code:
  https://github.com/mdn/webassembly-examples/commit/77d8ec2f79dea462036fb361b7b99cb793ab1c2a
and the Caching MDN page.  Seems to run great in my browser now.

And lastly, one *completely* related feature request (while I was scanning everything): for all pages under /docs/WebAssembly, the sidebar has links to both other tutorials and the JS API references, however for all pages under /docs/Web/JavaScript/Reference/Global_Objects/WebAssembly, the sidebar only shows JS API references (no tutorial links).  For symmetry, and to help people discover out most-excellent tutorial content, could we get the a Tutorials list in the JS API sidebar?

Comment 4

[Chris Mills [:cmills]]

(In reply to Luke Wagner [:luke] from comment #3)
> Thanks and great work!

You're welcome. Thanks for the review!

> 
> OOC, is the "This is an experimental technology" banner used for all
> features that are effectively standardized, just not available in all
> browsers yet?

Our definition is quite similar to the W3C definition, see here:
https://developer.mozilla.org/en-US/docs/MDN/Contribute/Guidelines/Conventions_definitions#Experimental

I think WebAssembly is advanced enough in standardization and implementation to not be considered experimental anymore, so I've removed the remaining experimental banners and tags from these pages.

> 
> A few nits on a few pages:
> 
> https://developer.mozilla.org/en-US/docs/WebAssembly/Using_the_JavaScript_API
>  - Could we put the instantiateStreaming() example first (before the
> ArrayBuffer API) and remove the compileStreaming() source/link?

Good idea - I've rearranged it to sort this out.

>  - Unrelated, but it looks like we can remove some boilerplate about the
> 'javascript.options.wasm' pref now that it's totally enabled everywhere and
> in other browsers

Agreed - removed.
 
> https://developer.mozilla.org/en-US/docs/WebAssembly/Loading_and_running
>  - Similarly, could instantiateStreaming() go first (in the Using Fetch
> section, the header is fine)?

Done.

> 
> https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/
> Global_Objects/WebAssembly/instantiate
>  - Could you change it to no longer say instantiate() is the primary way to
> compile and instead forward to instantiateStream()?

I've added an important note block near the top of the article, to make this clear.

> 
> https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/
> Global_Objects/WebAssembly/instantiateStreaming
>  - Could you change the header to indicate this is now the most optimized
> way to load wasm code?

Done.

> 
> https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/
> Global_Objects/WebAssembly/Instance
>  - Could you update where it says "the primary way to get an Instance" to
> point to instantiateStreaming?

Done.

> 
> > Luke, one thing in particular that I'd love you to cast your eye over
> > quickly is your IDB caching code for wasm modules:
> > 
> > https://github.com/mdn/webassembly-examples/blob/master/wasm-utils.js
> 
> I made a tiny fix and a few tweaks to the code:
>  
> https://github.com/mdn/webassembly-examples/commit/
> 77d8ec2f79dea462036fb361b7b99cb793ab1c2a
> and the Caching MDN page.  Seems to run great in my browser now.

Cool, this looks fab, thanks.

> 
> And lastly, one *completely* related feature request (while I was scanning
> everything): for all pages under /docs/WebAssembly, the sidebar has links to
> both other tutorials and the JS API references, however for all pages under
> /docs/Web/JavaScript/Reference/Global_Objects/WebAssembly, the sidebar only
> shows JS API references (no tutorial links).  For symmetry, and to help
> people discover out most-excellent tutorial content, could we get the a
> Tutorials list in the JS API sidebar?

I am not sure how to do this. The trouble is that the tutorial pages use a separate sidebar macro, whereas the reference pages use the general JSSidebar macro that just deals with ALL built-in JS features.

Florian, you are a bit of a sidebar guru; is there any way to add some additional links to the sidebar on the WebAssembly object reference pages without breaking the JSSidebar?

Comment 5

[Luke Wagner [:luke]]

I'll close this bug since it's primary objective is now accomplished.  Quite happy to have continued discussion on the tangent I started about the sidebar in this bug or a GH issue or wherever.