doc: change child to subprocess
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
parent
2dc09f656b
commit
dd75005a9e
@ -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
|
||||
[`ChildProcess`][] will have an additional communication channel built-in that
|
||||
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
|
||||
independent of the parent with exception of the IPC communication channel
|
||||
@ -472,10 +472,10 @@ Example of checking for failed `spawn`:
|
||||
|
||||
```js
|
||||
const { spawn } = require('child_process');
|
||||
const child = spawn('bad_command');
|
||||
const subprocess = spawn('bad_command');
|
||||
|
||||
child.on('error', (err) => {
|
||||
console.log('Failed to start child process.');
|
||||
subprocess.on('error', (err) => {
|
||||
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.
|
||||
|
||||
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.
|
||||
Doing so will cause the parent's event loop to not include the child in its
|
||||
reference count, allowing the parent to exit independently of the child, unless
|
||||
there is an established IPC channel between the child and parent.
|
||||
the parent from waiting for a given `subprocess`, use the `subprocess.unref()`
|
||||
method. Doing so will cause the parent's event loop to not include the child in
|
||||
its reference count, allowing the parent to exit independently of the child,
|
||||
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
|
||||
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
|
||||
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,
|
||||
stdio: 'ignore'
|
||||
});
|
||||
|
||||
child.unref();
|
||||
subprocess.unref();
|
||||
```
|
||||
|
||||
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 err = fs.openSync('./out.log', 'a');
|
||||
|
||||
const child = spawn('prg', [], {
|
||||
const subprocess = spawn('prg', [], {
|
||||
detached: true,
|
||||
stdio: [ 'ignore', out, err ]
|
||||
});
|
||||
|
||||
child.unref();
|
||||
subprocess.unref();
|
||||
```
|
||||
|
||||
#### options.stdio
|
||||
@ -555,9 +555,10 @@ changes:
|
||||
|
||||
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,
|
||||
and stderr are redirected to corresponding [`child.stdin`][], [`child.stdout`][], and
|
||||
[`child.stderr`][] streams on the [`ChildProcess`][] object. This is equivalent to
|
||||
setting the `options.stdio` equal to `['pipe', 'pipe', 'pipe']`.
|
||||
and stderr are redirected to corresponding [`subprocess.stdin`][],
|
||||
[`subprocess.stdout`][], and [`subprocess.stderr`][] streams on the
|
||||
[`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:
|
||||
|
||||
@ -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.
|
||||
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
|
||||
fds 0 - 2 are also available as [`child.stdin`][], [`child.stdout`][]
|
||||
and [`child.stderr`][], respectively.
|
||||
`child_process` object as [`subprocess.stdio[fd]`][`stdio`]. Pipes created
|
||||
for fds 0 - 2 are also available as [`subprocess.stdin`][],
|
||||
[`subprocess.stdout`][] and [`subprocess.stderr`][], respectively.
|
||||
2. `'ipc'` - Create an IPC channel for passing messages/file descriptors
|
||||
between parent and child. A [`ChildProcess`][] may have at most *one* IPC stdio
|
||||
file descriptor. Setting this option enables the [`child.send()`][] method.
|
||||
If the child writes JSON messages to this file descriptor, the
|
||||
[`child.on('message')`][`'message'`] event handler will be triggered in the parent.
|
||||
If the child is a Node.js process, the presence of an IPC channel will enable
|
||||
[`process.send()`][], [`process.disconnect()`][], [`process.on('disconnect')`][], and
|
||||
[`process.on('message')`] within the child.
|
||||
file descriptor. Setting this option enables the [`subprocess.send()`][]
|
||||
method. If the child writes JSON messages to this file descriptor, the
|
||||
[`subprocess.on('message')`][`'message'`] event handler will be triggered in
|
||||
the parent. If the child is a Node.js process, the presence of an IPC channel
|
||||
will enable [`process.send()`][], [`process.disconnect()`][],
|
||||
[`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
|
||||
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
|
||||
@ -828,9 +830,10 @@ added: v0.7.2
|
||||
-->
|
||||
|
||||
The `'disconnect'` event is emitted after calling the
|
||||
[`child.disconnect()`][] method in parent process or [`process.disconnect()`][] in child process. After
|
||||
disconnecting it is no longer possible to send or receive messages, and the
|
||||
[`child.connected`][] property is `false`.
|
||||
[`subprocess.disconnect()`][] method in parent process or
|
||||
[`process.disconnect()`][] in child process. After disconnecting it is no longer
|
||||
possible to send or receive messages, and the [`subprocess.connected`][]
|
||||
property is `false`.
|
||||
|
||||
### Event: 'error'
|
||||
|
||||
@ -846,7 +849,7 @@ The `'error'` event is emitted whenever:
|
||||
When listening to both the `'exit'` and `'error'` events, it is important
|
||||
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'
|
||||
<!-- YAML
|
||||
@ -883,56 +886,56 @@ added: v0.5.9
|
||||
The `'message'` event is triggered when a child process uses [`process.send()`][]
|
||||
to send messages.
|
||||
|
||||
### child.channel
|
||||
### subprocess.channel
|
||||
<!-- YAML
|
||||
added: v7.1.0
|
||||
-->
|
||||
|
||||
* {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
|
||||
IPC channel currently exists, this property is `undefined`.
|
||||
The `subprocess.channel` property is a reference to the child's IPC channel. If
|
||||
no IPC channel currently exists, this property is `undefined`.
|
||||
|
||||
### child.connected
|
||||
### subprocess.connected
|
||||
<!-- YAML
|
||||
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
|
||||
and receive messages from a child process. When `child.connected` is `false`, it
|
||||
is no longer possible to send or receive messages.
|
||||
The `subprocess.connected` property indicates whether it is still possible to
|
||||
send and receive messages from a child process. When `subprocess.connected` is
|
||||
`false`, it is no longer possible to send or receive messages.
|
||||
|
||||
### child.disconnect()
|
||||
### subprocess.disconnect()
|
||||
<!-- YAML
|
||||
added: v0.7.2
|
||||
-->
|
||||
|
||||
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
|
||||
this method the `child.connected` and `process.connected` properties in both
|
||||
the parent and child (respectively) will be set to `false`, and it will be no
|
||||
longer possible to pass messages between the processes.
|
||||
this method the `subprocess.connected` and `process.connected` properties in
|
||||
both the parent and child (respectively) will be set to `false`, and it will be
|
||||
no longer possible to pass messages between the processes.
|
||||
|
||||
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
|
||||
calling `child.disconnect()`.
|
||||
calling `subprocess.disconnect()`.
|
||||
|
||||
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
|
||||
within the child process to close the IPC channel as well.
|
||||
|
||||
### child.kill([signal])
|
||||
### subprocess.kill([signal])
|
||||
<!-- YAML
|
||||
added: v0.1.90
|
||||
-->
|
||||
|
||||
* `signal` {string}
|
||||
|
||||
The `child.kill()` methods sends a signal to the child process. If no argument
|
||||
is given, the process will be sent the `'SIGTERM'` signal. See signal(7) for
|
||||
a list of available signals.
|
||||
The `subprocess.kill()` methods sends a signal to the child process. If no
|
||||
argument is given, the process will be sent the `'SIGTERM'` signal. See
|
||||
signal(7) for a list of available signals.
|
||||
|
||||
```js
|
||||
const { spawn } = require('child_process');
|
||||
@ -967,7 +970,7 @@ as in this example:
|
||||
'use strict';
|
||||
const { spawn } = require('child_process');
|
||||
|
||||
const child = spawn(
|
||||
const subprocess = spawn(
|
||||
'sh',
|
||||
[
|
||||
'-c',
|
||||
@ -980,11 +983,11 @@ const child = spawn(
|
||||
);
|
||||
|
||||
setTimeout(() => {
|
||||
child.kill(); // does not terminate the node process in the shell
|
||||
subprocess.kill(); // does not terminate the node process in the shell
|
||||
}, 2000);
|
||||
```
|
||||
|
||||
### child.pid
|
||||
### subprocess.pid
|
||||
<!-- YAML
|
||||
added: v0.1.90
|
||||
-->
|
||||
@ -1003,7 +1006,7 @@ console.log(`Spawned child pid: ${grep.pid}`);
|
||||
grep.stdin.end();
|
||||
```
|
||||
|
||||
### child.send(message[, sendHandle[, options]][, callback])
|
||||
### subprocess.send(message[, sendHandle[, options]][, callback])
|
||||
<!-- YAML
|
||||
added: v0.5.9
|
||||
changes:
|
||||
@ -1026,9 +1029,10 @@ changes:
|
||||
* Returns: {boolean}
|
||||
|
||||
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
|
||||
used to send messages to the child process. When the child process is a Node.js
|
||||
instance, these messages can be received via the [`process.on('message')`][] event.
|
||||
i.e. when using [`child_process.fork()`][]), the `subprocess.send()` method can
|
||||
be used to send messages to the child process. When the child process is a
|
||||
Node.js instance, these messages can be received via the
|
||||
[`process.on('message')`][] event.
|
||||
|
||||
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
|
||||
`'internalMessage'` events as it is subject to change without notice.
|
||||
|
||||
The optional `sendHandle` argument that may be passed to `child.send()` is for
|
||||
passing a TCP server or socket object to the child process. The child will
|
||||
The optional `sendHandle` argument that may be passed to `subprocess.send()` is
|
||||
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
|
||||
registered on the [`process.on('message')`][] event. Any data that is received
|
||||
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,
|
||||
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
|
||||
more. Otherwise, the method returns `true`. The `callback` function can be
|
||||
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:
|
||||
|
||||
```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.
|
||||
const server = require('net').createServer();
|
||||
@ -1105,7 +1109,7 @@ server.on('connection', (socket) => {
|
||||
socket.end('handled by parent');
|
||||
});
|
||||
server.listen(1337, () => {
|
||||
child.send('server', server);
|
||||
subprocess.send('server', server);
|
||||
});
|
||||
```
|
||||
|
||||
@ -1137,8 +1141,8 @@ handle connections with "normal" or "special" priority:
|
||||
|
||||
```js
|
||||
const { fork } = require('child_process');
|
||||
const normal = fork('child.js', ['normal']);
|
||||
const special = fork('child.js', ['special']);
|
||||
const normal = fork('subprocess.js', ['normal']);
|
||||
const special = fork('subprocess.js', ['special']);
|
||||
|
||||
// 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.
|
||||
@ -1156,8 +1160,8 @@ server.on('connection', (socket) => {
|
||||
server.listen(1337);
|
||||
```
|
||||
|
||||
The `child.js` would receive the socket handle as the second argument passed
|
||||
to the event callback function:
|
||||
The `subprocess.js` would receive the socket handle as the second argument
|
||||
passed to the event callback function:
|
||||
|
||||
```js
|
||||
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
|
||||
`message`.
|
||||
|
||||
### child.stderr
|
||||
### subprocess.stderr
|
||||
<!-- YAML
|
||||
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'`,
|
||||
then this will be `null`.
|
||||
|
||||
`child.stderr` is an alias for `child.stdio[2]`. Both properties will refer to
|
||||
the same value.
|
||||
`subprocess.stderr` is an alias for `subprocess.stdio[2]`. Both properties will
|
||||
refer to the same value.
|
||||
|
||||
### child.stdin
|
||||
### subprocess.stdin
|
||||
<!-- YAML
|
||||
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'`,
|
||||
then this will be `null`.
|
||||
|
||||
`child.stdin` is an alias for `child.stdio[0]`. Both properties will refer to
|
||||
the same value.
|
||||
`subprocess.stdin` is an alias for `subprocess.stdio[0]`. Both properties will
|
||||
refer to the same value.
|
||||
|
||||
### child.stdio
|
||||
### subprocess.stdio
|
||||
<!-- YAML
|
||||
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
|
||||
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
|
||||
`child.stdio[2]` are also available as `child.stdin`, `child.stdout`, and
|
||||
`child.stderr`, respectively.
|
||||
to the value `'pipe'`. Note that `subprocess.stdio[0]`, `subprocess.stdio[1]`,
|
||||
and `subprocess.stdio[2]` are also available as `subprocess.stdin`,
|
||||
`subprocess.stdout`, and `subprocess.stderr`, respectively.
|
||||
|
||||
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
|
||||
the array are `null`.
|
||||
pipe, so only the parent's `subprocess.stdio[1]` is a stream, all other values
|
||||
in the array are `null`.
|
||||
|
||||
```js
|
||||
const assert = require('assert');
|
||||
const fs = require('fs');
|
||||
const child_process = require('child_process');
|
||||
|
||||
const child = child_process.spawn('ls', {
|
||||
const subprocess = child_process.spawn('ls', {
|
||||
stdio: [
|
||||
0, // Use parent's stdin for child
|
||||
'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(child.stdio[0], child.stdin);
|
||||
assert.strictEqual(subprocess.stdio[0], null);
|
||||
assert.strictEqual(subprocess.stdio[0], subprocess.stdin);
|
||||
|
||||
assert(child.stdout);
|
||||
assert.strictEqual(child.stdio[1], child.stdout);
|
||||
assert(subprocess.stdout);
|
||||
assert.strictEqual(subprocess.stdio[1], subprocess.stdout);
|
||||
|
||||
assert.strictEqual(child.stdio[2], null);
|
||||
assert.strictEqual(child.stdio[2], child.stderr);
|
||||
assert.strictEqual(subprocess.stdio[2], null);
|
||||
assert.strictEqual(subprocess.stdio[2], subprocess.stderr);
|
||||
```
|
||||
|
||||
### child.stdout
|
||||
### subprocess.stdout
|
||||
<!-- YAML
|
||||
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'`,
|
||||
then this will be `null`.
|
||||
|
||||
`child.stdout` is an alias for `child.stdio[1]`. Both properties will refer
|
||||
to the same value.
|
||||
`subprocess.stdout` is an alias for `subprocess.stdio[1]`. Both properties will
|
||||
refer to the same value.
|
||||
|
||||
## `maxBuffer` and Unicode
|
||||
|
||||
@ -1300,13 +1304,13 @@ unavailable.
|
||||
[`Error`]: errors.html#errors_class_error
|
||||
[`EventEmitter`]: events.html#events_class_eventemitter
|
||||
[`JSON.stringify()`]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/stringify
|
||||
[`child.connected`]: #child_process_child_connected
|
||||
[`child.disconnect()`]: #child_process_child_disconnect
|
||||
[`child.kill()`]: #child_process_child_kill_signal
|
||||
[`child.send()`]: #child_process_child_send_message_sendhandle_options_callback
|
||||
[`child.stderr`]: #child_process_child_stderr
|
||||
[`child.stdin`]: #child_process_child_stdin
|
||||
[`child.stdout`]: #child_process_child_stdout
|
||||
[`subprocess.connected`]: #child_process_subprocess_connected
|
||||
[`subprocess.disconnect()`]: #child_process_subprocess_disconnect
|
||||
[`subprocess.kill()`]: #child_process_subprocess_kill_signal
|
||||
[`subprocess.send()`]: #child_process_subprocess_send_message_sendhandle_options_callback
|
||||
[`subprocess.stderr`]: #child_process_subprocess_stderr
|
||||
[`subprocess.stdin`]: #child_process_subprocess_stdin
|
||||
[`subprocess.stdout`]: #child_process_subprocess_stdout
|
||||
[`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.execFileSync()`]: #child_process_child_process_execfilesync_file_args_options
|
||||
|
||||
@ -692,7 +692,7 @@ platform-dependent.
|
||||
### ERR_INVALID_HANDLE_TYPE
|
||||
|
||||
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.
|
||||
|
||||
<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
|
||||
|
||||
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>
|
||||
### 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.
|
||||
|
||||
[`ERR_INVALID_ARG_TYPE`]: #ERR_INVALID_ARG_TYPE
|
||||
[`child.kill()`]: child_process.html#child_process_child_kill_signal
|
||||
[`child.send()`]: child_process.html#child_process_child_send_message_sendhandle_options_callback
|
||||
[`subprocess.kill()`]: child_process.html#child_process_subprocess_kill_signal
|
||||
[`subprocess.send()`]: child_process.html#child_process_subprocess_send_message_sendhandle_options_callback
|
||||
[`fs.readFileSync`]: fs.html#fs_fs_readfilesync_path_options
|
||||
[`fs.readdir`]: fs.html#fs_fs_readdir_path_options_callback
|
||||
[`fs.unlink`]: fs.html#fs_fs_unlink_path_callback
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user