Table of Contents

• Worker Threads

  • worker.isMainThread
  • worker.moveMessagePortToContext(port, contextifiedSandbox)
  • worker.parentPort
  • worker.receiveMessageOnPort(port)
  • worker.resourceLimits
  • worker.SHARE_ENV
  • worker.threadId
  • worker.workerData
  • Class: MessageChannel

  • Class: MessagePort

    • Event: 'close'
    • Event: 'message'
    • port.close()
    • port.postMessage(value[, transferList])
    • port.ref()
    • port.start()
    • port.unref()

  • Class: Worker

    • new Worker(filename[, options])
    • Event: 'error'
    • Event: 'exit'
    • Event: 'message'
    • Event: 'online'
    • worker.getHeapSnapshot()
    • worker.postMessage(value[, transferList])
    • worker.ref()
    • worker.resourceLimits
    • worker.stderr
    • worker.stdin
    • worker.stdout
    • worker.terminate()
    • worker.threadId
    • worker.unref()

Worker Threads#

The worker_threads module enables the use of threads that execute JavaScript in parallel. To access it:

const worker = require('worker_threads');

Workers (threads) are useful for performing CPU-intensive JavaScript operations. They will not help much with I/O-intensive work. Node.js’s built-in asynchronous I/O operations are more efficient than Workers can be.

Unlike child_process or cluster, worker_threads can share memory. They do so by transferring ArrayBuffer instances or sharing SharedArrayBuffer instances.

const {
  Worker, isMainThread, parentPort, workerData
} = require('worker_threads');

if (isMainThread) {
  module.exports = function parseJSAsync(script) {
    return new Promise((resolve, reject) => {
      const worker = new Worker(__filename, {
        workerData: script
      });
      worker.on('message', resolve);
      worker.on('error', reject);
      worker.on('exit', (code) => {
        if (code !== 0)
          reject(new Error(`Worker stopped with exit code ${code}`));
      });
    });
  };
} else {
  const { parse } = require('some-js-parsing-library');
  const script = workerData;
  parentPort.postMessage(parse(script));
}

The above example spawns a Worker thread for each parse() call. In actual practice, use a pool of Workers instead for these kinds of tasks. Otherwise, the overhead of creating Workers would likely exceed their benefit.

When implementing a worker pool, use the AsyncResource API to inform diagnostic tools (e.g. in order to provide asynchronous stack traces) about the correlation between tasks and their outcomes. See "Using AsyncResource for a Worker thread pool" in the async_hooks documentation for an example implementation.

Worker threads inherit non-process-specific options by default. Refer to Worker constructor options to know how to customize worker thread options, specifically argv and execArgv options.

worker.isMainThread#

• <boolean>

Is true if this code is not running inside of a Worker thread.

const { Worker, isMainThread } = require('worker_threads');

if (isMainThread) {
  // This re-loads the current file inside a Worker instance.
  new Worker(__filename);
} else {
  console.log('Inside Worker!');
  console.log(isMainThread);  // Prints 'false'.
}

worker.moveMessagePortToContext(port, contextifiedSandbox)#

• port <MessagePort> The message port which will be transferred.

• contextifiedSandbox <Object> A contextified object as returned by the vm.createContext() method.

• Returns: <MessagePort>

Transfer a MessagePort to a different vm Context. The original port