Node.js Reference ยท process
Node.js process.send() method and the message event
Reference for process.send(), process.connected, process.disconnect() and the message event in Node.js: talk to a parent process over an IPC channel.
A Node.js process started with an IPC channel (by child_process.fork(), or by spawn() with an 'ipc' entry in stdio) can exchange messages with its parent. Inside the child, process.send(message) sends a message up to the parent, and the message event on process fires for every message the parent sends down. The parent uses child.send() and child.on('message').
Messages are serialized for you (JSON by default, or the structured-clone-like 'advanced' serialization), so you can pass plain objects, arrays and numbers without any framing. When the process was not started with a channel, process.send is undefined, which is the easy way to detect it.
if (process.send) { process.send({ ready: true }); } process.on('message', (msg) => { /* ... */ });
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
process.send( message: object | string | number | boolean | null, sendHandle?: net.Socket | net.Server, options?: { keepOpen?: boolean }, callback?: (error: Error | null) => void ): boolean process.on('message', (message, sendHandle) => { }) process.connected: boolean process.disconnect(): void
| Name | Description |
|---|---|
message |
The value to send. It must be serializable; functions, symbols and cyclic structures are not. |
sendHandle |
Optional TCP socket or server to hand over to the other process. |
options.keepOpen |
Keep the handle open in the sender after sending a socket. |
callback |
Called after the message was sent, with an error or null. |
Returns: true unless the channel's queue is backed up, in which case it returns false. The message is still queued; use the callback to pace a fast sender.
Errors / edge cases:
- With no channel,
process.send,process.disconnect,process.connectedandprocess.channelare allundefined, so calling them throws aTypeError. - Sending after the channel closed emits an
errorevent on the process (or calls the callback withERR_IPC_CHANNEL_CLOSED), so checkprocess.connected. - On the receiving side the
disconnectevent fires when the other end closes the channel.
Usage notes
- Detect the channel with
if (process.send)orprocess.connected. A script that is run both on its own and as a forked worker can behave differently in each case. - The child stays alive as long as the channel is open and a
messagelistener exists. Callprocess.disconnect()(or remove the listener) when the conversation is finished, as the example does, or the child will not exit by itself. - JSON limits. With the default serialization,
Map,Set,Date(becomes a string),undefinedandBigIntdo not survive. Fork with{ serialization: 'advanced' }for structured-clone behaviour includingBigIntand typed arrays. - Messages are asynchronous and ordered;
senddoes not wait for the other process to handle them. - Large messages are slow. The channel is a pipe. For big data use files or streams on stdio.
- For threads, not processes, use
worker_threadsandparentPort.postMessage(), which is faster and supports transferables. - Handle passing lets a parent distribute accepted TCP connections to children; the cluster module is built on this.