Web Workers in JavaScript: True Parallelism, Internals & Production Pitfalls

// ─── main.js (runs on the main thread) ───────────────────────────────────────

// Spawn a dedicated worker from a separate file.
// The browser creates a new thread + V8 isolate immediately.
const primeWorker = new Worker('prime-calculator.js');

// Listen for results coming back FROM the worker.
// This callback runs on the main thread — safe to update the DOM here.
primeWorker.onmessage = function (event) {
  const { primes, computationTimeMs } = event.data;
  console.log(`Found ${primes.length} primes in ${computationTimeMs}ms`);
  console.log('First 5:', primes.slice(0, 5)); // [2, 3, 5, 7, 11]
  document.getElementById('result').textContent = `Primes found: ${primes.length}`;
};

// Handle any uncaught errors thrown inside the worker.
// Without this, errors inside workers fail SILENTLY in many browsers.
primeWorker.onerror = function (errorEvent) {
  console.error('Worker blew up:', errorEvent.message, 'at line', errorEvent.lineno);
  errorEvent.preventDefault(); // Prevent the error bubbling to window.onerror
};

// Send a task to the worker. The object is deep-cloned via structured clone.
// The main thread is NOT blocked — it continues executing immediately after this.
primeWorker.postMessage({ upperLimit: 1_000_000 });
console.log('Message sent — main thread is still free to handle clicks, paint frames, etc.');

// ─── prime-calculator.js (runs inside the Worker's isolated thread) ───────────

// 'self' is the DedicatedWorkerGlobalScope — equivalent to 'window' on main thread.
// There is no 'document', no 'window', no DOM access here.
self.onmessage = function (event) {
  const { upperLimit } = event.data;
  const startTime = performance.now();

  // Sieve of Eratosthenes — CPU-intensive, would freeze the UI on the main thread
  const sieve = new Uint8Array(upperLimit + 1).fill(1);
  sieve[0] = 0;
  sieve[1] = 0;

  for (let i = 2; i * i <= upperLimit; i++) {
    if (sieve[i] === 1) {
      for (let multiple = i * i; multiple <= upperLimit; multiple += i) {
        sieve[multiple] = 0; // Mark composite numbers
      }
    }
  }

  const primes = [];
  for (let n = 2; n <= upperLimit; n++) {
    if (sieve[n] === 1) primes.push(n);
  }

  const computationTimeMs = Math.round(performance.now() - startTime);

  // Send results back. The primes array is deep-cloned back to main thread.
  self.postMessage({ primes, computationTimeMs });
};

// ─── main.js ──────────────────────────────────────────────────────────────────

const imageWorker = new Worker('image-processor.js');

// Simulate a raw RGBA pixel buffer for a 1024x768 image
// 1024 * 768 * 4 bytes (R,G,B,A) = 3,145,728 bytes (~3MB)
const imageWidth = 1024;
const imageHeight = 768;
const rawPixelBuffer = new ArrayBuffer(imageWidth * imageHeight * 4);
const pixelView = new Uint8ClampedArray(rawPixelBuffer);

// Fill with fake image data (checkerboard pattern)
for (let i = 0; i < pixelView.length; i += 4) {
  const pixelIndex = i / 4;
  const isEvenRow = Math.floor(pixelIndex / imageWidth) % 2 === 0;
  const isEvenCol = (pixelIndex % imageWidth) % 2 === 0;
  const isBright = isEvenRow === isEvenCol;
  pixelView[i] = isBright ? 200 : 50;     // Red channel
  pixelView[i + 1] = isBright ? 200 : 50; // Green channel
  pixelView[i + 2] = isBright ? 200 : 50; // Blue channel
  pixelView[i + 3] = 255;                  // Alpha — fully opaque
}

console.log('Before transfer — buffer byteLength on main thread:', rawPixelBuffer.byteLength);
// Output: 3145728

// TRANSFER the buffer (2nd arg to postMessage) instead of cloning it.
// rawPixelBuffer is now DETACHED on the main thread after this call.
imageWorker.postMessage(
  { width: imageWidth, height: imageHeight, buffer: rawPixelBuffer },
  [rawPixelBuffer] // <-- The transfer list. This is what makes it a transfer, not a clone.
);

// The buffer is now neutered — the main thread no longer owns it.
console.log('After transfer — buffer byteLength on main thread:', rawPixelBuffer.byteLength);
// Output: 0  (buffer is detached — attempting to read it throws TypeError)

imageWorker.onmessage = function (event) {
  const { processedBuffer, width, height } = event.data;
  // Worker transferred the processed buffer back — zero copy, instant
  console.log('Received processed buffer, byteLength:', processedBuffer.byteLength);
  // Output: 3145728 — back to full size, now owned by main thread

  const processedPixels = new Uint8ClampedArray(processedBuffer);
  const imageData = new ImageData(processedPixels, width, height);
  const canvas = document.getElementById('output-canvas');
  canvas.getContext('2d').putImageData(imageData, 0, 0);
};

// ─── image-processor.js ───────────────────────────────────────────────────────

self.onmessage = function (event) {
  const { buffer, width, height } = event.data;
  // Worker now OWNS the buffer — main thread can't touch it
  const pixels = new Uint8ClampedArray(buffer);

  // Apply a simple grayscale filter in-place
  for (let i = 0; i < pixels.length; i += 4) {
    const luminance = 0.299 * pixels[i] + 0.587 * pixels[i + 1] + 0.114 * pixels[i + 2];
    pixels[i] = luminance;     // Red
    pixels[i + 1] = luminance; // Green
    pixels[i + 2] = luminance; // Blue
    // Alpha unchanged
  }

  // Transfer the processed buffer back — no copy
  self.postMessage({ processedBuffer: buffer, width, height }, [buffer]);
};

// ─── main.js ──────────────────────────────────────────────────────────────────
// REQUIRES the page to be served with:
//   Cross-Origin-Opener-Policy: same-origin
//   Cross-Origin-Embedder-Policy: require-corp
// Without these headers, SharedArrayBuffer is undefined and this throws.

if (typeof SharedArrayBuffer === 'undefined') {
  throw new Error('SharedArrayBuffer unavailable — check COOP/COEP response headers');
}

const audioWorker = new Worker('audio-generator.js');

// A simple ring buffer layout using a SharedArrayBuffer:
// Index 0: write cursor (updated by Worker)
// Index 1: read cursor (updated by main thread)
// Index 2..N: audio sample data
const RING_BUFFER_CAPACITY = 256; // Number of audio samples in the ring
const METADATA_SLOTS = 2;         // write_cursor + read_cursor
const totalSlots = METADATA_SLOTS + RING_BUFFER_CAPACITY;

// Int32Array because Atomics works on integer typed arrays (Int32, Uint8, etc.)
const sharedBuffer = new SharedArrayBuffer(totalSlots * Int32Array.BYTES_PER_ELEMENT);
const sharedView = new Int32Array(sharedBuffer);

const WRITE_CURSOR_INDEX = 0;
const READ_CURSOR_INDEX = 1;
const DATA_START_INDEX = 2;

// Hand the same SharedArrayBuffer to the worker — NO COPY, same physical memory
audioWorker.postMessage({ sharedBuffer, capacity: RING_BUFFER_CAPACITY });

// Main thread reads samples from the ring buffer on a schedule
function consumeSamples() {
  const writeCursor = Atomics.load(sharedView, WRITE_CURSOR_INDEX); // Atomic read
  const readCursor = Atomics.load(sharedView, READ_CURSOR_INDEX);   // Atomic read

  const availableSamples = (writeCursor - readCursor + RING_BUFFER_CAPACITY) % RING_BUFFER_CAPACITY;

  if (availableSamples > 0) {
    const sampleIndex = DATA_START_INDEX + (readCursor % RING_BUFFER_CAPACITY);
    const sample = Atomics.load(sharedView, sampleIndex); // Thread-safe read

    // Atomically advance the read cursor
    Atomics.add(sharedView, READ_CURSOR_INDEX, 1);
    console.log(`Main consumed sample: ${sample}, available remaining: ${availableSamples - 1}`);

    // Wake the worker in case it was waiting for buffer space
    Atomics.notify(sharedView, WRITE_CURSOR_INDEX, 1);
  }
}

setInterval(consumeSamples, 10); // Consume up to 100 samples per second

// ─── audio-generator.js ───────────────────────────────────────────────────────

let sharedView;
let capacity;

self.onmessage = function (event) {
  const { sharedBuffer, capacity: cap } = event.data;
  // Worker receives the SAME SharedArrayBuffer — same physical RAM
  sharedView = new Int32Array(sharedBuffer);
  capacity = cap;
  generateSamples();
};

const WRITE_CURSOR_INDEX = 0;
const READ_CURSOR_INDEX = 1;
const DATA_START_INDEX = 2;

function generateSamples() {
  let sampleCounter = 0;

  while (sampleCounter < 50) { // Generate 50 test samples
    const writeCursor = Atomics.load(sharedView, WRITE_CURSOR_INDEX);
    const readCursor = Atomics.load(sharedView, READ_CURSOR_INDEX);
    const usedSlots = (writeCursor - readCursor + capacity) % capacity;

    if (usedSlots < capacity - 1) {
      // Buffer has space — write the sample atomically
      const targetIndex = DATA_START_INDEX + (writeCursor % capacity);
      const newSample = Math.floor(Math.sin(sampleCounter * 0.1) * 1000); // Fake audio
      Atomics.store(sharedView, targetIndex, newSample);
      Atomics.add(sharedView, WRITE_CURSOR_INDEX, 1); // Advance write cursor
      sampleCounter++;
    } else {
      // Buffer is full — wait for main thread to consume (blocks THIS worker thread only)
      // Atomics.wait is FORBIDDEN on the main thread — use waitAsync there
      Atomics.wait(sharedView, WRITE_CURSOR_INDEX, writeCursor, 100); // 100ms timeout
    }
  }

  console.log('Worker: Finished generating 50 samples');
}

// ─── WorkerPool.js — A production-ready Worker pool implementation ────────────

class WorkerPool {
  /**
   * @param {string | URL} workerScript  - Path or URL to the worker script
   * @param {number} poolSize            - Number of persistent workers to create
   * @param {number} taskTimeoutMs       - Max ms to wait for a task before rejecting
   */
  constructor(workerScript, poolSize = navigator.hardwareConcurrency || 4, taskTimeoutMs = 10_000) {
    this.poolSize = poolSize;
    this.taskTimeoutMs = taskTimeoutMs;
    this.workers = [];       // All worker instances
    this.idleWorkers = [];   // Workers currently waiting for work
    this.taskQueue = [];     // Tasks waiting for a free worker

    // Pre-warm all workers immediately so first tasks don't pay spawn cost
    for (let i = 0; i < poolSize; i++) {
      const worker = new Worker(workerScript, { type: 'module' });
      worker.poolId = i; // Tag for debugging
      this.workers.push(worker);
      this.idleWorkers.push(worker);
    }

    console.log(`WorkerPool: ${poolSize} workers ready (hardwareConcurrency: ${navigator.hardwareConcurrency})`);
  }

  /**
   * Submit a task to the pool. Returns a Promise that resolves with the Worker's response.
   * @param {any} taskPayload      - Data to send to the worker
   * @param {Transferable[]} transferList - Buffers to transfer (not copy)
   */
  runTask(taskPayload, transferList = []) {
    return new Promise((resolve, reject) => {
      const taskEntry = { taskPayload, transferList, resolve, reject };

      if (this.idleWorkers.length > 0) {
        // A worker is free — dispatch immediately
        this._dispatchTask(this.idleWorkers.pop(), taskEntry);
      } else {
        // All workers busy — queue the task
        this.taskQueue.push(taskEntry);
        console.log(`WorkerPool: Task queued. Queue depth: ${this.taskQueue.length}`);
      }
    });
  }

  _dispatchTask(worker, taskEntry) {
    const { taskPayload, transferList, resolve, reject } = taskEntry;

    // Guard against runaway workers with a timeout
    const timeoutHandle = setTimeout(() => {
      console.error(`WorkerPool: Worker ${worker.poolId} timed out — terminating and replacing`);
      worker.terminate();
      // Replace the dead worker with a fresh one
      const replacementWorker = new Worker(worker._scriptURL, { type: 'module' });
      replacementWorker.poolId = worker.poolId;
      this.workers[worker.poolId] = replacementWorker;
      this.idleWorkers.push(replacementWorker);
      reject(new Error(`Worker ${worker.poolId} timed out after ${this.taskTimeoutMs}ms`));
    }, this.taskTimeoutMs);

    // One-shot message handler — listen for exactly one response then clean up
    worker.onmessage = (event) => {
      clearTimeout(timeoutHandle); // Task completed in time — cancel the timeout
      resolve(event.data);
      this._returnWorkerToPool(worker);
    };

    worker.onerror = (errorEvent) => {
      clearTimeout(timeoutHandle);
      reject(new Error(`Worker error: ${errorEvent.message} at ${errorEvent.filename}:${errorEvent.lineno}`));
      this._returnWorkerToPool(worker);
      errorEvent.preventDefault();
    };

    worker.postMessage(taskPayload, transferList);
  }

  _returnWorkerToPool(worker) {
    if (this.taskQueue.length > 0) {
      // There's a queued task — assign it immediately rather than idling the worker
      const nextTask = this.taskQueue.shift();
      this._dispatchTask(worker, nextTask);
    } else {
      this.idleWorkers.push(worker);
    }
  }

  /** Shut down all workers cleanly — call this on app teardown */
  destroy() {
    this.workers.forEach(worker => worker.terminate());
    this.workers = [];
    this.idleWorkers = [];
    this.taskQueue = [];
    console.log('WorkerPool: All workers terminated');
  }
}

// ─── Usage example ────────────────────────────────────────────────────────────

const pool = new WorkerPool('./hash-worker.js', 4, 5_000);

// Fire off 10 tasks — pool queues the overflow and drains it automatically
const tasks = Array.from({ length: 10 }, (_, i) => ({
  inputData: `dataset-chunk-${i}`,
  chunkIndex: i
}));

const results = await Promise.all(tasks.map(task => pool.runTask(task)));
console.log('All tasks complete. Results count:', results.length);

pool.destroy();