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.
import { MessageChannel, receiveMessageOnPort } from "node:worker_threads"; const { port1, port2 } = new MessageChannel(); port1.postMessage("hello"); const result = receiveMessageOnPort(port2); // { message: "hello" }
Try it
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.
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
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 aSharedArrayBufferas in the second example, or poll. - Messages posted on the same thread are available at once. After
port1.postMessage(x)you can readxfromport2in 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", ...)orport.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.