Add wasm in web worker example (#2556)

This commit adds a parallel execution example in which we spawn a web
worker with `web_sys`, run WASM code in the web worker and interact
between the main thread and the web worker.

It is intended to add an easy starting point for parallel execution
with WASM, complementing the more involved parallel raytrace example.

Related to GitHub issue #2549

Co-authored-by: Simon Gasse <[email protected]>

Author: sgasse

Cargo.toml

@@ -80,6 +80,7 @@ members = [
   "examples/todomvc",
   "examples/wasm-in-wasm",
   "examples/wasm-in-wasm-imports",
+  "examples/wasm-in-web-worker",
   "examples/wasm2js",
   "examples/webaudio",
   "examples/webgl",

azure-pipelines.yml

@@ -178,7 +178,7 @@ jobs:
       - script: mv _package.json package.json && npm install && rm package.json
         displayName: "run npm install"
       - script: |
-          for dir in `ls examples | grep -v README | grep -v asm.js | grep -v raytrace | grep -v without-a-bundler | grep -v websockets | grep -v webxr | grep -v deno`; do
+          for dir in `ls examples | grep -v README | grep -v asm.js | grep -v raytrace | grep -v without-a-bundler | grep -v wasm-in-web-worker | grep -v websockets | grep -v webxr | grep -v deno`; do
             (cd examples/$dir &&
             ln -fs ../../node_modules . &&
             npm run build -- --output-path $BUILD_ARTIFACTSTAGINGDIRECTORY/exbuild/$dir) || exit 1;

examples/wasm-in-web-worker/Cargo.toml

@@ -0,0 +1,24 @@
+[package]
+name = "wasm-in-web-worker"
+version = "0.1.0"
+authors = ["The wasm-bindgen Developers"]
+edition = "2018"
+
+[lib]
+crate-type = ["cdylib"]
+
+[dependencies]
+wasm-bindgen = "0.2.74"
+console_error_panic_hook = { version = "0.1.6", optional = true }
+
+[dependencies.web-sys]
+version = "0.3.4"
+features = [
+    'console',
+    'Document',
+    'HtmlElement',
+    'HtmlInputElement',
+    'MessageEvent',
+    'Window',
+    'Worker',
+]

examples/wasm-in-web-worker/build.sh

@@ -0,0 +1,7 @@
+#!/bin/sh
+
+set -ex
+
+# This example requires to *not* create ES modules, therefore we pass the flag
+# `--target no-modules`
+wasm-pack build --out-dir www/pkg --target no-modules

examples/wasm-in-web-worker/src/lib.rs

@@ -0,0 +1,140 @@
+use std::cell::RefCell;
+use std::rc::Rc;
+use wasm_bindgen::prelude::*;
+use wasm_bindgen::JsCast;
+use web_sys::{console, HtmlElement, HtmlInputElement, MessageEvent, Worker};
+
+/// A number evaluation struct
+///
+/// This struct will be the main object which responds to messages passed to the
+/// worker. It stores the last number which it was passed to have a state. The
+/// statefulness is not is not required in this example but should show how
+/// larger, more complex scenarios with statefulness can be set up.
+#[wasm_bindgen]
+pub struct NumberEval {
+    number: i32,
+}
+
+#[wasm_bindgen]
+impl NumberEval {
+    /// Create new instance.
+    pub fn new() -> NumberEval {
+        NumberEval { number: 0 }
+    }
+
+    /// Check if a number is even and store it as last processed number.
+    ///
+    /// # Arguments
+    ///
+    /// * `number` - The number to be checked for being even/odd.
+    pub fn is_even(&mut self, number: i32) -> bool {
+        self.number = number;
+        match self.number % 2 {
+            0 => true,
+            _ => false,
+        }
+    }
+
+    /// Get last number that was checked - this method is added to work with
+    /// statefulness.
+    pub fn get_last_number(&self) -> i32 {
+        self.number
+    }
+}
+
+/// Run entry point for the main thread.
+#[wasm_bindgen]
+pub fn startup() {
+    // Here, we create our worker. In a larger app, multiple callbacks should be
+    // able to interact with the code in the worker. Therefore, we wrap it in
+    // `Rc<RefCell>` following the interior mutability pattern. Here, it would
+    // not be needed but we include the wrapping anyway as example.
+    let worker_handle = Rc::new(RefCell::new(Worker::new("./worker.js").unwrap()));
+    console::log_1(&"Created a new worker from within WASM".into());
+
+    // Pass the worker to the function which sets up the `oninput` callback.
+    setup_input_oninput_callback(worker_handle.clone());
+}
+
+fn setup_input_oninput_callback(worker: Rc<RefCell<web_sys::Worker>>) {
+    let document = web_sys::window().unwrap().document().unwrap();
+
+    // If our `onmessage` callback should stay valid after exiting from the
+    // `oninput` closure scope, we need to either forget it (so it is not
+    // destroyed) or store it somewhere. To avoid leaking memory every time we
+    // want to receive a response from the worker, we move a handle into the
+    // `oninput` closure to which we will always attach the last `onmessage`
+    // callback. The initial value will not be used and we silence the warning.
+    #[allow(unused_assignments)]
+    let mut persistent_callback_handle = get_on_msg_callback();
+
+    let callback = Closure::wrap(Box::new(move || {
+        console::log_1(&"oninput callback triggered".into());
+        let document = web_sys::window().unwrap().document().unwrap();
+
+        let input_field = document
+            .get_element_by_id("inputNumber")
+            .expect("#inputNumber should exist");
+        let input_field = input_field
+            .dyn_ref::<HtmlInputElement>()
+            .expect("#inputNumber should be a HtmlInputElement");
+
+        // If the value in the field can be parsed to a `i32`, send it to the
+        // worker. Otherwise clear the result field.
+        match input_field.value().parse::<i32>() {
+            Ok(number) => {
+                // Access worker behind shared handle, following the interior
+                // mutability pattern.
+                let worker_handle = &*worker.borrow();
+                let _ = worker_handle.post_message(&number.into());
+                persistent_callback_handle = get_on_msg_callback();
+
+                // Since the worker returns the message asynchronously, we
+                // attach a callback to be triggered when the worker returns.
+                worker_handle
+                    .set_onmessage(Some(persistent_callback_handle.as_ref().unchecked_ref()));
+            }
+            Err(_) => {
+                document
+                    .get_element_by_id("resultField")
+                    .expect("#resultField should exist")
+                    .dyn_ref::<HtmlElement>()
+                    .expect("#resultField should be a HtmlInputElement")
+                    .set_inner_text("");
+            }
+        }
+    }) as Box<dyn FnMut()>);
+
+    // Attach the closure as `oninput` callback to the input field.
+    document
+        .get_element_by_id("inputNumber")
+        .expect("#inputNumber should exist")
+        .dyn_ref::<HtmlInputElement>()
+        .expect("#inputNumber should be a HtmlInputElement")
+        .set_oninput(Some(callback.as_ref().unchecked_ref()));
+
+    // Leaks memory.
+    callback.forget();
+}
+
+/// Create a closure to act on the message returned by the worker
+fn get_on_msg_callback() -> Closure<dyn FnMut(MessageEvent)> {
+    let callback = Closure::wrap(Box::new(move |event: MessageEvent| {
+        console::log_2(&"Received response: ".into(), &event.data().into());
+
+        let result = match event.data().as_bool().unwrap() {
+            true => "even",
+            false => "odd",
+        };
+
+        let document = web_sys::window().unwrap().document().unwrap();
+        document
+            .get_element_by_id("resultField")
+            .expect("#resultField should exist")
+            .dyn_ref::<HtmlElement>()
+            .expect("#resultField should be a HtmlInputElement")
+            .set_inner_text(result);
+    }) as Box<dyn FnMut(_)>);
+
+    callback
+}

examples/wasm-in-web-worker/www/index.html

@@ -0,0 +1,24 @@
+<html>
+
+<head>
+    <meta content="text/html;charset=utf-8" http-equiv="Content-Type" />
+    <link rel="stylesheet" href="style.css">
+</head>
+
+<body>
+    <div id="wrapper">
+        <h1>Main Thread/WASM Web Worker Interaction</h1>
+
+        <input type="text" id="inputNumber">
+
+        <div id="resultField"></div>
+    </div>
+
+    <!-- Make `wasm_bindgen` available for `index.js` -->
+    <script src='./pkg/wasm_in_web_worker.js'></script>
+    <!-- Note that there is no `type="module"` in the script tag -->
+    <script src="./index.js"></script>
+
+</body>
+
+</html>

examples/wasm-in-web-worker/www/index.js

@@ -0,0 +1,18 @@
+// We only need `startup` here which is the main entry point
+// In theory, we could also use all other functions/struct types from Rust which we have bound with
+// `#[wasm_bindgen]`
+const {startup} = wasm_bindgen;
+
+async function run_wasm() {
+    // Load the wasm file by awaiting the Promise returned by `wasm_bindgen`
+    // `wasm_bindgen` was imported in `index.html`
+    await wasm_bindgen('./pkg/wasm_in_web_worker_bg.wasm');
+
+    console.log('index.js loaded');
+
+    // Run main WASM entry point
+    // This will create a worker from within our Rust code compiled to WASM
+    startup();
+}
+
+run_wasm();

examples/wasm-in-web-worker/www/style.css

@@ -0,0 +1,32 @@
+body {
+    position: absolute;
+    top: 0;
+    left: 0;
+    width: 100%;
+    height: 100%;
+    display: flex;
+    flex-direction: column;
+    align-items: center;
+    justify-content: center;
+    font-family: "Century Gothic", CenturyGothic, Geneva, AppleGothic, sans-serif; 
+    color: white;
+    background-color: black;
+}
+
+#wrapper {
+    width: 50%;
+    display: flex;
+    flex-direction: column;
+    align-items: center;
+    justify-content: center;
+}
+
+#inputNumber {
+    text-align: center;
+}
+
+#resultField {
+    text-align: center;
+    height: 1em;
+    padding-top: 0.2em;
+}

examples/wasm-in-web-worker/www/worker.js

@@ -0,0 +1,30 @@
+// The worker has its own scope and no direct access to functions/objects of the
+// global scope. We import the generated JS file to make `wasm_bindgen`
+// available which we need to initialize our WASM code.
+importScripts('./pkg/wasm_in_web_worker.js');
+
+console.log('Initializing worker')
+
+// In the worker, we have a different struct that we want to use as in
+// `index.js`.
+const {NumberEval} = wasm_bindgen;
+
+async function init_wasm_in_worker() {
+    // Load the wasm file by awaiting the Promise returned by `wasm_bindgen`.
+    await wasm_bindgen('./pkg/wasm_in_web_worker_bg.wasm');
+
+    // Create a new object of the `NumberEval` struct.
+    var num_eval = NumberEval.new();
+
+    // Set callback to handle messages passed to the worker.
+    self.onmessage = async event => {
+        // By using methods of a struct as reaction to messages passed to the
+        // worker, we can preserve our state between messages.
+        var worker_result = num_eval.is_even(event.data);
+
+        // Send response back to be handled by callback in main thread.
+        self.postMessage(worker_result);
+    };
+};
+
+init_wasm_in_worker();

guide/src/SUMMARY.md

@@ -25,6 +25,7 @@
   - [web-sys: WebRTC DataChannel](./examples/webrtc_datachannel.md)
   - [web-sys: `requestAnimationFrame`](./examples/request-animation-frame.md)
   - [web-sys: A Simple Paint Program](./examples/paint.md)
+  - [web-sys: WASM in Web Worker](./examples/wasm-in-web-worker.md)
   - [Parallel Raytracing](./examples/raytrace.md)
   - [web-sys: A TODO MVC App](./examples/todomvc.md)
 - [Reference](./reference/index.md)

guide/src/examples/wasm-in-web-worker.md

@@ -0,0 +1,71 @@
+# WASM in Web Worker
+
+[View full source code][code]
+
+[code]: https://github.com/rustwasm/wasm-bindgen/tree/master/examples/wasm-in-web-worker
+
+A simple example of parallel execution by spawning a web worker with `web_sys`,
+loading WASM code in the web worker and interacting between the main thread and
+the worker.
+
+## Building & compatibility
+
+At the time of this writing, only Chrome supports modules in web workers, e.g.
+Firefox does not. To have compatibility across browsers, the whole example is
+set up without relying on ES modules as target. Therefore we have to build
+with `--target no-modules`. The full command can be found in `build.sh`.
+
+## `Cargo.toml`
+
+The `Cargo.toml` enables features necessary to work with the DOM, log output to
+the JS console, creating a worker and reacting to message events.
+
+```toml
+{{#include ../../../examples/wasm-in-web-worker/Cargo.toml}}
+```
+
+## `src/lib.rs`
+
+Creates a struct `NumberEval` with methods to act as stateful object in the
+worker and function `startup` to be launched in the main thread. Also includes
+internal helper functions `setup_input_oninput_callback` to attach a
+`wasm_bindgen::Closure` as callback to the `oninput` event of the input field
+and `get_on_msg_callback` to create a `wasm_bindgen::Closure` which is triggered
+when the worker returns a message.
+
+```rust
+{{#include ../../../examples/wasm-in-web-worker/src/lib.rs}}
+```
+
+## `index.html`
+
+Includes the input element `#inputNumber` to type a number into and a HTML
+element `#resultField` were the result of the evaluation even/odd is written to.
+Since we require to build with `--target no-modules` to be able to load WASM
+code in in the worker across browsers, the `index.html` also includes loading
+both `wasm_in_web_worker.js` and `index.js`.
+
+```html
+{{#include ../../../examples/wasm-in-web-worker/www/index.html}}
+```
+
+## `index.js`
+
+Loads our WASM file asynchronously and calls the entry point `startup` of the
+main thread which will create a worker.
+
+```js
+{{#include ../../../examples/wasm-in-web-worker/www/index.js}}
+```
+
+## `worker.js`
+
+Loads our WASM file by first importing `wasm_bindgen` via
+`importScripts('./pkg/wasm_in_web_worker.js')` and then awaiting the Promise
+returned by `wasm_bindgen(...)`. Creates a new object to do the background
+calculation and bind a method of the object to the `onmessage` callback of the
+worker.
+
+```js
+{{#include ../../../examples/wasm-in-web-worker/www/worker.js}}
+```