tty: set blocking by default, api for unblocking

Builds on nodejs#6816,
adds API for explicitly setting non-blocking mode
without relying on `_`-prefixed internal property.

Adds documentation.

doc/api/tty.md

@@ -5,8 +5,8 @@
 The `tty` module houses the `tty.ReadStream` and `tty.WriteStream` classes. In
 most cases, you will not need to use this module directly.
 
-When Node.js detects that it is being run inside a TTY context, then `process.stdin`
-will be a `tty.ReadStream` instance and `process.stdout` will be
+When Node.js detects that it is being run inside a TTY context, then 
+`process.stdin` will be a `tty.ReadStream` instance and `process.stdout` will be
 a `tty.WriteStream` instance. The preferred way to check if Node.js is being run
 in a TTY context is to check `process.stdout.isTTY`:
 
@@ -25,8 +25,8 @@ Node.js program (only when `isatty(0)` is true).
 
 ### rs.isRaw
 
-A `Boolean` that is initialized to `false`. It represents the current "raw" state
-of the `tty.ReadStream` instance.
+A `Boolean` that is initialized to `false`. It represents the current "raw" 
+state of the `tty.ReadStream` instance.
 
 ### rs.setRawMode(mode)
 
@@ -40,6 +40,17 @@ A `net.Socket` subclass that represents the writable portion of a tty. In normal
 circumstances, `process.stdout` will be the only `tty.WriteStream` instance
 ever created (and only when `isatty(1)` is true).
 
+### Constructor: new fs.WriteStream(fd[, options])
+
+* `fd` {Number} The numeric file descriptor for this TTY instance.
+* `options` {Object}
+  * `blocking` {boolean} `true` if writes to the TTY should be blocking,
+    `false` otherwise. Defaults to `true`.
+
+Creates a new `tty.WriteStream`. By default, writes to the TTY will be blocking.
+Use `new fs.WriteStream(fd, {blocking: false})` to create the `fs.WriteStream`
+using non-blocking writes by default.
+
 ### Event: 'resize'
 
 `function () {}`
@@ -64,6 +75,17 @@ gets updated on `'resize'` events.
 A `Number` that gives the number of rows the TTY currently has. This property
 gets updated on `'resize'` events.
 
+### ws.setNonBlocking([bool])
+
+* `bool` {boolean} `true` to set the TTY to non-blocking writes, `false`
+  otherwise. Defaults to `true`.
+
+Returns a reference to the `tty.WriteStream` so calls can be chained.
+
+```js
+const myNonBlockingTTY = new tty.WriteStream(myFd).setNonBlocking();
+```
+
 ## tty.isatty(fd)
 
 Returns `true` or `false` depending on if the `fd` is associated with a

lib/tty.js

@@ -40,14 +40,23 @@ ReadStream.prototype.setRawMode = function(flag) {
 };
 
 
-function WriteStream(fd) {
+function WriteStream(fd, options) {
   if (!(this instanceof WriteStream)) return new WriteStream(fd);
   net.Socket.call(this, {
     handle: new TTY(fd, false),
     readable: false,
     writable: true
   });
 
+  options = options || {};
+  if (options.blocking === undefined) options.blocking = true;
+
+  // Prevents interleaved stdout/stderr output in terminals.
+  // As noted in the following reference, TTYs tend to be quite fast and this
+  // behaviour has become expected due to how it has functioned historically.
+  // Ref: /~https://github.com/nodejs/node/pull/1771#issuecomment-119351671
+  this._handle.setBlocking(options.blocking);
+
   var winSize = [];
   var err = this._handle.getWindowSize(winSize);
   if (!err) {
@@ -58,6 +67,13 @@ function WriteStream(fd) {
 inherits(WriteStream, net.Socket);
 exports.WriteStream = WriteStream;
 
+// Because the default is for the WriteStream to be blocking,
+// this method is intentionally named setNonBlocking instead
+// of bubbling up the underlying setBlocking name from the handle.
+WriteStream.prototype.setNonBlocking = function(val = true) {
+  this._handle.setBlocking(!val);
+  return this;
+};
 
 WriteStream.prototype.isTTY = true;