diff --git a/doc/api/console.md b/doc/api/console.md index bbb96cb3d3..ac0ce25a37 100644 --- a/doc/api/console.md +++ b/doc/api/console.md @@ -53,11 +53,15 @@ duplicate the browser's functionality exactly. ## Asynchronous vs Synchronous Consoles -The console functions are asynchronous unless the destination is a file. +The console functions are usually asynchronous unless the destination is a file. Disks are fast and operating systems normally employ write-back caching; it should be a very rare occurrence indeed that a write blocks, but it is possible. +Additionally, console functions are blocking when outputting to TTYs +(terminals) on OS X as a workaround for the OS's very small, 1kb buffer size. +This is to prevent interleaving between `stdout` and `stderr`. + ## Class: Console diff --git a/doc/api/process.md b/doc/api/process.md index cb53dc3f5b..b0e85746cf 100644 --- a/doc/api/process.md +++ b/doc/api/process.md @@ -833,7 +833,8 @@ if (someConditionNotMet()) { ``` The reason this is problematic is because writes to `process.stdout` in Node.js -are *non-blocking* and may occur over multiple ticks of the Node.js event loop. +are usually *non-blocking* and may occur over multiple ticks of the Node.js +event loop. Calling `process.exit()`, however, forces the process to exit *before* those additional writes to `stdout` can be performed. @@ -1367,6 +1368,10 @@ event and that writes can block when output is redirected to a file (although disks are fast and operating systems normally employ write-back caching so it should be a very rare occurrence indeed.) +Additionally, `process.stderr` and `process.stdout` are blocking when outputting +to TTYs (terminals) on OS X as a workaround for the OS's very small, 1kb +buffer size. This is to prevent interleaving between `stdout` and `stderr`. + ## process.stdin A `Readable Stream` for stdin (on fd `0`). @@ -1417,6 +1422,10 @@ event and that writes can block when output is redirected to a file (although disks are fast and operating systems normally employ write-back caching so it should be a very rare occurrence indeed.) +Additionally, `process.stderr` and `process.stdout` are blocking when outputting +to TTYs (terminals) on OS X as a workaround for the OS's very small, 1kb +buffer size. This is to prevent interleaving between `stdout` and `stderr`. + To check if Node.js is being run in a TTY context, read the `isTTY` property on `process.stderr`, `process.stdout`, or `process.stdin`: diff --git a/lib/tty.js b/lib/tty.js index 72efcd078b..fe0cc2e521 100644 --- a/lib/tty.js +++ b/lib/tty.js @@ -48,6 +48,13 @@ function WriteStream(fd) { writable: true }); + // Prevents interleaved stdout/stderr output in OS X terminals. + // As noted in the following reference, local TTYs tend to be quite fast and + // this behaviour has become expected due historical functionality on OS X, + // even though it was originally intended to change in v1.0.2 (Libuv 1.2.1). + // Ref: https://github.com/nodejs/node/pull/1771#issuecomment-119351671 + if (process.platform === 'darwin') this._handle.setBlocking(true); + var winSize = []; var err = this._handle.getWindowSize(winSize); if (!err) {