MessagePort - worker_threads - Node

class MessagePort

extends EventEmitter

Usage in Deno

import { MessagePort } from "node:worker_threads";

Instances of the worker.MessagePort class represent one end of an asynchronous, two-way communications channel. It can be used to transfer structured data, memory regions and other MessagePorts between different Workers.

This implementation matches browser MessagePort s.

Properties



addEventListener: EventTarget["addEventListener"]



dispatchEvent: EventTarget["dispatchEvent"]



removeEventListener: EventTarget["removeEventListener"]

Methods



addListener(event: "close",
listener: () => void,
): this



addListener(event: "message",
listener: (value: any) => void,
): this



addListener(event: "messageerror",
listener: (error: Error) => void,
): this



addListener(event: string | symbol,
listener: (...args: any[]) => void,
): this



close(): void

Disables further sending of messages on either side of the connection. This method can be called when no further communication will happen over this MessagePort.

The 'close' event is emitted on both MessagePort instances that are part of the channel.



emit(event: "close"): boolean



emit(event: "message",
value: any,
): boolean



emit(event: "messageerror",
error: Error,
): boolean



emit(event: string | symbol,
...args: any[],
): boolean



off(event: "close",
listener: () => void,
): this



off(event: "message",
listener: (value: any) => void,
): this



off(event: "messageerror",
listener: (error: Error) => void,
): this



off(event: string | symbol,
listener: (...args: any[]) => void,
): this



on(event: "close",
listener: () => void,
): this



on(event: "message",
listener: (value: any) => void,
): this



on(event: "messageerror",
listener: (error: Error) => void,
): this



on(event: string | symbol,
listener: (...args: any[]) => void,
): this



once(event: "close",
listener: () => void,
): this



once(event: "message",
listener: (value: any) => void,
): this



once(event: "messageerror",
listener: (error: Error) => void,
): this



once(event: string | symbol,
listener: (...args: any[]) => void,
): this



postMessage(value: any,
transferList?: readonly TransferListItem[],
): void

Sends a JavaScript value to the receiving side of this channel. value is transferred in a way which is compatible with the HTML structured clone algorithm.

In particular, the significant differences to JSON are:

value may contain circular references.
value may contain instances of builtin JS types such as RegExps, BigInts, Maps, Sets, etc.
value may contain typed arrays, both using ArrayBuffers and SharedArrayBuffers.
value may contain WebAssembly.Module instances.
value may not contain native (C++-backed) objects other than:

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);

transferList may be a list of ArrayBuffer, MessagePort, and FileHandle objects. After transferring, they are not usable on the sending side of the channel anymore (even if they are not contained in value). Unlike with child processes, transferring handles such as network sockets is currently not supported.

If value contains SharedArrayBuffer instances, those are accessible from either thread. They cannot be listed in transferList.

value may still contain ArrayBuffer instances that are not in transferList; in that case, the underlying memory is copied rather than moved.

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 ]);

The message object is cloned immediately, and can be modified after posting without having side effects.

For more information on the serialization and deserialization mechanisms behind this API, see the serialization API of the node:v8 module.



prependListener(event: "close",
listener: () => void,
): this



prependListener(event: "message",
listener: (value: any) => void,
): this



prependListener(event: "messageerror",
listener: (error: Error) => void,
): this



prependListener(event: string | symbol,
listener: (...args: any[]) => void,
): this



prependOnceListener(event: "close",
listener: () => void,
): this



prependOnceListener(event: "message",
listener: (value: any) => void,
): this



prependOnceListener(event: "messageerror",
listener: (error: Error) => void,
): this



prependOnceListener(event: string | symbol,
listener: (...args: any[]) => void,
): this



ref(): void

Opposite of unref(). Calling ref() on a previously unref()ed port does not let the program exit if it's the only active handle left (the default behavior). If the port is ref()ed, calling ref() again has no effect.

If listeners are attached or removed using .on('message'), the port is ref()ed and unref()ed automatically depending on whether listeners for the event exist.



removeListener(event: "close",
listener: () => void,
): this



removeListener(event: "message",
listener: (value: any) => void,
): this



removeListener(event: "messageerror",
listener: (error: Error) => void,
): this



removeListener(event: string | symbol,
listener: (...args: any[]) => void,
): this



start(): void

Starts receiving messages on this MessagePort. When using this port as an event emitter, this is called automatically once 'message' listeners are attached.

This method exists for parity with the Web MessagePort API. In Node.js, it is only useful for ignoring messages when no event listener is present. Node.js also diverges in its handling of .onmessage. Setting it automatically calls .start(), but unsetting it lets messages queue up until a new handler is set or the port is discarded.



unref(): void

Calling unref() on a port allows the thread to exit if this is the only active handle in the event system. If the port is already unref()ed calling unref() again has no effect.

If listeners are attached or removed using .on('message'), the port is ref()ed and unref()ed automatically depending on whether listeners for the event exist.

variable MessagePort

MessagePort class is a global reference for import { MessagePort } from 'worker_threads' https://nodejs.org/api/globals.html#messageport

Type

globalThis extends { onmessage: any; MessagePort: infer T;  } ? T : _MessagePort