Skip to content
Tutorials Center
My learning

Topics

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.

NODE
// 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

Node.js A request and reply protocol over IPC

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 JSON versus advanced serialization

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 call process.exit() in the child.
  • Order is preserved per direction, but there are no replies built in. For request and reply, add an id to 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.send is undefined when there is no channel, so guard with if (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.