Skip to content

Commit

Permalink
doc: update child_process.md
Browse files Browse the repository at this point in the history
Add an explanation of the risk of exceeding platform pipe
capacity with uncaptured output in child_process.spawn
with stdio of pipe

PR-URL: #19075
Fixes: #4236
Reviewed-By: Ruben Bridgewater <ruben@bridgewater.de>
Reviewed-By: Benjamin Gruenbaum <benjamingr@gmail.com>
Reviewed-By: Colin Ihrig <cjihrig@gmail.com>
Reviewed-By: Gireesh Punathil <gpunathi@in.ibm.com>
Reviewed-By: James M Snell <jasnell@gmail.com>
  • Loading branch information
AriLFrankel authored and BethGriggs committed Dec 3, 2018
1 parent 18c4e5e commit 0649148
Showing 1 changed file with 10 additions and 4 deletions.
14 changes: 10 additions & 4 deletions doc/api/child_process.md
Original file line number Diff line number Diff line change
Expand Up @@ -26,10 +26,16 @@ ls.on('close', (code) => {
```

By default, pipes for `stdin`, `stdout`, and `stderr` are established between
the parent Node.js process and the spawned child. It is possible to stream data
through these pipes in a non-blocking way. *Note, however, that some programs
use line-buffered I/O internally. While that does not affect Node.js, it can
mean that data sent to the child process may not be immediately consumed.*
the parent Node.js process and the spawned child. These pipes have
limited (and platform-specific) capacity. If the child process writes to
stdout in excess of that limit without the output being captured, the child
process will block waiting for the pipe buffer to accept more data. This is
identical to the behavior of pipes in the shell. Use the `{ stdio: 'ignore' }`
option if the output will not be consumed.
It is possible to stream data through these pipes in a non-blocking way. Note,
however, that some programs use line-buffered I/O internally. While that does
not affect Node.js, it can mean that data sent to the child process may not be
immediately consumed.

The [`child_process.spawn()`][] method spawns the child process asynchronously,
without blocking the Node.js event loop. The [`child_process.spawnSync()`][]
Expand Down

0 comments on commit 0649148

Please sign in to comment.