1berry/nodejs
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

doc: change child to subprocess

Browse Source 
PR-URL: https://github.com/nodejs/node/pull/14578
Reviewed-By: Colin Ihrig <cjihrig@gmail.com>
Reviewed-By: Luigi Pinca <luigipinca@gmail.com>
Reviewed-By: Refael Ackermann <refack@gmail.com>
This commit is contained in:
Rich Trott 2017-08-01 14:43:34 -07:00
parent 2dc09f656b
commit dd75005a9e
2 changed files with 98 additions and 94 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

184
doc/api/child_process.md
View File

@ -333,7 +333,7 @@ The `child_process.fork()` method is a special case of
Like [`child_process.spawn()`][], a [`ChildProcess`][] object is returned. The returned Like [`child_process.spawn()`][], a [`ChildProcess`][] object is returned. The returned
[`ChildProcess`][] will have an additional communication channel built-in that [`ChildProcess`][] will have an additional communication channel built-in that
allows messages to be passed back and forth between the parent and child. See allows messages to be passed back and forth between the parent and child. See
[`child.send()`][] for details. [`subprocess.send()`][] for details.
It is important to keep in mind that spawned Node.js child processes are It is important to keep in mind that spawned Node.js child processes are
independent of the parent with exception of the IPC communication channel independent of the parent with exception of the IPC communication channel
@ -472,10 +472,10 @@ Example of checking for failed `spawn`:
```js ```js
const { spawn } = require('child_process'); const { spawn } = require('child_process');
const child = spawn('bad_command'); const subprocess = spawn('bad_command');
child.on('error', (err) => { subprocess.on('error', (err) => {
console.log('Failed to start child process.'); console.log('Failed to start subprocess.');
}); });
``` ```
@ -503,10 +503,10 @@ child processes may continue running after the parent exits regardless of
whether they are detached or not. See setsid(2) for more information. whether they are detached or not. See setsid(2) for more information.
By default, the parent will wait for the detached child to exit. To prevent By default, the parent will wait for the detached child to exit. To prevent
the parent from waiting for a given `child`, use the `child.unref()` method. the parent from waiting for a given `subprocess`, use the `subprocess.unref()`
Doing so will cause the parent's event loop to not include the child in its method. Doing so will cause the parent's event loop to not include the child in
reference count, allowing the parent to exit independently of the child, unless its reference count, allowing the parent to exit independently of the child,
there is an established IPC channel between the child and parent. unless there is an established IPC channel between the child and parent.
When using the `detached` option to start a long-running process, the process When using the `detached` option to start a long-running process, the process
will not stay running in the background after the parent exits unless it is will not stay running in the background after the parent exits unless it is
@ -520,12 +520,12 @@ Example of a long-running process, by detaching and also ignoring its parent
```js ```js
const { spawn } = require('child_process'); const { spawn } = require('child_process');
const child = spawn(process.argv[0], ['child_program.js'], { const subprocess = spawn(process.argv[0], ['child_program.js'], {
detached: true, detached: true,
stdio: 'ignore' stdio: 'ignore'
}); });
child.unref(); subprocess.unref();
``` ```
Alternatively one can redirect the child process' output into files: Alternatively one can redirect the child process' output into files:
@ -536,12 +536,12 @@ const { spawn } = require('child_process');
const out = fs.openSync('./out.log', 'a'); const out = fs.openSync('./out.log', 'a');
const err = fs.openSync('./out.log', 'a'); const err = fs.openSync('./out.log', 'a');
const child = spawn('prg', [], { const subprocess = spawn('prg', [], {
detached: true, detached: true,
stdio: [ 'ignore', out, err ] stdio: [ 'ignore', out, err ]
}); });
child.unref(); subprocess.unref();
``` ```
#### options.stdio #### options.stdio
@ -555,9 +555,10 @@ changes:
The `options.stdio` option is used to configure the pipes that are established The `options.stdio` option is used to configure the pipes that are established
between the parent and child process. By default, the child's stdin, stdout, between the parent and child process. By default, the child's stdin, stdout,
and stderr are redirected to corresponding [`child.stdin`][], [`child.stdout`][], and and stderr are redirected to corresponding [`subprocess.stdin`][],
[`child.stderr`][] streams on the [`ChildProcess`][] object. This is equivalent to [`subprocess.stdout`][], and [`subprocess.stderr`][] streams on the
setting the `options.stdio` equal to `['pipe', 'pipe', 'pipe']`. [`ChildProcess`][] object. This is equivalent to setting the `options.stdio`
equal to `['pipe', 'pipe', 'pipe']`.
For convenience, `options.stdio` may be one of the following strings: For convenience, `options.stdio` may be one of the following strings:
@ -573,17 +574,18 @@ pipes between the parent and child. The value is one of the following:
1. `'pipe'` - Create a pipe between the child process and the parent process. 1. `'pipe'` - Create a pipe between the child process and the parent process.
The parent end of the pipe is exposed to the parent as a property on the The parent end of the pipe is exposed to the parent as a property on the
`child_process` object as [`child.stdio[fd]`][`stdio`]. Pipes created for `child_process` object as [`subprocess.stdio[fd]`][`stdio`]. Pipes created
fds 0 - 2 are also available as [`child.stdin`][], [`child.stdout`][] for fds 0 - 2 are also available as [`subprocess.stdin`][],
and [`child.stderr`][], respectively. [`subprocess.stdout`][] and [`subprocess.stderr`][], respectively.
2. `'ipc'` - Create an IPC channel for passing messages/file descriptors 2. `'ipc'` - Create an IPC channel for passing messages/file descriptors
between parent and child. A [`ChildProcess`][] may have at most *one* IPC stdio between parent and child. A [`ChildProcess`][] may have at most *one* IPC stdio
file descriptor. Setting this option enables the [`child.send()`][] method. file descriptor. Setting this option enables the [`subprocess.send()`][]
If the child writes JSON messages to this file descriptor, the method. If the child writes JSON messages to this file descriptor, the
[`child.on('message')`][`'message'`] event handler will be triggered in the parent. [`subprocess.on('message')`][`'message'`] event handler will be triggered in
If the child is a Node.js process, the presence of an IPC channel will enable the parent. If the child is a Node.js process, the presence of an IPC channel
[`process.send()`][], [`process.disconnect()`][], [`process.on('disconnect')`][], and will enable [`process.send()`][], [`process.disconnect()`][],
[`process.on('message')`] within the child. [`process.on('disconnect')`][], and [`process.on('message')`] within the
child.
3. `'ignore'` - Instructs Node.js to ignore the fd in the child. While Node.js 3. `'ignore'` - Instructs Node.js to ignore the fd in the child. While Node.js
will always open fds 0 - 2 for the processes it spawns, setting the fd to will always open fds 0 - 2 for the processes it spawns, setting the fd to
`'ignore'` will cause Node.js to open `/dev/null` and attach it to the `'ignore'` will cause Node.js to open `/dev/null` and attach it to the
@ -828,9 +830,10 @@ added: v0.7.2
--> -->
The `'disconnect'` event is emitted after calling the The `'disconnect'` event is emitted after calling the
[`child.disconnect()`][] method in parent process or [`process.disconnect()`][] in child process. After [`subprocess.disconnect()`][] method in parent process or
disconnecting it is no longer possible to send or receive messages, and the [`process.disconnect()`][] in child process. After disconnecting it is no longer
[`child.connected`][] property is `false`. possible to send or receive messages, and the [`subprocess.connected`][]
property is `false`.
### Event: 'error' ### Event: 'error'
@ -846,7 +849,7 @@ The `'error'` event is emitted whenever:
When listening to both the `'exit'` and `'error'` events, it is important When listening to both the `'exit'` and `'error'` events, it is important
to guard against accidentally invoking handler functions multiple times. to guard against accidentally invoking handler functions multiple times.
See also [`child.kill()`][] and [`child.send()`][]. See also [`subprocess.kill()`][] and [`subprocess.send()`][].
### Event: 'exit' ### Event: 'exit'
<!-- YAML <!-- YAML
@ -883,56 +886,56 @@ added: v0.5.9
The `'message'` event is triggered when a child process uses [`process.send()`][] The `'message'` event is triggered when a child process uses [`process.send()`][]
to send messages. to send messages.
### child.channel ### subprocess.channel
<!-- YAML <!-- YAML
added: v7.1.0 added: v7.1.0
--> -->
* {Object} A pipe representing the IPC channel to the child process. * {Object} A pipe representing the IPC channel to the child process.
The `child.channel` property is a reference to the child's IPC channel. If no The `subprocess.channel` property is a reference to the child's IPC channel. If
IPC channel currently exists, this property is `undefined`. no IPC channel currently exists, this property is `undefined`.
### child.connected ### subprocess.connected
<!-- YAML <!-- YAML
added: v0.7.2 added: v0.7.2
--> -->
* {boolean} Set to `false` after `child.disconnect()` is called * {boolean} Set to `false` after `subprocess.disconnect()` is called
The `child.connected` property indicates whether it is still possible to send The `subprocess.connected` property indicates whether it is still possible to
and receive messages from a child process. When `child.connected` is `false`, it send and receive messages from a child process. When `subprocess.connected` is
is no longer possible to send or receive messages. `false`, it is no longer possible to send or receive messages.
### child.disconnect() ### subprocess.disconnect()
<!-- YAML <!-- YAML
added: v0.7.2 added: v0.7.2
--> -->
Closes the IPC channel between parent and child, allowing the child to exit Closes the IPC channel between parent and child, allowing the child to exit
gracefully once there are no other connections keeping it alive. After calling gracefully once there are no other connections keeping it alive. After calling
this method the `child.connected` and `process.connected` properties in both this method the `subprocess.connected` and `process.connected` properties in
the parent and child (respectively) will be set to `false`, and it will be no both the parent and child (respectively) will be set to `false`, and it will be
longer possible to pass messages between the processes. no longer possible to pass messages between the processes.
The `'disconnect'` event will be emitted when there are no messages in the The `'disconnect'` event will be emitted when there are no messages in the
process of being received. This will most often be triggered immediately after process of being received. This will most often be triggered immediately after
calling `child.disconnect()`. calling `subprocess.disconnect()`.
Note that when the child process is a Node.js instance (e.g. spawned using Note that when the child process is a Node.js instance (e.g. spawned using
[`child_process.fork()`]), the `process.disconnect()` method can be invoked [`child_process.fork()`]), the `process.disconnect()` method can be invoked
within the child process to close the IPC channel as well. within the child process to close the IPC channel as well.
### child.kill([signal]) ### subprocess.kill([signal])
<!-- YAML <!-- YAML
added: v0.1.90 added: v0.1.90
--> -->
* `signal` {string} * `signal` {string}
The `child.kill()` methods sends a signal to the child process. If no argument The `subprocess.kill()` methods sends a signal to the child process. If no
is given, the process will be sent the `'SIGTERM'` signal. See signal(7) for argument is given, the process will be sent the `'SIGTERM'` signal. See
a list of available signals. signal(7) for a list of available signals.
```js ```js
const { spawn } = require('child_process'); const { spawn } = require('child_process');
@ -967,7 +970,7 @@ as in this example:
'use strict'; 'use strict';
const { spawn } = require('child_process'); const { spawn } = require('child_process');
const child = spawn( const subprocess = spawn(
'sh', 'sh',
[ [
'-c', '-c',
@ -980,11 +983,11 @@ const child = spawn(
); );
setTimeout(() => { setTimeout(() => {
child.kill(); // does not terminate the node process in the shell subprocess.kill(); // does not terminate the node process in the shell
}, 2000); }, 2000);
``` ```
### child.pid ### subprocess.pid
<!-- YAML <!-- YAML
added: v0.1.90 added: v0.1.90
--> -->
@ -1003,7 +1006,7 @@ console.log(`Spawned child pid: ${grep.pid}`);
grep.stdin.end(); grep.stdin.end();
``` ```
### child.send(message[, sendHandle[, options]][, callback]) ### subprocess.send(message[, sendHandle[, options]][, callback])
<!-- YAML <!-- YAML
added: v0.5.9 added: v0.5.9
changes: changes:
@ -1026,9 +1029,10 @@ changes:
* Returns: {boolean} * Returns: {boolean}
When an IPC channel has been established between the parent and child ( When an IPC channel has been established between the parent and child (
i.e. when using [`child_process.fork()`][]), the `child.send()` method can be i.e. when using [`child_process.fork()`][]), the `subprocess.send()` method can
used to send messages to the child process. When the child process is a Node.js be used to send messages to the child process. When the child process is a
instance, these messages can be received via the [`process.on('message')`][] event. Node.js instance, these messages can be received via the
[`process.on('message')`][] event.
For example, in the parent script: For example, in the parent script:
@ -1064,8 +1068,8 @@ for use within Node.js core and will not be emitted in the child's
Applications should avoid using such messages or listening for Applications should avoid using such messages or listening for
`'internalMessage'` events as it is subject to change without notice. `'internalMessage'` events as it is subject to change without notice.
The optional `sendHandle` argument that may be passed to `child.send()` is for The optional `sendHandle` argument that may be passed to `subprocess.send()` is
passing a TCP server or socket object to the child process. The child will for passing a TCP server or socket object to the child process. The child will
receive the object as the second argument passed to the callback function receive the object as the second argument passed to the callback function
registered on the [`process.on('message')`][] event. Any data that is received registered on the [`process.on('message')`][] event. Any data that is received
and buffered in the socket will not be sent to the child. and buffered in the socket will not be sent to the child.
@ -1086,7 +1090,7 @@ If no `callback` function is provided and the message cannot be sent, an
`'error'` event will be emitted by the [`ChildProcess`][] object. This can happen, `'error'` event will be emitted by the [`ChildProcess`][] object. This can happen,
for instance, when the child process has already exited. for instance, when the child process has already exited.
`child.send()` will return `false` if the channel has closed or when the `subprocess.send()` will return `false` if the channel has closed or when the
backlog of unsent messages exceeds a threshold that makes it unwise to send backlog of unsent messages exceeds a threshold that makes it unwise to send
more. Otherwise, the method returns `true`. The `callback` function can be more. Otherwise, the method returns `true`. The `callback` function can be
used to implement flow control. used to implement flow control.
@ -1097,7 +1101,7 @@ The `sendHandle` argument can be used, for instance, to pass the handle of
a TCP server object to the child process as illustrated in the example below: a TCP server object to the child process as illustrated in the example below:
```js ```js
const child = require('child_process').fork('child.js'); const subprocess = require('child_process').fork('subprocess.js');
// Open up the server object and send the handle. // Open up the server object and send the handle.
const server = require('net').createServer(); const server = require('net').createServer();
@ -1105,7 +1109,7 @@ server.on('connection', (socket) => {
socket.end('handled by parent'); socket.end('handled by parent');
}); });
server.listen(1337, () => { server.listen(1337, () => {
child.send('server', server); subprocess.send('server', server);
}); });
``` ```
@ -1137,8 +1141,8 @@ handle connections with "normal" or "special" priority:
```js ```js
const { fork } = require('child_process'); const { fork } = require('child_process');
const normal = fork('child.js', ['normal']); const normal = fork('subprocess.js', ['normal']);
const special = fork('child.js', ['special']); const special = fork('subprocess.js', ['special']);
// Open up the server and send sockets to child. Use pauseOnConnect to prevent // Open up the server and send sockets to child. Use pauseOnConnect to prevent
// the sockets from being read before they are sent to the child process. // the sockets from being read before they are sent to the child process.
@ -1156,8 +1160,8 @@ server.on('connection', (socket) => {
server.listen(1337); server.listen(1337);
``` ```
The `child.js` would receive the socket handle as the second argument passed The `subprocess.js` would receive the socket handle as the second argument
to the event callback function: passed to the event callback function:
```js ```js
process.on('message', (m, socket) => { process.on('message', (m, socket) => {
@ -1184,7 +1188,7 @@ time it takes to send the connection to the child.
*Note*: This function uses [`JSON.stringify()`][] internally to serialize the *Note*: This function uses [`JSON.stringify()`][] internally to serialize the
`message`. `message`.
### child.stderr ### subprocess.stderr
<!-- YAML <!-- YAML
added: v0.1.90 added: v0.1.90
--> -->
@ -1196,10 +1200,10 @@ A `Readable Stream` that represents the child process's `stderr`.
If the child was spawned with `stdio[2]` set to anything other than `'pipe'`, If the child was spawned with `stdio[2]` set to anything other than `'pipe'`,
then this will be `null`. then this will be `null`.
`child.stderr` is an alias for `child.stdio[2]`. Both properties will refer to `subprocess.stderr` is an alias for `subprocess.stdio[2]`. Both properties will
the same value. refer to the same value.
### child.stdin ### subprocess.stdin
<!-- YAML <!-- YAML
added: v0.1.90 added: v0.1.90
--> -->
@ -1214,10 +1218,10 @@ continue until this stream has been closed via `end()`.*
If the child was spawned with `stdio[0]` set to anything other than `'pipe'`, If the child was spawned with `stdio[0]` set to anything other than `'pipe'`,
then this will be `null`. then this will be `null`.
`child.stdin` is an alias for `child.stdio[0]`. Both properties will refer to `subprocess.stdin` is an alias for `subprocess.stdio[0]`. Both properties will
the same value. refer to the same value.
### child.stdio ### subprocess.stdio
<!-- YAML <!-- YAML
added: v0.7.10 added: v0.7.10
--> -->
@ -1226,20 +1230,20 @@ added: v0.7.10
A sparse array of pipes to the child process, corresponding with positions in A sparse array of pipes to the child process, corresponding with positions in
the [`stdio`][] option passed to [`child_process.spawn()`][] that have been set the [`stdio`][] option passed to [`child_process.spawn()`][] that have been set
to the value `'pipe'`. Note that `child.stdio[0]`, `child.stdio[1]`, and to the value `'pipe'`. Note that `subprocess.stdio[0]`, `subprocess.stdio[1]`,
`child.stdio[2]` are also available as `child.stdin`, `child.stdout`, and and `subprocess.stdio[2]` are also available as `subprocess.stdin`,
`child.stderr`, respectively. `subprocess.stdout`, and `subprocess.stderr`, respectively.
In the following example, only the child's fd `1` (stdout) is configured as a In the following example, only the child's fd `1` (stdout) is configured as a
pipe, so only the parent's `child.stdio[1]` is a stream, all other values in pipe, so only the parent's `subprocess.stdio[1]` is a stream, all other values
the array are `null`. in the array are `null`.
```js ```js
const assert = require('assert'); const assert = require('assert');
const fs = require('fs'); const fs = require('fs');
const child_process = require('child_process'); const child_process = require('child_process');
const child = child_process.spawn('ls', { const subprocess = child_process.spawn('ls', {
stdio: [ stdio: [
0, // Use parent's stdin for child 0, // Use parent's stdin for child
'pipe', // Pipe child's stdout to parent 'pipe', // Pipe child's stdout to parent
@ -1247,17 +1251,17 @@ const child = child_process.spawn('ls', {
] ]
}); });
assert.strictEqual(child.stdio[0], null); assert.strictEqual(subprocess.stdio[0], null);
assert.strictEqual(child.stdio[0], child.stdin); assert.strictEqual(subprocess.stdio[0], subprocess.stdin);
assert(child.stdout); assert(subprocess.stdout);
assert.strictEqual(child.stdio[1], child.stdout); assert.strictEqual(subprocess.stdio[1], subprocess.stdout);
assert.strictEqual(child.stdio[2], null); assert.strictEqual(subprocess.stdio[2], null);
assert.strictEqual(child.stdio[2], child.stderr); assert.strictEqual(subprocess.stdio[2], subprocess.stderr);
``` ```
### child.stdout ### subprocess.stdout
<!-- YAML <!-- YAML
added: v0.1.90 added: v0.1.90
--> -->
@ -1269,8 +1273,8 @@ A `Readable Stream` that represents the child process's `stdout`.
If the child was spawned with `stdio[1]` set to anything other than `'pipe'`, If the child was spawned with `stdio[1]` set to anything other than `'pipe'`,
then this will be `null`. then this will be `null`.
`child.stdout` is an alias for `child.stdio[1]`. Both properties will refer `subprocess.stdout` is an alias for `subprocess.stdio[1]`. Both properties will
to the same value. refer to the same value.
## `maxBuffer` and Unicode ## `maxBuffer` and Unicode
@ -1300,13 +1304,13 @@ unavailable.
[`Error`]: errors.html#errors_class_error [`Error`]: errors.html#errors_class_error
[`EventEmitter`]: events.html#events_class_eventemitter [`EventEmitter`]: events.html#events_class_eventemitter
[`JSON.stringify()`]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/stringify [`JSON.stringify()`]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/stringify
[`child.connected`]: #child_process_child_connected [`subprocess.connected`]: #child_process_subprocess_connected
[`child.disconnect()`]: #child_process_child_disconnect [`subprocess.disconnect()`]: #child_process_subprocess_disconnect
[`child.kill()`]: #child_process_child_kill_signal [`subprocess.kill()`]: #child_process_subprocess_kill_signal
[`child.send()`]: #child_process_child_send_message_sendhandle_options_callback [`subprocess.send()`]: #child_process_subprocess_send_message_sendhandle_options_callback
[`child.stderr`]: #child_process_child_stderr [`subprocess.stderr`]: #child_process_subprocess_stderr
[`child.stdin`]: #child_process_child_stdin [`subprocess.stdin`]: #child_process_subprocess_stdin
[`child.stdout`]: #child_process_child_stdout [`subprocess.stdout`]: #child_process_subprocess_stdout
[`child_process.exec()`]: #child_process_child_process_exec_command_options_callback [`child_process.exec()`]: #child_process_child_process_exec_command_options_callback
[`child_process.execFile()`]: #child_process_child_process_execfile_file_args_options_callback [`child_process.execFile()`]: #child_process_child_process_execfile_file_args_options_callback
[`child_process.execFileSync()`]: #child_process_child_process_execfilesync_file_args_options [`child_process.execFileSync()`]: #child_process_child_process_execfilesync_file_args_options

8
doc/api/errors.md
View File

@ -692,7 +692,7 @@ platform-dependent.
### ERR_INVALID_HANDLE_TYPE ### ERR_INVALID_HANDLE_TYPE
Used when an attempt is made to send an unsupported "handle" over an IPC Used when an attempt is made to send an unsupported "handle" over an IPC
communication channel to a child process. See [`child.send()`] and communication channel to a child process. See [`subprocess.send()`] and
[`process.send()`] for more information. [`process.send()`] for more information.
<a id="ERR_INVALID_HTTP_TOKEN"></a> <a id="ERR_INVALID_HTTP_TOKEN"></a>
@ -910,7 +910,7 @@ Used when an invalid or unknown encoding option is passed to an API.
### ERR_UNKNOWN_SIGNAL ### ERR_UNKNOWN_SIGNAL
Used when an invalid or unknown process signal is passed to an API expecting a Used when an invalid or unknown process signal is passed to an API expecting a
valid signal (such as [`child.kill()`][]). valid signal (such as [`subprocess.kill()`][]).
<a id="ERR_UNKNOWN_STDIN_TYPE"></a> <a id="ERR_UNKNOWN_STDIN_TYPE"></a>
### ERR_UNKNOWN_STDIN_TYPE ### ERR_UNKNOWN_STDIN_TYPE
@ -935,8 +935,8 @@ Used when the V8 BreakIterator API is used but the full ICU data set is not
installed. installed.
[`ERR_INVALID_ARG_TYPE`]: #ERR_INVALID_ARG_TYPE [`ERR_INVALID_ARG_TYPE`]: #ERR_INVALID_ARG_TYPE
[`child.kill()`]: child_process.html#child_process_child_kill_signal [`subprocess.kill()`]: child_process.html#child_process_subprocess_kill_signal
[`child.send()`]: child_process.html#child_process_child_send_message_sendhandle_options_callback [`subprocess.send()`]: child_process.html#child_process_subprocess_send_message_sendhandle_options_callback
[`fs.readFileSync`]: fs.html#fs_fs_readfilesync_path_options [`fs.readFileSync`]: fs.html#fs_fs_readfilesync_path_options
[`fs.readdir`]: fs.html#fs_fs_readdir_path_options_callback [`fs.readdir`]: fs.html#fs_fs_readdir_path_options_callback
[`fs.unlink`]: fs.html#fs_fs_unlink_path_callback [`fs.unlink`]: fs.html#fs_fs_unlink_path_callback