superchild
v0.1.10
Published
A smarter replacement for node.js's child_process module.
Downloads
2,222
Maintainers
Readme
Superchild is a POSIX-only (e.g., Linux, Mac OS X) wrapper around
node.js's built-in child_process
module, which requires a lot of
care and attention to use correctly.
Links:
The purpose of Superchild is to allow large node.js programs to be split into independent processes (and sub-processes, resulting in process trees), while handling the tedious parts of process management and communication.
Superchild aims to be compatible with any program
that reads from and writes to their stdin
, stdout
, and stderr
streams, regardless of what language the program is written in.
This allows interesting hacks like using ssh
to execute a
module on a remote host, written in another language, over an
encrypted link, while using the near-universal format of
line-delimited JSON messages over stdio
.
Features that make Superchild different from node's built-in
child_process
module include the following (many of these
are currently possible only due to restricting focus to POSIX
platforms, i.e., not Windows):
A single function to replace
fork()
,exec()
, andspawn()
from the built-inchild_process
module.Waits for
stdout
andstderr
streams to end before emitting anexit
event, unlikechild_process.ChildProcess
.Handles isolating child process and its children in a separate, detached process group that can be terminated as a subtree using the POSIX
kill
command. This means that callingclose()
on a Superchild instance will kill not just the child process, but all its child processes and so on (i.e., the entire process group lead by the child). Note that if any processes in the sub-tree detach themselves into a new process group, they will not be part of our child's process group, and will not be killed.Handles graceful termination of child's entire process group using
SIGTERM
->SIGKILL
signals with a configurable timeout.Handles unexpected termination of the current process by killing the child's entire process group immediately with
SIGKILL
.Automatically serializes and deserializes line-delimited JSON values (LD-JSON) sent to and received from child, intermixed with
stdout
.stderr
is passed through unbuffered. Effectively, this means that the child'sstdout
stream is demultiplexed into the child streamsstdout_line
(parsed raw text lines),json_object
(parsed JSON objects), andjson_array
(parsed JSON arrays). Regular processes have 3 I/O streams (stdin, stdout, stderr); Superchildren have 6 streams (stdin, stdout, stderr, stdout_line, json_object, json_array).
Install
npm install superchild
Usage
Run a shell command
Get a directory listing line-by-line using ls
.
var superchild = require('superchild');
var child = superchild('ls -lh');
child.on('stdout_line', function(line) {
console.log('[stdout]: ', line);
});
Spawn and communicate with a module
Spawn a node.js module in another process and communicate with it.
Note that the child uses the superchild.unlogger
helper function
to parse its standard input for LD-JSON arrays and objects.
master.js
var assert = require('assert');
var superchild = require('superchild');
var child = superchild('node echo.js');
child.send({
some: 'data',
});
child.on('json_object', function(jsonObj) {
assert.equal(jsonObj.some, 'data');
});
echo.js
var unlogger = require('superchild').unlogger;
unlogger().on('json_object', function(jsonObj) {
// Echo JSON object from parent back to parent.
console.log(JSON.stringify(jsonObj));
});
Events emitted
Superchild is an EventEmitter. The following events can be listened for
using child.on()
and child.once()
functions.
| Event | Arguments | Description |
| ---------------| -------------------------|---------------------------------------------------------|
| exit
| code
, signal
| Child process exited, identical to child_process.exit
|
| stderr_data
| dataStr
| Received unbuffered data on child's stderr
stream. |
| stdout_line
| lineStr
| Received a full line of text from the child process. |
| json_object
| jsonObj
| Parsed a line-delimited JSON object from child's stdout
stream. |
| json_array
| jsonArr
| Parsed a line-delimited JSON array from child's stdout
stream. |
Methods
| Method | Description |
| ----------------| -------------------------------------------------------------------------------|
| send(jsonVal)
| Serialize and send a JSON-serializable object or array to the child as LD-JSON.|
| close(cb)
| Gracefully terminate the child, invoking the callback when the child has died. |
Requirements
node.js
version 0.11.13 or higher, due to the use ofspawnSync
.- POSIX-compliant platform, such as Linux or Mac OS.
Source Code
The full annotated source code of superchild.js
follows, generated
automatically by Docco.
Helper utilities
Class JSONSieve
, parses a readable stream into JSON objects and arrays, and stdout lines.function unlogger()
, an example of establishing bi-directional communication between a parent and child that can be easily ported to many other languages.