Multithreaded JavaScript: clone, transfer or share

HOW IT FITS TOGETHER

KEY TERMS

Agents and realms

ECMAScript runs code in agents: one thread with its own execution stack and job queue. A window and each worker are separate agents with separate realms (globals, built-ins). Agents in the same agent cluster can share SharedArrayBuffer memory, but never JavaScript objects.

Structured clone

The algorithm behind postMessage and structuredClone(). It deep-copies plain objects, arrays, Maps, Sets, Dates, typed arrays, Blobs and more, preserves cycles, and throws DataCloneError on functions and DOM nodes. Class instances arrive as plain objects. Cost scales with size and object count and is paid on the sending thread too.

Transferables

ArrayBuffer, MessagePort, OffscreenCanvas, ImageBitmap, ReadableStream/WritableStream/TransformStream, VideoFrame and others. Listing one in the transfer array moves the underlying resource and detaches the original. Typed arrays are not transferable themselves: transfer their .buffer.

SharedArrayBuffer and Atomics

A buffer whose bytes are visible to every agent it is posted to. Plain reads and writes can tear or be reordered; Atomics.add, compareExchange, load and store are indivisible and sequentially consistent. Atomics.wait blocks a worker until notify; compareExchange is the building block for locks and lock-free structures.

Cross-origin isolation

After Spectre, browsers disabled SharedArrayBuffer because it can build a high-resolution timer. It returns only when the document is served with Cross-Origin-Opener-Policy: same-origin and Cross-Origin-Embedder-Policy: require-corp (or credentialless), so no cross-origin data can end up in the process. Check self.crossOriginIsolated.

Atomics.waitAsync

A non-blocking wait that returns { async, value }: either an immediate "not-equal"/"timed-out" string or a promise that resolves "ok" on notify. It lets the main thread participate in wait/notify protocols. MDN lists it as Baseline 2025 (November 2025).

Pools and RPC

Creating a worker per task is slow; keep a bounded pool sized near the core count. In Node, Piscina (actively maintained, 5.x) provides queueing, backpressure, cancellation and Piscina.move() for transfers. In browsers, Comlink turns postMessage into proxied async calls; it is small and stable but releases rarely.

IN YOUR STACK

// main.js
const worker = new Worker(new URL("./stats.worker.js", import.meta.url), { type: "module" });
const samples = Float64Array.from({ length: 10_000_000 }, Math.random); // 80 MB

worker.postMessage({ samples }, [samples.buffer]); // move ownership, no copy
console.log(samples.byteLength); // 0: detached on this thread

worker.onmessage = ({ data }) => {
  console.log("mean", data.mean);
  reuse(data.samples); // the same memory, handed back
};
function reuse(buffer) { console.log("got back", buffer.length, "samples"); }

// stats.worker.js
self.onmessage = ({ data: { samples } }) => {
  let total = 0;
  for (const x of samples) total += x;
  self.postMessage({ mean: total / samples.length, samples }, [samples.buffer]);
};

// main.js (the page must be cross-origin isolated)
if (!crossOriginIsolated) throw new Error("SharedArrayBuffer needs COOP + COEP headers");

const counter = new Int32Array(new SharedArrayBuffer(Int32Array.BYTES_PER_ELEMENT));
const url = new URL("./count.worker.js", import.meta.url);
const workers = Array.from({ length: 4 }, () => new Worker(url, { type: "module" }));

let finished = 0;
for (const worker of workers) {
  worker.onmessage = () => {
    if (++finished === workers.length) console.log(Atomics.load(counter, 0)); // 4000000
  };
  worker.postMessage(counter); // shared: every worker sees the same memory
}

// count.worker.js
self.onmessage = ({ data: counter }) => {
  for (let i = 0; i < 1_000_000; i++) {
    Atomics.add(counter, 0, 1); // counter[0]++ here would lose updates
  }
  self.postMessage("done");
};

// protocol.js: cell[0] = state, cell[1] = payload
export const EMPTY = 0, REQUEST = 1, RESPONSE = 2;
import { EMPTY, REQUEST } from "./protocol.js"; // main.js: one call in flight at a time
const cell = new Int32Array(new SharedArrayBuffer(8));
new Worker(new URL("./square.worker.js", import.meta.url), { type: "module" }).postMessage(cell);
export async function square(n) {
  Atomics.store(cell, 1, n);
  Atomics.store(cell, 0, REQUEST);
  Atomics.notify(cell, 0);                                  // wake the sleeping worker
  const { async, value } = Atomics.waitAsync(cell, 0, REQUEST); // main thread must not block
  if (async) await value; // then the worker has written RESPONSE
  const result = Atomics.load(cell, 1);
  Atomics.store(cell, 0, EMPTY); // free the slot for the next call
  return result;
}
// square.worker.js: dedicated to this loop, so blocking is fine
import { REQUEST, RESPONSE } from "./protocol.js";
self.onmessage = ({ data: cell }) => {
  for (;;) {
    const state = Atomics.load(cell, 0);
    if (state !== REQUEST) { Atomics.wait(cell, 0, state); continue; } // sleep, no spin
    Atomics.store(cell, 1, Atomics.load(cell, 1) ** 2);
    Atomics.store(cell, 0, RESPONSE); Atomics.notify(cell, 0);
  }
};

# On the top-level HTML document
Cross-Origin-Opener-Policy: same-origin
Cross-Origin-Embedder-Policy: require-corp

# Each cross-origin subresource must then use CORS or opt in with
Cross-Origin-Resource-Policy: cross-origin

// Express middleware
app.use((req, res, next) => {
  res.set("Cross-Origin-Opener-Policy", "same-origin");
  res.set("Cross-Origin-Embedder-Policy", "require-corp");
  next();
});

// In the page or a worker
console.log(self.crossOriginIsolated); // true => SharedArrayBuffer is available

// server.mjs
import { createServer } from "node:http";
import { availableParallelism } from "node:os";
import { Piscina } from "piscina";
const pool = new Piscina({
  filename: new URL("./fib.worker.mjs", import.meta.url).href,
  maxThreads: availableParallelism(),
  maxQueue: "auto", // maxThreads squared; run() rejects when full
});

createServer(async (req, res) => {
  const n = Number(new URL(req.url, "http://localhost").searchParams.get("n") ?? 30);
  const signal = AbortSignal.timeout(2_000);
  try {
    res.end(JSON.stringify({ result: await pool.run({ n }, { signal }) }));
  } catch {
    res.statusCode = signal.aborted ? 504 : 503; // timed out, queue full, or task threw
    res.end();
  }
}).listen(3000);

// fib.worker.mjs: runs on a pool thread, the event loop stays free
export default function fib({ n }) {
  return n < 2 ? n : fib({ n: n - 1 }) + fib({ n: n - 2 });
}

// main.js
const canvas = document.querySelector("canvas");
const offscreen = canvas.transferControlToOffscreen(); // the element can no longer be resized here
const worker = new Worker(new URL("./render.worker.js", import.meta.url), { type: "module" });
worker.postMessage({ canvas: offscreen }, [offscreen]);

new ResizeObserver(([entry]) => {
  const { width, height } = entry.contentRect;
  worker.postMessage({ width: width * devicePixelRatio, height: height * devicePixelRatio });
}).observe(canvas);

// render.worker.js: drawing keeps running even when the main thread is busy
let ctx = null;
self.onmessage = ({ data }) => {
  if (data.canvas) ctx = data.canvas.getContext("2d");
  if (data.width && ctx) Object.assign(ctx.canvas, { width: data.width, height: data.height });
};
function frame(time) {
  if (ctx) {
    ctx.clearRect(0, 0, ctx.canvas.width, ctx.canvas.height);
    ctx.fillRect((time / 5) % ctx.canvas.width, 20, 40, 40);
  }
  requestAnimationFrame(frame);
}
requestAnimationFrame(frame);

WHERE IT BITES

• Moving work to a worker and then posting a huge object graph every frame: the structured clone on the main thread costs as much as the work you moved. Transfer buffers or keep state in the worker.
• Using a buffer after transferring it. It is detached: typed array views report length 0 and reading gives nothing useful.
• Plain reads and writes on SharedArrayBuffer for coordination. Without Atomics you get lost updates and reordering; flags need Atomics.store/load and wait/notify.
• Turning on COOP/COEP late and discovering it broke OAuth popups, third-party embeds and analytics scripts. Ship report-only first.
• Spawning a worker per task, or sizing a pool far above the core count. Startup cost and context switching eat the gain.
• Expecting threads to speed up I/O. Node's docs are explicit that worker_threads help CPU-bound work, not network or disk waits.

SOURCES

• MDN: Transferable objects (opens in new tab)Checked 2026-10-11
• MDN: SharedArrayBuffer (security requirements) (opens in new tab)Checked 2026-10-11
• MDN: Atomics.wait() (opens in new tab)Checked 2026-10-11
• web.dev: Making your website cross-origin isolated using COOP and COEP (opens in new tab)Checked 2026-10-11
• Node.js: Worker threads (opens in new tab)Checked 2026-10-11
• Piscina: Node.js worker thread pool (opens in new tab)Checked 2026-10-11