Skip to content

Commit

Permalink
doc: remove IPC channel implementation details
Browse files Browse the repository at this point in the history
IPC messages are more complicated than a simple pipe passing JSON
objects separated by new line. This removes inaccurate notes about
implementation from the documentation.

PR-URL: #17460
Fixes: #16491
Fixes: #17405
Reviewed-By: Jon Moss <me@jonathanmoss.me>
Reviewed-By: Rich Trott <rtrott@gmail.com>
Reviewed-By: Refael Ackermann <refack@gmail.com>
Reviewed-By: Luigi Pinca <luigipinca@gmail.com>
Reviewed-By: James M Snell <jasnell@gmail.com>
  • Loading branch information
bzoz authored and gibfahn committed Dec 20, 2017
1 parent 79f7564 commit 4980517
Show file tree
Hide file tree
Showing 2 changed files with 10 additions and 19 deletions.
18 changes: 6 additions & 12 deletions doc/api/child_process.md
Original file line number Diff line number Diff line change
Expand Up @@ -366,8 +366,7 @@ By default, `child_process.fork()` will spawn new Node.js instances using the

Node.js processes launched with a custom `execPath` will communicate with the
parent process using the file descriptor (fd) identified using the
environment variable `NODE_CHANNEL_FD` on the child process. The input and
output on this fd is expected to be line delimited JSON objects.
environment variable `NODE_CHANNEL_FD` on the child process.

*Note*: Unlike the fork(2) POSIX system call, `child_process.fork()` does
not clone the current process.
Expand Down Expand Up @@ -609,9 +608,7 @@ pipes between the parent and child. The value is one of the following:
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 [`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
method. 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.
Expand Down Expand Up @@ -933,9 +930,8 @@ added: v0.5.9
The `'message'` event is triggered when a child process uses [`process.send()`][]
to send messages.

*Note*: The message goes through JSON serialization and parsing. The resulting
message might not be the same as what is originally sent. See notes in
[the `JSON.stringify()` specification][`JSON.stringify` spec].
*Note*: The message goes through serialization and parsing. The resulting
message might not be the same as what is originally sent.

<a name="child_process_child_channel"></a>
### subprocess.channel
Expand Down Expand Up @@ -1103,9 +1099,8 @@ 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.

*Note*: The message goes through JSON serialization and parsing. The resulting
message might not be the same as what is originally sent. See notes in
[the `JSON.stringify()` specification][`JSON.stringify` spec].
*Note*: The message goes through serialization and parsing. The resulting
message might not be the same as what is originally sent.

For example, in the parent script:

Expand Down Expand Up @@ -1382,7 +1377,6 @@ unavailable.
[`ChildProcess`]: #child_process_child_process
[`Error`]: errors.html#errors_class_error
[`EventEmitter`]: events.html#events_class_eventemitter
[`JSON.stringify` spec]: https://tc39.github.io/ecma262/#sec-json.stringify
[`subprocess.connected`]: #child_process_subprocess_connected
[`subprocess.disconnect()`]: #child_process_subprocess_disconnect
[`subprocess.kill()`]: #child_process_subprocess_kill_signal
Expand Down
11 changes: 4 additions & 7 deletions doc/api/process.md
Original file line number Diff line number Diff line change
Expand Up @@ -94,9 +94,8 @@ The listener callback is invoked with the following arguments:
* `sendHandle` {Handle object} a [`net.Socket`][] or [`net.Server`][] object, or
undefined.

*Note*: The message goes through JSON serialization and parsing. The resulting
message might not be the same as what is originally sent. See notes in
[the `JSON.stringify()` specification][`JSON.stringify` spec].
*Note*: The message goes through serialization and parsing. The resulting
message might not be the same as what is originally sent.

### Event: 'rejectionHandled'
<!-- YAML
Expand Down Expand Up @@ -1443,9 +1442,8 @@ used to send messages to the parent process. Messages will be received as a
If Node.js was not spawned with an IPC channel, `process.send()` will be
`undefined`.

*Note*: The message goes through JSON serialization and parsing. The resulting
message might not be the same as what is originally sent. See notes in
[the `JSON.stringify()` specification][`JSON.stringify` spec].
*Note*: The message goes through serialization and parsing. The resulting
message might not be the same as what is originally sent.

## process.setegid(id)
<!-- YAML
Expand Down Expand Up @@ -1847,7 +1845,6 @@ cases:
[`ChildProcess`]: child_process.html#child_process_class_childprocess
[`Error`]: errors.html#errors_class_error
[`EventEmitter`]: events.html#events_class_eventemitter
[`JSON.stringify` spec]: https://tc39.github.io/ecma262/#sec-json.stringify
[`console.error()`]: console.html#console_console_error_data_args
[`console.log()`]: console.html#console_console_log_data_args
[`end()`]: stream.html#stream_writable_end_chunk_encoding_callback
Expand Down

0 comments on commit 4980517

Please sign in to comment.