Repository files navigation

Anstd::thread replacement for wasm32 target.

This crate tries to closely replicatestd::thread API. Namely, it doesn't require you to bundle worker scripts and resolves wasm-bindgen shim URL automatically.

Note that some API is still missing and may be even impossible to implement given wasm limitations.

• Addwasm_thread to yourCargo.toml.
• This project supportswasm-pack targetsweb andno-modules.es_modules feature is enabled by default, if building forno-modules, usedefault-features = false when specifying dependency.
• Replaceuse std::thread withuse wasm_thread as thread. Note that some API might be missing.
• Build normally usingwasm-pack or adaptbuild_wasm.sh to your project.

• In order for multiple wasm instances to share the same memory,SharedArrayBuffer is required. This means that the COOP and COEP security headers for the webpage will need to be set (seeMozilla's documentation). These may be enabled by adjusting webserver settings or using aservice worker.
• Any blocking API (thread.join(),futures::block_on(), etc) on the main thread will freeze the browser for as long as lock is maintained. This also freezes any proxied functions, which means that worker spawning, network fetches and other similar asynchronous APIs will block also and can cause a deadlock. To avoid this, either run yourmain() in a worker thread or use async futures.
• Atomic locks (i32.atomic.wait to be specific) will panic on the main thread. This means thatmutex.lock() will likely crash. Solution is the same as above.
• Web workers are normally spawned by providing a script URL, however, to avoid bundling scripts this library uses URL encoded blobweb_worker.js to avoid HTTP fetch.wasm_bindgen generated.js shim script is still needed and ahack is used to obtain its URL. If this for some reason does not work in your setup, please report an issue or useBuilder::wasm_bindgen_shim_url() to specify explicit URL.
• For additional information on wasm threading look atthis blogpost orraytrace-parallel example.

For a higher-level threading solution, seewasm-bindgen-rayon, which allows one to utilize a fixed-size threadpool in web browsers.

• Justcargo run --example simple

• Install nightly toolchain and dependencies:

rustup toolchain install nightlyrustup component add rust-src --toolchain nightlycargo install wasm-bindgen-cli

• Build with./build_wasm.sh (bash) or./build_wasm.ps1 (PowerShell). This custom build step is required because prebuilt standard library does not have support for atomics yet. Read more about thishere.
• Serveexamples directory over HTTP with cross-origin isolation enabled and opensimple.html in the browser. Inspect console output. You can usecargo install sfz as a basic HTTP server and serve withsfz examples --coi.

• Installwasm-pack:

cargo install wasm-pack

• Build with./examples-wasm-pack/web-build.sh for an example targetingweb, and./examples-wasm-pack/web-build-no-module.sh for an example targetingno-modules.
• Serve./examples-wasm-pack/module or./examples-wasm-pack/no-module, respectively, over HTTP and opensimple.html in browser. Inspect console output.

Native:

hi number 1 from the spawned thread ThreadId(2)!hi number 1 from the main thread ThreadId(1)!hi number 1 from the spawned thread ThreadId(3)!hi number 2 from the main thread ThreadId(1)!hi number 2 from the spawned thread ThreadId(2)!hi number 2 from the spawned thread ThreadId(3)!

Wasm:

hi number 1 from the main thread ThreadId(1)!hi number 2 from the main thread ThreadId(1)!hi number 1 from the spawned thread ThreadId(2)!hi number 1 from the spawned thread ThreadId(3)!hi number 2 from the spawned thread ThreadId(2)!hi number 2 from the spawned thread ThreadId(3)!

As you can see wasm threads are only spawned aftermain() returns, because browser event loop cannot continue while main thread is blocked.

Licensed under either of

• Apache License, Version 2.0 (LICENSE-APACHE orhttp://www.apache.org/licenses/LICENSE-2.0)
• MIT license (LICENSE-MIT orhttp://opensource.org/licenses/MIT)

at your option.

Unless you explicitly state otherwise, any contribution intentionally submittedfor inclusion in the work by you, as defined in the Apache-2.0 license, shall bedual licensed as above, without any additional terms or conditions.