From 06491482f83af0adf74013345e2cd5fc09b4633a Mon Sep 17 00:00:00 2001 From: Ari Leo Frankel Date: Thu, 1 Mar 2018 13:56:03 -0600 Subject: [PATCH] doc: update child_process.md Add an explanation of the risk of exceeding platform pipe capacity with uncaptured output in child_process.spawn with stdio of pipe PR-URL: https://github.com/nodejs/node/pull/19075 Fixes: https://github.com/nodejs/node/issues/4236 Reviewed-By: Ruben Bridgewater Reviewed-By: Benjamin Gruenbaum Reviewed-By: Colin Ihrig Reviewed-By: Gireesh Punathil Reviewed-By: James M Snell --- doc/api/child_process.md | 14 ++++++++++---- 1 file changed, 10 insertions(+), 4 deletions(-) diff --git a/doc/api/child_process.md b/doc/api/child_process.md index 6f5b320f43ca35..cf0ba5a75bab93 100755 --- a/doc/api/child_process.md +++ b/doc/api/child_process.md @@ -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()`][]