Skip to content

threading.md

Latest commit

 

History

History
146 lines (105 loc) · 7.44 KB

threading.md

File metadata and controls

146 lines (105 loc) · 7.44 KB

Threading — runtime: 'st' vs 'mt', useWorker, and edge limits

Two orthogonal axes: threading (single vs multi-thread Wasm) and useWorker (whether the Wasm module runs in a Web Worker). Don't confuse them.

The two axes

                    │ runtime: 'st'        │ runtime: 'mt'
────────────────────┼──────────────────────┼─────────────────────────
useWorker: false    │ Default. Main thread │ Wasm runs main-thread,
                    │ Wasm. Smallest setup.│ pthreads via SharedArray-
                    │                      │ Buffer. Needs COOP/COEP.
────────────────────┼──────────────────────┼─────────────────────────
useWorker: true     │ Wasm in 1 Web Worker.│ Wasm in 1 Web Worker;
                    │ Comlink bridge. Main │ pthreads spawn ADDITIONAL
                    │ thread free. Required│ workers from there. Needs
                    │ for OPFS persistence.│ COOP/COEP + Worker support.

When you need each

You want Pick
Quickest path to "C++ in browser" runtime: 'st', no useWorker
Persistent storage in browser runtime: 'st', useWorker: true
CPU-bound parallelism (image / geo / crypto) runtime: 'mt'
Both: persistent storage AND parallelism runtime: 'mt', useWorker: true
Cloudflare Worker / Deno Deploy / Vercel Edge runtime: 'st' only — mt and useWorker not supported
React Native runtime: 'mt' if perf-sensitive (pthreads via JSI; no COOP/COEP needed)

Setting runtime: 'mt'

In cppjs.config.js:

export default {
  general: { name: 'myapp' },
  paths: { config: import.meta.url },
  target: { runtime: 'mt' },  // ← here
}

Two things happen at build time:

  1. The Wasm is compiled with -pthread (Emscripten flag).
  2. Any transitive dependency that's already mt keeps the project on mt. Conversely, if any dep is mt, this project auto-promotes to mt (you can't downgrade).

The COOP/COEP requirement

Multi-threaded Wasm uses SharedArrayBuffer, which browsers gate behind cross-origin isolation. Your hosting layer must send these response headers:

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

Without them, SharedArrayBuffer is undefined and the Wasm init silently fails.

How to verify (in the browser console)

console.log(crossOriginIsolated)   // must be true for `mt`
console.log(typeof SharedArrayBuffer)  // must be 'function'

Per-host configuration

Host Config
Vite dev / preview Auto-injected by @cpp.js/plugin-vite
Webpack / Rspack dev server Auto-injected by @cpp.js/plugin-webpack
Vercel Add to vercel.json: { "headers": [{ "source": "/(.*)", "headers": [{ "key": "Cross-Origin-Opener-Policy", "value": "same-origin" }, { "key": "Cross-Origin-Embedder-Policy", "value": "require-corp" }] }] }
Netlify Add to _headers: /*\n Cross-Origin-Opener-Policy: same-origin\n Cross-Origin-Embedder-Policy: require-corp
Cloudflare Pages _headers file (same syntax as Netlify)
nginx add_header Cross-Origin-Opener-Policy same-origin; add_header Cross-Origin-Embedder-Policy require-corp;
Express / Next.js custom server Set headers via middleware on every response

COEP gotcha

require-corp blocks cross-origin resources unless they explicitly opt in (Cross-Origin-Resource-Policy: cross-origin on the response, or crossorigin attribute on <img> / <script> tags). If your page loads third-party images / fonts / scripts, you'll either need to:

  • Switch to Cross-Origin-Embedder-Policy: credentialless (more permissive, supported in Chrome 96+, Firefox 110+).
  • Or proxy third-party assets through your own origin.

useWorker: true (independent of threading)

Wasm runs in a single dedicated Web Worker; main thread receives a Comlink-bridged proxy.

const m = await initCppJs({ useWorker: true })
// m looks identical, but every call is async.
const result = await m.add(2, 3)

You want this when:

  • You need OPFS persistent storage (mandatory; OPFS is Worker-scope-only).
  • Your C++ is slow and you don't want to block the main thread paint loop.
  • You're using runtime: 'mt' and want pthread workers spawned from a non-main scope (cleaner architecture).

You don't need it when:

  • The C++ is fast (sub-frame) and main-thread blocking doesn't matter.
  • You're already using mt for parallelism (pthread workers are separate from useWorker).

What changes when useWorker: true

Aspect Without worker With worker
m.add(2, 3) returns 5 Promise<5>
m.FS.writeFile(...) returns undefined Promise<undefined>
Synchronous callbacks Work Don't work — use returned promises
OPFS storage Throws Works (if browser supports)
Termination n/a initCppJs.terminate() kills the worker

Embind objects (vectors, structs) are auto-proxied via cpp.js's custom Comlink transfer handlers. m.toArray(vec) and m.toVector(cls, arr) work transparently.

Edge runtime limits (Cloudflare Workers, Deno Deploy, Vercel Edge)

These platforms run JavaScript in V8 isolates that don't expose the Web Worker API. Therefore:

  • ❌ useWorker: true — fails (no Worker constructor).
  • ❌ runtime: 'mt' — fails (pthreads need workers + SharedArrayBuffer).
  • ❌ OPFS — fails (browser-only API anyway).
  • ✅ runtime: 'st' + memory fs — works.

If your use case demands persistence on edge, you need an external service (R2, KV, S3) — call it from JS and feed bytes into Wasm via m.FS.writeFile(...).

React Native

Pthreads are routed through JSI (no SharedArrayBuffer, no COOP/COEP). runtime: 'mt' works without any host configuration. useWorker is a no-op (n/a — no Web Worker API in RN).

Common pitfalls

  1. mt works in dev but not in prod — the bundler plugin injects COOP/COEP for dev/preview, but production hosting needs explicit configuration. Look at crossOriginIsolated in console; if false, the headers are missing.
  2. Mixing mt and st artifacts in one bundle — they have incompatible memory layouts. The CLI prevents this at build time but if you manually copy .wasm files between projects, you'll see "wasm streaming compile failed" errors.
  3. Calling sync callbacks across useWorker: true — Comlink can't invoke main-thread sync code from worker. If your C++ needs a JS callback, design it as a promise round-trip.
  4. Assuming runtime: 'mt' enables useWorker — they're independent. runtime: 'mt' without useWorker runs pthreads on the main thread; useWorker: true without runtime: 'mt' runs single-thread Wasm in a worker.
  5. Loading third-party scripts on a COEP page — require-corp blocks them unless they send Cross-Origin-Resource-Policy: cross-origin. Switch to credentialless or proxy.

See also

  • init.md — useWorker, runtime (via cppjs.config.js), getWasmFunction.
  • cppjs-config.md — target.runtime: 'st' | 'mt'.
  • filesystem.md — why OPFS depends on useWorker.
  • docs/playbooks/integration/*.md — per-framework COOP/COEP setup.