| 1 |
# Parallel Raytracing |
| 2 |
|
| 3 |
[View full source code][code] or [view the compiled example online][online] |
| 4 |
|
| 5 |
[online]: https://wasm-bindgen.netlify.app/exbuild/raytrace-parallel/ |
| 6 |
[code]: https://github.com/rustwasm/wasm-bindgen/tree/master/examples/raytrace-parallel |
| 7 |
|
| 8 |
This is an example of using threads with WebAssembly, Rust, and `wasm-bindgen`, |
| 9 |
culminating in a parallel raytracer demo. There's a number of moving pieces to |
| 10 |
this demo and it's unfortunately not the easiest thing to wrangle, but it's |
| 11 |
hoped that this'll give you a bit of a taste of what it's like to use threads |
| 12 |
and wasm with Rust on the web. |
| 13 |
|
| 14 |
### Building the demo |
| 15 |
|
| 16 |
One of the major gotchas with threaded WebAssembly is that Rust does not ship a |
| 17 |
precompiled target (e.g. standard library) which has threading support enabled. |
| 18 |
This means that you'll need to recompile the standard library with the |
| 19 |
appropriate rustc flags, namely |
| 20 |
`-C target-feature=+atomics,+bulk-memory,+mutable-globals`. |
| 21 |
Note that this requires a nightly Rust toolchain. |
| 22 |
|
| 23 |
To do this you can use the `RUSTFLAGS` environment variable that Cargo reads: |
| 24 |
|
| 25 |
```sh |
| 26 |
export RUSTFLAGS='-C target-feature=+atomics,+bulk-memory,+mutable-globals' |
| 27 |
``` |
| 28 |
|
| 29 |
To recompile the standard library it's recommended to use Cargo's |
| 30 |
[`-Zbuild-std`](https://doc.rust-lang.org/nightly/cargo/reference/unstable.html#build-std) |
| 31 |
feature: |
| 32 |
|
| 33 |
```sh |
| 34 |
cargo build --target wasm32-unknown-unknown -Z build-std=panic_abort,std |
| 35 |
``` |
| 36 |
|
| 37 |
Note that you can also configure this via `.cargo/config.toml`: |
| 38 |
|
| 39 |
```toml |
| 40 |
[unstable] |
| 41 |
build-std = ['std', 'panic_abort'] |
| 42 |
|
| 43 |
[build] |
| 44 |
target = "wasm32-unknown-unknown" |
| 45 |
rustflags = '-Ctarget-feature=+atomics,+bulk-memory,+mutable-globals' |
| 46 |
``` |
| 47 |
|
| 48 |
After this `cargo build` should produce a WebAssembly file with threading |
| 49 |
enabled, and the standard library will be appropriately compiled as well. |
| 50 |
|
| 51 |
The final step in this is to run `wasm-bindgen` as usual, and `wasm-bindgen` |
| 52 |
needs no extra configuration to work with threads. You can continue to run it |
| 53 |
through `wasm-pack`, for example. |
| 54 |
|
| 55 |
### Running the demo |
| 56 |
|
| 57 |
Currently it's required to use the `--target no-modules` or `--target web` flag |
| 58 |
with `wasm-bindgen` to run threaded code. This is because the WebAssembly file |
| 59 |
imports memory instead of exporting it, so we need to hook initialization of the |
| 60 |
wasm module at this time to provide the appropriate memory object. This demo |
| 61 |
uses `--target no-modules`, because Firefox does not support modules in workers. |
| 62 |
|
| 63 |
With `--target no-modules` you'll be able to use `importScripts` inside of each |
| 64 |
web worker to import the shim JS generated by `wasm-bindgen` as well as calling |
| 65 |
the `wasm_bindgen` initialization function with the shared memory instance from |
| 66 |
the main thread. The expected usage is that WebAssembly on the main thread will |
| 67 |
post its memory object to all other threads to get instantiated with. |
| 68 |
|
| 69 |
### Caveats |
| 70 |
|
| 71 |
Unfortunately at this time running wasm on the web with threads has a number of |
| 72 |
caveats, although some are specific to just `wasm-bindgen`. These are some |
| 73 |
pieces to consider and watch out for, although we're always looking for |
| 74 |
improvements to be made so if you have an idea please file an issue! |
| 75 |
|
| 76 |
* The main thread in a browser cannot block. This means that if you run |
| 77 |
WebAssembly code on the main thread you can *never* block, meaning you can't |
| 78 |
do so much as acquire a mutex. This is an extremely difficult limitation to |
| 79 |
work with on the web, although one workaround is to run wasm exclusively in |
| 80 |
web workers and run JS on the main thread. It is possible to run the same wasm |
| 81 |
across all threads, but you need to be extremely vigilant about |
| 82 |
synchronization with the main thread. |
| 83 |
|
| 84 |
* Setting up a threaded environment is a bit wonky and doesn't feel smooth |
| 85 |
today. For example `--target bundler` is unsupported and very specific shims |
| 86 |
are required on both the main thread and worker threads. These are possible to |
| 87 |
work with but are somewhat brittle since there's no standard way to spin up |
| 88 |
web workers as wasm threads. |
| 89 |
|
| 90 |
* There is no standard notion of a "thread". For example the standard library |
| 91 |
has no viable route to implement the `std::thread` module. As a consequence |
| 92 |
there is no concept of thread exit and TLS destructors will never run. |
| 93 |
We do expose a helper, `__wbindgen_thread_destroy`, that deallocates |
| 94 |
the thread stack and TLS. If you invoke it, it *must* be the last function |
| 95 |
you invoke from the wasm module for a given thread. |
| 96 |
|
| 97 |
* Any thread launched after the first one _might attempt to block_ implicitly |
| 98 |
in its initialization routine. This is a constraint introduced by the way |
| 99 |
we set up the space for thread stacks and TLS. This means that if you attempt |
| 100 |
to run a wasm module in the main thread _after_ you are already running it |
| 101 |
in a worker, it might fail. |
| 102 |
|
| 103 |
* Web Workers executing WebAssembly code cannot receive events from JS. A Web |
| 104 |
Worker has to fully return back to the browser (and ideally should do so |
| 105 |
occasionally) to receive JS messages and such. This means that common |
| 106 |
paradigms like a rayon thread pool do not apply straightforward-ly to the web. |
| 107 |
The intention of the web is that all long-term blocking happens in the browser |
| 108 |
itself, not in each thread, but many crates in the ecosystem leveraging |
| 109 |
threading are not necessarily engineered this way. |
| 110 |
|
| 111 |
These caveats are all largely inherited from the web platform itself, and |
| 112 |
they're important to consider when designing an application for threading. It's |
| 113 |
highly unlikely that you can pull a crate off the shelf and "just use it" due to |
| 114 |
these limitations. You'll need to be sure to carefully plan ahead and ensure |
| 115 |
that gotchas such as these don't cause issues in the future. As mentioned before |
| 116 |
though we're always trying to actively develop this support so if folks have |
| 117 |
ideas about how to improve, or if web standards change, we'll try to update this |
| 118 |
documentation! |
| 119 |
|
| 120 |
### Browser Requirements |
| 121 |
|
| 122 |
This demo should work in the latest Firefox and Chrome versions at this time, |
| 123 |
and other browsers are likely to follow suit. Note that threads and |
| 124 |
`SharedArrayBuffer` require HTTP headers to be set to work correctly. For more |
| 125 |
information see the [documentation on |
| 126 |
MDN](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/SharedArrayBuffer) |
| 127 |
under "Security requirements" as well as [Firefox's rollout blog |
| 128 |
post](https://hacks.mozilla.org/2020/07/safely-reviving-shared-memory/). This |
| 129 |
means that during local development you'll need to configure your web server |
| 130 |
appropriately or enable a workaround in your browser. |