wasm-bindgen-rayon

After adding the dependency, you must re-export init_thread_pool from your Rust code. This exposes an async initThreadPool function in your generated JavaScript.

You must call initThreadPool on the main thread immediately after the standard wasm-bindgen initialization and before calling any functions that require concurrency.

// In your Rust code
pub use wasm_bindgen_rayon::init_thread_pool;

import init, { initThreadPool /* ... */ } from './pkg/index.js';

// Regular wasm-bindgen initialization.
await init();

// Thread pool initialization with the given number of threads
// (pass `navigator.hardwareConcurrency` if you want to use all cores).
await initThreadPool(navigator.hardwareConcurrency);

// ...now you can invoke any exported functions as you normally would

To support older browsers that do not support WebAssembly threads, you should provide two builds (one with threads and one without) and use wasm-feature-detect to select the correct one at runtime.

import { threads } from 'wasm-feature-detect';

let wasmPkg;

if (await threads()) {
  wasmPkg = await import('./pkg-with-threads/index.js');
  await wasmPkg.default();
  await wasmPkg.initThreadPool(navigator.hardwareConcurrency);
} else {
  wasmPkg = await import('./pkg-without-threads/index.js');
  await wasmPkg.default();
}

wasmPkg.nowCallAnyExportedFuncs();

The library uses a syntax for Web Workers that is compatible with most modern bundlers:

• Webpack: Works out of the box with v5 (>= 5.25.1). You may see circular dependency warnings; these are safe to ignore.
• Parcel: Works out of the box with v2.
• Rollup / Vite: Vite is recommended. For raw Rollup, use @surma/rollup-plugin-off-main-thread and @web/rollup-plugin-import-meta-assets.
• No Bundler: If you are not using a bundler, you must enable the no-bundler feature in Cargo.toml to handle import paths correctly.

wasm-bindgen-rayon = { version = "1.2", features = ["no-bundler"] }

To enable Rayon-based concurrency, add wasm-bindgen, rayon, and wasm-bindgen-rayon to your Cargo.toml.

Important: You must enable cross-origin isolation policies on your web server to allow the use of SharedArrayBuffer.

[dependencies]
wasm-bindgen = "0.2"
rayon = "1.8"
wasm-bindgen-rayon = "1.2"

The initialization process follows a specific lifecycle to bridge Rust's Rayon with Web Workers:

1. JS Call: The user calls initThreadPool(num_threads) from JavaScript.
2. Worker Spawning: The underlying start_workers helper (provided by the library's JS glue code) spawns the requested number of Web Workers.
3. Pool Construction: A wbg_rayon_PoolBuilder is created in Rust to manage the communication between the main thread and the new workers.
4. Handshake: Once the workers are spawned, the build() method is called on the builder. This sets up a spawn_handler that sends ThreadBuilder objects through a channel to the workers.
5. Worker Execution: Each worker calls wbg_rayon_start_worker (internally) to receive its ThreadBuilder and start Rayon's internal event loop.

Once initialized, you can use Rayon's parallel iterators (e.g., par_iter()) inside your #[wasm_bindgen] functions. These functions will automatically utilize the initialized thread pool to perform computations across multiple Web Workers.

#[wasm_bindgen]
pub fn sum(numbers: &[i32]) -> i32 {
    numbers.par_iter().sum()
}

The primary way to enable Rayon concurrency in your WebAssembly application is to call initThreadPool from JavaScript. This function handles the spawning of Web Workers and the initialization of the shared memory required for Rayon to function.

Parameters:

• num_threads (number): The number of worker threads to spawn.

Returns:

• A JavaScript Promise that resolves once the thread pool is successfully initialized.

Note: While you can technically call this from Rust using wasm-bindgen-futures, it is recommended to call it from JavaScript to avoid unnecessary Wasm size overhead and complexity.

// Example usage in JavaScript
import init, { initThreadPool } from './pkg/your_wasm_package.js';

async function run() {
  await init();
  // Initialize a pool with 4 threads
  await initThreadPool(4);
  console.log('Rayon thread pool is ready!');
}

run();