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)`