lib,doc: return boolean from child.send()

The documentation indicates that child.send() returns a boolean but it
has returned undefinined at since v0.12.0. It now returns a boolean per
the (slightly updated) documentation.

PR-URL: nodejs#3516
Reviewed-By: Ben Noordhuis <[email protected]>

Author: Trott

doc/api/child_process.markdown

@@ -266,9 +266,10 @@ argument: `null` on success, or an `Error` object on failure.
 `child.send()` emits an `'error'` event if no callback was given and the message
 cannot be sent, for example because the child process has already exited.
 
-Returns `true` under normal circumstances or `false` when the backlog of
+`child.send()` returns `false` if the channel has closed or when the backlog of
 unsent messages exceeds a threshold that makes it unwise to send more.
-Use the callback mechanism to implement flow control.
+Otherwise, it returns `true`. Use the callback mechanism to implement flow
+control.
 
 #### Example: sending server object
 

lib/internal/child_process.js

@@ -504,15 +504,15 @@ function setupChannel(target, channel) {
       handle = undefined;
     }
     if (this.connected) {
-      this._send(message, handle, false, callback);
-      return;
+      return this._send(message, handle, false, callback);
     }
     const ex = new Error('channel closed');
     if (typeof callback === 'function') {
       process.nextTick(callback, ex);
     } else {
       this.emit('error', ex);  // FIXME(bnoordhuis) Defer to next tick.
     }
+    return false;
   };
 
   target._send = function(message, handle, swallowErrors, callback) {
@@ -577,7 +577,7 @@ function setupChannel(target, channel) {
         handle: null,
         message: message,
       });
-      return;
+      return this._handleQueue.length === 1;
     }
 
     var req = new WriteWrap();

test/parallel/test-child-process-send-returns-boolean.js

@@ -0,0 +1,9 @@
+'use strict';
+const common = require('../common');
+const assert = require('assert');
+const fork = require('child_process').fork;
+
+const n = fork(common.fixturesDir + '/empty.js');
+
+const rv = n.send({ hello: 'world' });
+assert.strictEqual(rv, true);