Skip to content
Tutorials Center
My learning

Topics

Lesson 27 of 38 ยท Performance and Debugging

SIMD and Threads in WebAssembly

Learn WebAssembly SIMD (v128 vectors) and threads (shared memory, atomics, Web Workers) with runnable examples, plus cross-origin isolation, feature detection and when each one pays off.

A single WebAssembly function running on a single thread already gets you close to native speed for many tasks. Two extensions push further. SIMD (Single Instruction, Multiple Data) processes several numbers with one instruction, and threads let several cores work on the same data at once. Both are standardized, and both are now available in all major browsers and in server runtimes, though threads need extra server configuration on the web.

This lesson explains what each feature adds to the instruction set, shows a runnable example of each, and covers the practical details: how compilers use them, how to feature-detect them, and what can go wrong.

SIMD: one instruction, four numbers

WebAssembly SIMD adds a 128-bit value type, v128, and about 230 instructions that treat it as a small vector. The same 128 bits can be viewed as 16 bytes, 8 shorts, 4 i32/f32 values or 2 i64/f64 values, and each instruction names its interpretation: i32x4.add, f32x4.mul, i8x16.min_u and so on.

For a loop that adds two arrays, a scalar version does one addition per iteration. With i32x4.add, each iteration handles four elements, so the loop runs a quarter as many times. The module below does exactly that: add_arrays(a, b, out, vecs) loads 16 bytes from each input, adds them lane by lane, and stores 16 bytes.

WAT
(func (export "add_arrays") (param $a i32) (param $b i32) (param $out i32) (param $vecs i32)
  ...
  (v128.store (i32.add (local.get $out) (local.get $off))
    (i32x4.add
      (v128.load (i32.add (local.get $a) (local.get $off)))
      (v128.load (i32.add (local.get $b) (local.get $off))))))

SIMD at a glance

v128 One 128-bit value type.
Lanes 4 x i32, 8 x i16, 16 x i8 and more.
One instruction i32x4.add adds four pairs at once.
Best for Images, audio, math, codecs.

Portable across x86 and ARM.

1 / 2
Node.js SIMD add versus a plain JavaScript loop

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

You rarely write v128 code by hand. Compilers produce it in two ways:

  • Auto-vectorization. Compile with -msimd128 (Emscripten, Clang) or RUSTFLAGS="-C target-feature=+simd128" (Rust) and the optimizer turns simple loops into SIMD code.
  • Intrinsics. In C, include <wasm_simd128.h> and call functions such as wasm_i32x4_add. In Rust, use core::arch::wasm32. This gives you control for hot kernels like convolution, color conversion or matrix multiplication.

Because SIMD changes the instruction set, a module that uses it will not even compile in an engine that lacks support. Ship two builds and pick one with a validation probe (the same technique shown in Other Languages for WebAssembly).

Threads: shared memory and atomics

WebAssembly itself has no spawn instruction. The threads proposal adds three things, and the host (JavaScript or a runtime) provides the actual threads:

  1. Shared memory. A WebAssembly.Memory created with shared: true is backed by a SharedArrayBuffer. The same memory can be passed to several Workers, and every instance sees the same bytes.
  2. Atomic instructions. i32.atomic.load, i32.atomic.rmw.add, i32.atomic.rmw.cmpxchg and friends read and modify memory indivisibly, so two threads cannot interleave halfway through an update.
  3. Wait and notify. memory.atomic.wait32 and memory.atomic.notify let a thread sleep until another wakes it, which is the basis for locks and queues.

Sharing a normal counter between threads without atomics causes data races: both threads read 5, both write 6, and an increment is lost. Atomic add makes the read-modify-write a single step. In the example, four workers each call the module's bump(addr) export, which runs i32.atomic.rmw.add on a shared counter, 1000 times each:

Node.js Four workers, one shared counter

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

The module and memory objects are passed to each worker by structured clone: a WebAssembly.Module can be shared (compiled once, instantiated many times) and a shared Memory is shared by reference to the same bytes. In a browser the code looks the same, with postMessage({ module, memory }) in place of workerData.

The web requirements: cross-origin isolation

SharedArrayBuffer was disabled in browsers after the Spectre CPU vulnerabilities, and returned only for pages that opt into cross-origin isolation. Your server must send two headers on the page:

TEXT
Cross-Origin-Opener-Policy: same-origin
Cross-Origin-Embedder-Policy: require-corp

You can check at runtime with self.crossOriginIsolated. If it is false, new WebAssembly.Memory({ shared: true, ... }) will throw or give you a buffer that cannot be shared. Note that require-corp blocks third-party resources (images, scripts) that do not opt in with their own headers, so enabling it on an existing site can break embedded content. Plan for it early.

How languages use threads

  • Emscripten: compile with -pthread and set -sPTHREAD_POOL_SIZE=4; pthread_create, mutexes and std::thread then work, backed by Web Workers.
  • Rust: wasm-bindgen-rayon runs Rayon's parallel iterators on a Worker pool; it needs nightly options for atomics and bulk memory.
  • WASI threads are still evolving, and for server-side use the safest model remains one instance per request.

Pitfalls and good habits

  • Main thread blocking. Atomics.wait is not allowed on the browser's main thread; wait in Workers.
  • Startup cost. Spawning workers takes milliseconds; create a pool once and reuse it.
  • False sharing and contention. Threads fighting over one counter or cache line can be slower than one thread. Give each thread its own slice of the data and combine results at the end.
  • Memory limits. A shared memory needs a declared maximum, and a larger one reserves more address space.
  • Measure. Parallel speed-up depends on the task, core count and memory bandwidth; see WebAssembly Performance.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What does i32x4.add do?

    A v128 value holds four 32-bit lanes. The instruction adds corresponding lanes of the two operands in one step.
  2. 2. Why do shared-memory programs need atomic instructions?

    Without atomics two threads can read the same old value and both write back the same new value, losing an increment.
  3. 3. Which headers make SharedArrayBuffer available on a web page?

    These two headers put the page in a cross-origin isolated state, which re-enables shared memory safely.
  4. 4. How does a wasm module get real threads?

    The proposal adds shared memory and atomics only. Thread creation is done by the host environment.

Summary

  • SIMD adds the 128-bit v128 type and lane-wise instructions; enable it with -msimd128 or use intrinsics, and always keep a fallback build.
  • Threads come from the host: Workers sharing a WebAssembly.Memory with shared: true, synchronized by atomic instructions and wait/notify.
  • On the web, shared memory requires cross-origin isolation (COOP and COEP headers).
  • Give each thread separate work and use a reusable pool; measure before and after.

Next: What is WASI?