From bd880e7f3fc882a2161db30f5f9f2008047224e4 Mon Sep 17 00:00:00 2001 From: isaacs Date: Mon, 27 Feb 2012 11:04:08 -0800 Subject: [PATCH] s/child_processes/child_process/ --- doc/about/index.html | 2 +- doc/api/_toc.markdown | 2 +- doc/api/all.markdown | 2 +- ...cesses.markdown => child_process.markdown} | 173 ++++++++++++++---- 4 files changed, 140 insertions(+), 39 deletions(-) rename doc/api/{child_processes.markdown => child_process.markdown} (68%) diff --git a/doc/about/index.html b/doc/about/index.html index 49688c3f10..bd0d122f51 100644 --- a/doc/about/index.html +++ b/doc/about/index.html @@ -102,7 +102,7 @@ console.log('Server running at http://127.0.0.1:1337/');

But what about multiple-processor concurrency? Aren't threads necessary to scale programs to multi-core computers? You can start new processes via child_process.fork() + href="http://nodejs.org/docs/latest/api/child_process.html#child_process.fork">child_process.fork() these other processes will be scheduled in parallel. For load balancing incoming connections across multiple processes use the diff --git a/doc/api/_toc.markdown b/doc/api/_toc.markdown index 4c8f33baea..ec37a578d2 100644 --- a/doc/api/_toc.markdown +++ b/doc/api/_toc.markdown @@ -26,7 +26,7 @@ * [Readline](readline.html) * [REPL](repl.html) * [VM](vm.html) -* [Child Processes](child_processes.html) +* [Child Processes](child_process.html) * [Assertion Testing](assert.html) * [TTY](tty.html) * [ZLIB](zlib.html) diff --git a/doc/api/all.markdown b/doc/api/all.markdown index b35b746e20..8b5ae257d3 100644 --- a/doc/api/all.markdown +++ b/doc/api/all.markdown @@ -24,7 +24,7 @@ @include readline @include repl @include vm -@include child_processes +@include child_process @include assert @include tty @include zlib diff --git a/doc/api/child_processes.markdown b/doc/api/child_process.markdown similarity index 68% rename from doc/api/child_processes.markdown rename to doc/api/child_process.markdown index 57aa945209..3349617ef2 100644 --- a/doc/api/child_processes.markdown +++ b/doc/api/child_process.markdown @@ -1,21 +1,32 @@ -## Child Processes +# Child Process -Node provides a tri-directional `popen(3)` facility through the `ChildProcess` -class. +Node provides a tri-directional `popen(3)` facility through the +`child_process` module. -It is possible to stream data through the child's `stdin`, `stdout`, and +It is possible to stream data through a child's `stdin`, `stdout`, and `stderr` in a fully non-blocking way. -To create a child process use `require('child_process').spawn()`. +To create a child process use `require('child_process').spawn()` or +`require('child_process').fork()`. The semantics of each are slightly +different, and explained below. -Child processes always have three streams associated with them. `child.stdin`, -`child.stdout`, and `child.stderr`. +## Class: ChildProcess `ChildProcess` is an `EventEmitter`. +Child processes always have three streams associated with them. `child.stdin`, +`child.stdout`, and `child.stderr`. These may be shared with the stdio +streams of the parent process, or they may be separate stream objects +which can be piped to and from. + +The ChildProcess class is not intended to be used directly. Use the +`spawn()` or `fork()` methods to create a Child Process instance. + ### Event: 'exit' -`function (code, signal) {}` +* `code` {Number} the exit code, if it exited normally. +* `signal` {String} the signal passed to kill the child process, if it + was killed by the parent. This event is emitted after the child process ends. If the process terminated normally, `code` is the final exit code of the process, otherwise `null`. If @@ -33,19 +44,36 @@ An alternative way to check if you can send messages is to see if the ### child.stdin +* {Stream object} + A `Writable Stream` that represents the child process's `stdin`. Closing this stream via `end()` often causes the child process to terminate. +If the child stdio streams are shared with the parent, then this will +not be set. + ### child.stdout +* {Stream object} + A `Readable Stream` that represents the child process's `stdout`. +If the child stdio streams are shared with the parent, then this will +not be set. + ### child.stderr +* {Stream object} + A `Readable Stream` that represents the child process's `stderr`. +If the child stdio streams are shared with the parent, then this will +not be set. + ### child.pid +* {Integer} + The PID of the child process. Example: @@ -56,8 +84,48 @@ Example: console.log('Spawned child pid: ' + grep.pid); grep.stdin.end(); +### child.kill([signal]) + +* `signal` {String} + +Send a signal to the child process. If no argument is given, the process will +be sent `'SIGTERM'`. See `signal(7)` for a list of available signals. + + var spawn = require('child_process').spawn, + grep = spawn('grep', ['ssh']); + + grep.on('exit', function (code, signal) { + console.log('child process terminated due to receipt of signal '+signal); + }); + + // send SIGHUP to process + grep.kill('SIGHUP'); + +Note that while the function is called `kill`, the signal delivered to the child +process may not actually kill it. `kill` really just sends a signal to a process. + +See `kill(2)` + +### child.send(message, [sendHandle]) + +* `message` {Object} +* `sendHandle` {Handle object} + +Send a message (and, optionally, a handle object) to a child process. + +See `child_process.fork()` for details. -### child_process.spawn(command, [args], [options]) +## child_process.spawn(command, [args], [options]) + +* `command` {String} The command to run +* `args` {Array} List of string arguments +* `options` {Object} + * `cwd` {String} Current working directory of the child process + * `customFds` {Array} **Deprecated** File descriptors for the child to use + for stdio. (See below) + * `env` {Object} Environment key-value pairs + * `setsid` {Boolean} +* return: {ChildProcess object} Launches a new process with the given `command`, with command line arguments in `args`. If omitted, `args` defaults to an empty Array. @@ -150,17 +218,34 @@ API. There is a deprecated option called `customFds` which allows one to specify specific file descriptors for the stdio of the child process. This API was not portable to all platforms and therefore removed. -With `customFds` it was possible to hook up the new process' [stdin, stdout, -stderr] to existing streams; `-1` meant that a new stream should be created. +With `customFds` it was possible to hook up the new process' `[stdin, stdout, +stderr]` to existing streams; `-1` meant that a new stream should be created. Use at your own risk. There are several internal options. In particular `stdinStream`, `stdoutStream`, `stderrStream`. They are for INTERNAL USE ONLY. As with all undocumented APIs in Node, they should not be used. -See also: `child_process.exec()` - -### child_process.exec(command, [options], callback) +See also: `child_process.exec()` and `child_process.fork()` + +## child_process.exec(command, [options], callback) + +* `command` {String} The command to run, with space-separated arguments +* `options` {Object} + * `cwd` {String} Current working directory of the child process + * `customFds` {Array} **Deprecated** File descriptors for the child to use + for stdio. (See below) + * `env` {Object} Environment key-value pairs + * `setsid` {Boolean} + * `encoding` {String} (Default: 'utf8') + * `timeout` {Number} (Default: 0) + * `maxBuffer` {Number} (Default: 200*1024) + * `killSignal` {String} (Default: 'SIGTERM') +* `callback` {Function} called with the output when process terminates + * `code` {Integer} Exit code + * `stdout` {Buffer} + * `stderr` {Buffer} +* Return: ChildProcess object Runs a command in a shell and buffers the output. @@ -182,7 +267,8 @@ will be `null`. On error, `error` will be an instance of `Error` and `err.code` will be the exit code of the child process, and `err.signal` will be set to the signal that terminated the process. -There is a second optional argument to specify several options. The default options are +There is a second optional argument to specify several options. The +default options are { encoding: 'utf8', timeout: 0, @@ -198,14 +284,48 @@ amount of data allowed on stdout or stderr - if this value is exceeded then the child process is killed. -### child_process.execFile(file, args, options, callback) +## child_process.execFile(file, args, options, callback) + +* `file` {String} The filename of the program to run +* `args` {Array} List of string arguments +* `options` {Object} + * `cwd` {String} Current working directory of the child process + * `customFds` {Array} **Deprecated** File descriptors for the child to use + for stdio. (See below) + * `env` {Object} Environment key-value pairs + * `setsid` {Boolean} + * `encoding` {String} (Default: 'utf8') + * `timeout` {Number} (Default: 0) + * `maxBuffer` {Number} (Default: 200*1024) + * `killSignal` {String} (Default: 'SIGTERM') +* `callback` {Function} called with the output when process terminates + * `code` {Integer} Exit code + * `stdout` {Buffer} + * `stderr` {Buffer} +* Return: ChildProcess object This is similar to `child_process.exec()` except it does not execute a subshell but rather the specified file directly. This makes it slightly leaner than `child_process.exec`. It has the same options. -### child_process.fork(modulePath, [arguments], [options]) +## child_process.fork(modulePath, [args], [options]) + +* `modulePath` {String} The module to run in the child +* `args` {Array} List of string arguments +* `options` {Object} + * `cwd` {String} Current working directory of the child process + * `customFds` {Array} **Deprecated** File descriptors for the child to use + for stdio. (See below) + * `env` {Object} Environment key-value pairs + * `setsid` {Boolean} + * `encoding` {String} (Default: 'utf8') + * `timeout` {Number} (Default: 0) +* `callback` {Function} called with the output when process terminates + * `code` {Integer} Exit code + * `stdout` {Buffer} + * `stderr` {Buffer} +* Return: ChildProcess object This is a special case of the `spawn()` functionality for spawning Node processes. In addition to having all the methods in a normal ChildProcess @@ -278,22 +398,3 @@ there is no IPC channel keeping it alive. When calling this method the `connected` flag will be set to `false`. Please note that you can also call `process.disconnect()` in the child process. -### child.kill([signal]) - -Send a signal to the child process. If no argument is given, the process will -be sent `'SIGTERM'`. See `signal(7)` for a list of available signals. - - var spawn = require('child_process').spawn, - grep = spawn('grep', ['ssh']); - - grep.on('exit', function (code, signal) { - console.log('child process terminated due to receipt of signal '+signal); - }); - - // send SIGHUP to process - grep.kill('SIGHUP'); - -Note that while the function is called `kill`, the signal delivered to the child -process may not actually kill it. `kill` really just sends a signal to a process. - -See `kill(2)`