new BroadcastChannel(name)

• name <any> Имя канала для подключения. Допускается любое значение JavaScript, которое можно преобразовать в строку с помощью `${name}`.

broadcastChannel.close()

Закрывает соединение BroadcastChannel.

broadcastChannel.onmessage

• Тип: <Function> Вызывается с одним аргументом MessageEvent при получении сообщения.

broadcastChannel.onmessageerror

• Тип: <Function> Вызывается, если полученное сообщение не удаётся десериализовать.

broadcastChannel.postMessage(message)

• message <any> Любое клонируемое значение JavaScript.

broadcastChannel.ref()

Противоположность unref(). Вызов ref() для ранее unref()ированного BroadcastChannel не позволяет программе завершиться, если он остался единственным активным дескриптором (поведение по умолчанию). Если порт был ref()ирован, повторный вызов ref() не имеет эффекта.

broadcastChannel.unref()

Вызов unref() для BroadcastChannel позволяет потоку завершиться, если он является единственным активным дескриптором в системе событий. Если BroadcastChannel уже был unref()ирован, повторный вызов unref() не имеет эффекта.

Событие: 'close'

Событие 'close' возникает, когда одна из сторон канала отключается.

import { MessageChannel } from 'node:worker_threads';
const { port1, port2 } = new MessageChannel();

// Prints:
//   foobar
//   closed!
port2.on('message', (message) => console.log(message));
port2.on('close', () => console.log('closed!'));

port1.postMessage('foobar');
port1.close();

'use strict';

const { MessageChannel } = require('node:worker_threads');
const { port1, port2 } = new MessageChannel();

// Prints:
//   foobar
//   closed!
port2.on('message', (message) => console.log(message));
port2.on('close', () => console.log('closed!'));

port1.postMessage('foobar');
port1.close();

Событие: 'message'

• value <any> Переданное значение

Событие 'message' возникает при получении любого сообщения и содержит клонированные входные данные, переданные в port.postMessage().

Обработчики этого события получают копию параметра value, переданного в postMessage(), и никаких дополнительных аргументов.

Событие: 'messageerror'

• error <Error> Объект Error

Событие 'messageerror' возникает, если при десериализации сообщения произошла ошибка.

В настоящее время это событие возникает при ошибке во время создания отправленного объекта JS на принимающей стороне. Такие ситуации редки, но возможны, например, если в vm.Context получены объекты определённых API Node.js (где API Node.js сейчас недоступны).

port.close()

Отключает дальнейшую отправку сообщений в обе стороны соединения. Этот метод можно вызвать, если через этот MessagePort больше не будет происходить обмен данными.

Событие 'close' возникает у обоих экземпляров MessagePort, входящих в канал.

port.postMessage(value[, transferList])

• value <any>
• transferList <Object[]>

Отправляет значение JavaScript принимающей стороне этого канала. Передача value выполняется в соответствии с алгоритмом структурного клонирования HTML.

В частности, основные отличия от JSON таковы:

• value может содержать циклические ссылки.
• value может содержать экземпляры встроенных типов JS, таких как RegExp, BigInt, Map, Set и т. д.
• value может содержать типизированные массивы, использующие как ArrayBuffer, так и SharedArrayBuffer.
• value может содержать экземпляры WebAssembly.Module.
• value не может содержать собственные объекты (на основе C++), кроме следующих:
  • <CryptoKey>,
  • <FileHandle>,
  • <Histogram>,
  • <KeyObject>,
  • <MessagePort>,
  • <net.BlockList>,
  • <net.SocketAddress>,
  • <X509Certificate>.

import { MessageChannel } from 'node:worker_threads';
const { port1, port2 } = new MessageChannel();

port1.on('message', (message) => console.log(message));

const circularData = {};
circularData.foo = circularData;
// Prints: { foo: [Circular] }
port2.postMessage(circularData);

'use strict';

const { MessageChannel } = require('node:worker_threads');
const { port1, port2 } = new MessageChannel();

port1.on('message', (message) => console.log(message));

const circularData = {};
circularData.foo = circularData;
// Prints: { foo: [Circular] }
port2.postMessage(circularData);

transferList может быть списком объектов <ArrayBuffer>, MessagePort и FileHandle. После передачи они становятся недоступны на отправляющей стороне канала (даже если они не входят в value). В отличие от дочерних процессов, передача дескрипторов, таких как сетевые сокеты, в настоящее время не поддерживается.

Если value содержит экземпляры <SharedArrayBuffer>, к ним можно обращаться из любого потока. Их нельзя указывать в transferList.

value может содержать экземпляры ArrayBuffer, не включённые в transferList; в этом случае базовая память копируется, а не перемещается.

import { MessageChannel } from 'node:worker_threads';
const { port1, port2 } = new MessageChannel();

port1.on('message', (message) => console.log(message));

const uint8Array = new Uint8Array([ 1, 2, 3, 4 ]);
// This posts a copy of `uint8Array`:
port2.postMessage(uint8Array);
// This does not copy data, but renders `uint8Array` unusable:
port2.postMessage(uint8Array, [ uint8Array.buffer ]);

// The memory for the `sharedUint8Array` is accessible from both the
// original and the copy received by `.on('message')`:
const sharedUint8Array = new Uint8Array(new SharedArrayBuffer(4));
port2.postMessage(sharedUint8Array);

// This transfers a freshly created message port to the receiver.
// This can be used, for example, to create communication channels between
// multiple `Worker` threads that are children of the same parent thread.
const otherChannel = new MessageChannel();
port2.postMessage({ port: otherChannel.port1 }, [ otherChannel.port1 ]);

'use strict';

const { MessageChannel } = require('node:worker_threads');
const { port1, port2 } = new MessageChannel();

port1.on('message', (message) => console.log(message));

const uint8Array = new Uint8Array([ 1, 2, 3, 4 ]);
// This posts a copy of `uint8Array`:
port2.postMessage(uint8Array);
// This does not copy data, but renders `uint8Array` unusable:
port2.postMessage(uint8Array, [ uint8Array.buffer ]);

// The memory for the `sharedUint8Array` is accessible from both the
// original and the copy received by `.on('message')`:
const sharedUint8Array = new Uint8Array(new SharedArrayBuffer(4));
port2.postMessage(sharedUint8Array);

// This transfers a freshly created message port to the receiver.
// This can be used, for example, to create communication channels between
// multiple `Worker` threads that are children of the same parent thread.
const otherChannel = new MessageChannel();
port2.postMessage({ port: otherChannel.port1 }, [ otherChannel.port1 ]);

Объект сообщения клонируется немедленно, поэтому после отправки его можно изменять без побочных эффектов.

Дополнительные сведения о механизмах сериализации и десериализации, лежащих в основе этого API, см. в API сериализации модуля node:v8.

const ab = new ArrayBuffer(10);

const u1 = new Uint8Array(ab);
const u2 = new Uint16Array(ab);

console.log(u2.length);  // prints 5

port.postMessage(u1, [u1.buffer]);

console.log(u2.length);  // prints 0 copy

const b = Symbol('b');

class Foo {
  #a = 1;
  constructor() {
    this[b] = 2;
    this.c = 3;
  }

  get d() { return 4; }
}

const { port1, port2 } = new MessageChannel();

port1.onmessage = ({ data }) => console.log(data);

port2.postMessage(new Foo());

// Prints: { c: 3 } copy

const { port1, port2 } = new MessageChannel();

port1.onmessage = ({ data }) => console.log(data);

port2.postMessage(new URL('https://example.org'));

// Prints: { } copy

port.hasRef()

• Возвращает: <boolean>

Если значение равно true, объект MessagePort будет поддерживать активность цикла событий Node.js.

port.ref()

Противоположность unref(). Вызов ref() для порта, ранее подвергнутого unref(), не позволит программе завершиться, если это единственный оставшийся активный дескриптор (поведение по умолчанию). Если порт подвергнут ref(), повторный вызов ref() не даст результата.

Если обработчики добавляются или удаляются с помощью .on('message'), порт автоматически подвергается ref() или unref() в зависимости от наличия обработчиков события.

port.start()

Начинает получать сообщения через этот MessagePort. При использовании этого порта в качестве источника событий метод вызывается автоматически после добавления обработчиков событий 'message'.

Этот метод существует для совместимости с API Web MessagePort. В Node.js он полезен только для игнорирования сообщений, когда обработчик события отсутствует. Node.js также отличается обработкой .onmessage. Установка этого параметра автоматически вызывает .start(), но его сброс приводит к тому, что сообщения накапливаются в очереди, пока не будет назначен новый обработчик или порт не будет удалён.

port.unref()

Вызов unref() для порта позволяет потоку завершить работу, если это единственный активный дескриптор в системе событий. Если порт уже подвергнут unref(), повторный вызов unref() не даст результата.

Если обработчики добавляются или удаляются с помощью .on('message'), порт автоматически подвергается ref() или unref() в зависимости от наличия обработчиков события.

new Worker(filename[, options])

• filename <string> | <URL> Путь к основному скрипту или модулю Worker. Должен быть абсолютным или относительным путем (то есть относительно текущего рабочего каталога), начинающимся с ./ или ../, либо объектом WHATWG URL с использованием протокола file: или data:. При использовании URL data: данные интерпретируются на основе MIME-типа с использованием загрузчика модулей ECMAScript. Если options.eval имеет значение true, это строка с кодом JavaScript, а не путь.
• options <Object>
  • argv <any[]> Список аргументов, которые будут преобразованы в строки и добавлены к process.argv в Worker. Это во многом аналогично workerData, но значения доступны в глобальном объекте process.argv, как если бы они были переданы скрипту в качестве параметров CLI.
  • env <Object> Если задано, указывает начальное значение process.env в потоке Worker. В качестве специального значения можно использовать worker.SHARE_ENV, чтобы указать, что родительский и дочерний потоки должны использовать общие переменные окружения; в этом случае изменения объекта process.env одного потока влияют и на другой поток. По умолчанию: process.env.
  • eval <boolean> Если имеет значение true и первый аргумент является string, первый аргумент конструктора интерпретируется как скрипт, который выполняется после запуска Worker.
  • execArgv <string[]> Список параметров CLI Node.js, передаваемых Worker. Параметры V8 (например, --max-old-space-size) и параметры, влияющие на процесс (например, --title), не поддерживаются. Если задано, это значение доступно в Worker как process.execArgv. По умолчанию параметры наследуются от родительского потока.
  • stdin <boolean> Если этому параметру присвоено значение true, то worker.stdin предоставляет записываемый поток, содержимое которого становится доступно в Worker как process.stdin. По умолчанию данные не предоставляются.
  • stdout <boolean> Если этому параметру присвоено значение true, то worker.stdout не перенаправляется автоматически в process.stdout родительского потока.
  • stderr <boolean> Если этому параметру присвоено значение true, то worker.stderr не перенаправляется автоматически в process.stderr родительского потока.
  • workerData <any> Любое значение JavaScript, которое копируется и становится доступным как require('node:worker_threads').workerData. Копирование выполняется согласно алгоритму структурного клонирования HTML; если объект невозможно скопировать (например, если он содержит объекты function), возникает ошибка.
  • trackUnmanagedFds <boolean> Если этому параметру присвоено значение true, Worker отслеживает дескрипторы файлов низкого уровня, управляемые через fs.open() и fs.close(), и закрывает их при завершении Worker, как и другие ресурсы, например сетевые сокеты или дескрипторы файлов, управляемые через API FileHandle. Этот параметр автоматически наследуется всеми вложенными объектами Worker. По умолчанию: true.
  • transferList <Object[]> Если в workerData передан один или несколько объектов типа MessagePort, для этих элементов необходимо указать transferList, иначе возникает ошибка ERR_MISSING_MESSAGE_PORT_IN_TRANSFER_LIST. Подробнее см. в разделе port.postMessage().
  • resourceLimits <Object> Необязательный набор ограничений ресурсов для нового экземпляра движка JS. Достижение этих пределов приводит к завершению экземпляра Worker. Эти ограничения влияют только на движок JS и не распространяются на внешние данные, включая объекты ArrayBuffer. Даже при заданных ограничениях процесс все равно может аварийно завершиться при глобальной нехватке памяти.
    • maxOldGenerationSizeMb <number> Максимальный размер основной кучи в МБ. Если задан аргумент командной строки --max-old-space-size, он переопределяет это значение.
    • maxYoungGenerationSizeMb <number> Максимальный размер области кучи для недавно созданных объектов. Если задан аргумент командной строки --max-semi-space-size, он переопределяет это значение.
    • codeRangeSizeMb <number> Размер предварительно выделенного диапазона памяти, используемого для сгенерированного кода.
    • stackSizeMb <number> Максимальный размер стека по умолчанию для потока. Небольшие значения могут привести к тому, что экземпляры Worker станут непригодными для использования. По умолчанию: 4.
  • name <string> Необязательное значение name, добавляемое к заголовку Worker для отладки или идентификации; итоговый заголовок имеет вид [worker ${id}] ${name}. По умолчанию: ''.

Событие: 'error'

• err <Error>

Событие 'error' генерируется, если в потоке Worker возникает необработанное исключение. В этом случае Worker завершается.

Событие: 'exit'

• exitCode <integer>

Событие 'exit' генерируется после остановки Worker. Если Worker завершился вызовом process.exit(), параметр exitCode содержит переданный код завершения. Если Worker был принудительно остановлен, параметр exitCode имеет значение 1.

Это последнее событие, генерируемое любым экземпляром Worker.

Событие: 'message'

• value <any> Переданное значение

Событие 'message' генерируется, когда поток Worker вызывает require('node:worker_threads').parentPort.postMessage(). Подробнее см. в описании события port.on('message').

Все сообщения, отправленные из потока Worker, генерируются до события 'exit' объекта Worker.

Событие: 'messageerror'

• error <Error> Объект Error

Событие 'messageerror' генерируется, если при десериализации сообщения произошла ошибка.

Событие: 'online'

Событие 'online' генерируется, когда поток Worker начинает выполнять код JavaScript.

worker.cpuUsage([prev])

• Возвращает: <Promise>

Этот метод возвращает Promise, который разрешается объектом, идентичным результату process.threadCpuUsage(), либо отклоняется с ошибкой ERR_WORKER_NOT_RUNNING, если Worker больше не выполняется. Этот метод позволяет получать статистику извне самого потока.

worker.getHeapSnapshot([options])

• options <Object>
  • exposeInternals <boolean> Если значение равно true, во снимке кучи отображаются внутренние данные. По умолчанию: false.
  • exposeNumericValues <boolean> Если значение равно true, числовые значения отображаются в искусственных полях. По умолчанию: false.
• Возвращает: <Promise> Промис для читаемого потока, содержащего снимок кучи V8

Возвращает читаемый поток со снимком текущего состояния Worker в V8. Подробнее см. в разделе v8.getHeapSnapshot().

Если поток Worker больше не выполняется, что может произойти до генерации события 'exit', возвращенный Promise немедленно отклоняется с ошибкой ERR_WORKER_NOT_RUNNING.

worker.getHeapStatistics()

• Возвращает: <Promise>

Этот метод возвращает Promise, который разрешается объектом, идентичным результату v8.getHeapStatistics(), либо отклоняется с ошибкой ERR_WORKER_NOT_RUNNING, если Worker больше не выполняется. Этот метод позволяет получать статистику извне самого потока.

worker.performance

Объект, с помощью которого можно получать данные о производительности экземпляра Worker. Аналогичен perf_hooks.performance.

import { Worker, isMainThread, parentPort } from 'node:worker_threads';

if (isMainThread) {
  const worker = new Worker(new URL(import.meta.url));
  setInterval(() => {
    worker.postMessage('hi');
    console.log(worker.performance.eventLoopUtilization());
  }, 100).unref();
} else {
  parentPort.on('message', () => console.log('msg')).unref();
  (function r(n) {
    if (--n < 0) return;
    const t = Date.now();
    while (Date.now() - t < 300);
    setImmediate(r, n);
  })(10);
}

'use strict';

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

if (isMainThread) {
  const worker = new Worker(__filename);
  setInterval(() => {
    worker.postMessage('hi');
    console.log(worker.performance.eventLoopUtilization());
  }, 100).unref();
} else {
  parentPort.on('message', () => console.log('msg')).unref();
  (function r(n) {
    if (--n < 0) return;
    const t = Date.now();
    while (Date.now() - t < 300);
    setImmediate(r, n);
  })(10);
}

worker.postMessage(value[, transferList])

• value <any>
• transferList <Object[]>

Отправляет сообщение Worker, которое принимается через require('node:worker_threads').parentPort.on('message'). Подробнее см. в разделе port.postMessage().

worker.ref()

Противоположность unref(): вызов ref() для Worker, ранее вызвавшего unref(), не позволяет программе завершиться, если он остается единственным активным дескриптором (поведение по умолчанию). Если для Worker был вызван ref(), повторный вызов ref() не дает эффекта.

worker.resourceLimits

• Тип: <Object>
  • maxYoungGenerationSizeMb <number>
  • maxOldGenerationSizeMb <number>
  • codeRangeSizeMb <number>
  • stackSizeMb <number>

Предоставляет набор ограничений ресурсов движка JS для этого потока Worker. Если конструктору Worker был передан параметр resourceLimits, возвращаемое значение соответствует его значениям.

Если Worker остановлен, возвращается пустой объект.

worker.startCpuProfile(name)

• имя: <string>
• Возвращает: <Promise>

Запускает профилирование ЦП с указанным name, а затем возвращает Promise, который выполняется с ошибкой или объектом с методом stop. Вызов метода stop останавливает сбор данных профиля, после чего возвращается Promise, который выполняется с ошибкой или данными профиля.

const { Worker } = require('node:worker_threads');

const worker = new Worker(`
  const { parentPort } = require('worker_threads');
  parentPort.on('message', () => {});
  `, { eval: true });

worker.on('online', async () => {
  const handle = await worker.startCpuProfile('demo');
  const profile = await handle.stop();
  console.log(profile);
  worker.terminate();
}); copy

worker.stderr

• Тип: <stream.Readable>

Это читаемый поток, содержащий данные, записанные в process.stderr в потоке Worker. Если конструктору Worker не передан параметр stderr: true, данные перенаправляются в поток process.stderr родительского потока.

worker.stdin

• Тип: <null> | <stream.Writable>

Если конструктору Worker передан параметр stdin: true, это записываемый поток. Данные, записанные в этот поток, становятся доступны в потоке Worker как process.stdin.

worker.stdout

• Тип: <stream.Readable>

Это читаемый поток, содержащий данные, записанные в process.stdout в потоке Worker. Если конструктору Worker не передан параметр stdout: true, данные перенаправляются в поток process.stdout родительского потока.

worker.terminate()

• Возвращает: <Promise>

Как можно скорее останавливает выполнение всего кода JavaScript в потоке Worker. Возвращает Promise с кодом завершения, который выполняется при генерации события 'exit'.

worker.threadId

• Тип: <integer>

Целочисленный идентификатор указанного потока. Внутри потока Worker он доступен как require('node:worker_threads').threadId. Это значение уникально для каждого экземпляра Worker в пределах одного процесса.

worker.threadName

• <string> | <null>

Строковый идентификатор указанного потока или null, если поток не выполняется. Внутри потока Worker он доступен как require('node:worker_threads').threadName.

worker.unref()

Вызов unref() для Worker позволяет потоку завершиться, если он остается единственным активным дескриптором в системе событий. Если для Worker уже был вызван unref(), повторный вызов unref() не дает эффекта.

worker[Symbol.asyncDispose]()

Псевдоним для worker.terminate().

Синхронная блокировка стандартных потоков ввода-вывода

Worker используют передачу сообщений через <MessagePort> для взаимодействия с stdio. Это означает, что вывод stdio, поступающий из Worker, может быть заблокирован синхронным кодом на принимающей стороне, если этот код блокирует цикл событий Node.js.

import {
  Worker,
  isMainThread,
} from 'node:worker_threads';

if (isMainThread) {
  new Worker(new URL(import.meta.url));
  for (let n = 0; n < 1e10; n++) {
    // Looping to simulate work.
  }
} else {
  // This output will be blocked by the for loop in the main thread.
  console.log('foo');
}

'use strict';

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

if (isMainThread) {
  new Worker(__filename);
  for (let n = 0; n < 1e10; n++) {
    // Looping to simulate work.
  }
} else {
  // This output will be blocked by the for loop in the main thread.
  console.log('foo');
}

Запуск потоков Worker из скриптов предварительной загрузки

Будьте осторожны при запуске потоков Worker из скриптов предварительной загрузки (скриптов, загружаемых и запускаемых с помощью флага командной строки -r). Если параметр execArgv явно не задан, новые потоки Worker автоматически наследуют флаги командной строки запущенного процесса и предварительно загружают те же скрипты, что и основной поток. Если скрипт предварительной загрузки безусловно запускает поток Worker, каждый запущенный поток будет порождать новый, пока приложение не завершится сбоем.