Skip to content
Tutorials Center
My learning

Topics

Node.js Reference ยท child_process, worker_threads and cluster

Node.js receiveMessageOnPort() function

Reference for receiveMessageOnPort() in worker_threads: read one queued message from a MessagePort without waiting, the wrapper object, and the Atomics.wait pattern.

receiveMessageOnPort(port) takes the oldest message waiting in a MessagePort's queue and returns it immediately, without an event handler and without await. If the queue is empty it returns undefined.

Normally messages arrive through the 'message' event, which runs on a later turn of the event loop. receiveMessageOnPort() is for the cases where you need the answer right now, in the middle of synchronous code: for example a worker that blocks with Atomics.wait() until another thread has posted a reply.

NODE
import { MessageChannel, receiveMessageOnPort } from "node:worker_threads";

const { port1, port2 } = new MessageChannel();
port1.postMessage("hello");
const result = receiveMessageOnPort(port2); // { message: "hello" }

Try it

Node.js Reading a queue by hand

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Node.js Blocking until another thread replies

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Syntax

NODE
worker_threads.receiveMessageOnPort(port: MessagePort | BroadcastChannel): { message: any } | undefined
Name Description
port The MessagePort (or BroadcastChannel) whose queue should be read.

Returns: an object { message } containing the oldest queued message, or undefined if no message is waiting. The wrapper is what lets you tell "a message whose value is undefined" from "no message".

Errors: throws ERR_INVALID_ARG_TYPE if port is not a MessagePort or BroadcastChannel. Receiving a message that cannot be deserialized throws as well.

Usage notes

  • It takes the message away. A message read this way is removed from the queue, so a 'message' listener on the same port will not see it.
  • No waiting. The function only looks at what has already arrived; it does not block for new messages. To wait, combine it with Atomics.wait() on a SharedArrayBuffer as in the second example, or poll.
  • Messages posted on the same thread are available at once. After port1.postMessage(x) you can read x from port2 in the same tick, which makes ports useful as plain queues in tests.
  • The main thread may block with Atomics.wait() in Node.js (unlike browsers), but blocking stalls its event loop. Do it only in short, controlled cases or inside workers.
  • Attaching a listener starts the flow: port.on("message", ...) or port.start() makes the port deliver messages by events; do not mix both styles on one port unless you know which messages each will receive.
  • Remember to close ports (port.close()), or the open handle can keep the process alive.
  • Typical use: a synchronous RPC where a worker serves requests from a main thread that cannot await, such as a synchronous API wrapped around asynchronous work.