Node.js Reference ยท child_process, worker_threads and cluster
Node.js child process IPC messaging
How inter-process messaging works in Node.js: child.send(), process.send(), the message event, JSON versus advanced serialization, disconnect and request patterns.
When a child process is started with an IPC channel, parent and child can exchange JavaScript values without any text protocol of their own. The parent calls child.send(value) and the child receives it in process.on('message', handler). The child answers with process.send(value), which fires 'message' on the parent's ChildProcess object.
The channel is created by fork() automatically, or by adding 'ipc' to the stdio array of spawn(). Messages are serialized, sent through a pipe (a Unix domain socket or a named pipe), and deserialized on the other side, so every message is a copy. IPC is one-to-one: a process has exactly one channel to its parent and one to each child it opened.
// parent child.send({ type: 'job', id: 1 }); child.on('message', (msg) => console.log(msg)); // child process.on('message', (msg) => process.send({ type: 'done', id: msg.id }));
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.
How it works
Sending
child.send(message[, sendHandle[, options]][, callback]) and process.send(...) have the same shape. They return true if the message was queued without exceeding the internal buffer; a false result means the channel is backed up. The optional callback is called after the message has been handed to the operating system, with an error or null. If the channel is closed, send() emits 'error' (or reports it to the callback) instead of throwing.
message is serialized with one of two formats, chosen by the serialization option of the child process:
| Format | Supports | Notes |
|---|---|---|
'json' (default) |
Plain data: objects, arrays, strings, numbers, booleans, null. |
undefined, functions and symbols are dropped, Date becomes a string, Map and Set become {}, and BigInt makes send() throw. |
'advanced' |
Everything the structured clone algorithm handles: Map, Set, Date, RegExp, BigInt, typed arrays, Error objects and cyclic references. |
Slower for tiny messages. Functions still cannot be cloned. |
Receiving
'message' handlers receive (message, sendHandle). The second argument is only used when a handle (for example a TCP server or socket) was sent. Messages with cmd values starting with NODE_ are reserved for Node.js itself and are not delivered to 'message' handlers.
Closing the channel
Either side can call disconnect() (child.disconnect() or process.disconnect()). Both ends then emit 'disconnect', connected becomes false, and the IPC channel stops keeping the processes alive. A child that exits closes the channel automatically.
Usage notes
- The channel keeps the event loop alive. A child with a
'message'listener and an open channel does not exit by itself. Disconnect, or callprocess.exit()in the child. - Order is preserved per direction, but there are no replies built in. For request and reply, add an
idto each message and match answers as the first example does. - Messages are copies. Changing an object after
send()does not change what the other side receives. For big binary data, use files or shared memory in worker threads. - Check
process.send. In a script that may run with or without a parent,process.sendisundefinedwhen there is no channel, so guard withif (process.send). - Messaging a parent that is not Node. Only processes created with the Node IPC protocol (in practice, Node children) understand the channel. See
process.send()for the child-side API. - Do not pass secrets lightly. The channel is private to the two processes, but anything you send is visible to the child's code. Do not send credentials to code you do not trust.
- Message sizes. There is no hard limit, but very large messages are serialized fully in memory and block the sender while they are encoded.