child_process,cluster: promisify .send(), add exec{File,}Async

nodejs · chrisdickinson · Feb 1, 2016 · Feb 1, 2016 · Feb 1, 2016 · Feb 1, 2016
commit 697ce018bb1b73872b4f48872c7fec3b4fd71060
diff --git a/doc/api/child_process.markdown b/doc/api/child_process.markdown
@@ -182,6 +182,21 @@ terminated.
 *Note: Unlike the `exec()` POSIX system call, `child_process.exec()` does not
 replace the existing process and uses a shell to execute the command.*
 
+### child_process.exec(command[, options])
+
+A [`Promise`][def-promise]-returning variant of [`child_process.exec()`][].
+Resolves to a two-element array of [Strings][def-string], representing
+`stdout` output and `stderr` respectively.
+
+```js
+child_process.exec('cat *.js bad_file | wc -l').then((output) => {
+  console.log(`stdout: ${output[0]}`);
+  console.log(`stderr: ${output[1]}`);
+}).catch((err) => {
+  console.error(`something went wrong: ${err}`);
+});
+```
+
 ### child_process.execFile(file[, args][, options][, callback])
 
 * `file` {String} A path to an executable file
@@ -220,6 +235,20 @@ const child = execFile('node', ['--version'], (error, stdout, stderr) => {
 });
 ```
 
+### child_process.execFileAsync(file[, args][, options])
+
+A [`Promise`][def-promise]-returning variant of [`child_process.execFile()`][].
+Resolves to a two-element array of [Strings][def-string], representing
+`stdout` output and `stderr` respectively.
+
+```js
+const execFile = require('child_process').execFile;
+const child = execFile('node', ['--version']).then((output) => {
+  console.log(output[0]); // stdout
+  console.log(output[1]); // stderr
+});
+```
+
 ### child_process.fork(modulePath[, args][, options])
 
 * `modulePath` {String} The module to run in the child
@@ -755,7 +784,7 @@ grep.stdin.end();
 * `message` {Object}
 * `sendHandle` {Handle object}
 * `callback` {Function}
-* Return: Boolean
+* Return: Boolean | Promise
 
 When an IPC channel has been established between the parent and child (
 i.e. when using [`child_process.fork()`][]), the `child.send()` method can be
@@ -766,7 +795,7 @@ For example, in the parent script:
 
 ```js
 const cp = require('child_process');
-const n = cp.fork(`${__dirname}/sub.js`);
+const n = cp.fork(`${\_\_dirname}/sub.js`);
 
 n.on('message', (m) => {
   console.log('PARENT got message:', m);
@@ -801,18 +830,22 @@ passing a TCP server or socket object to the child process. The child will
 receive the object as the second argument passed to the callback function
 registered on the `process.on('message')` event.
 
-The optional `callback` is a function that is invoked after the message is
-sent but before the child may have received it.  The function is called with a
-single argument: `null` on success, or an [`Error`][] object on failure.
+The optional `callback` is a function that is invoked after the message is sent
+but before the child may have received it. The function is called with a single
+argument: `null` on success, or an [`Error`][] object on failure.
+
+If used with a callback, `child.send()` will return `false` if the channel has
+closed or when the backlog of unsent messages exceeds a threshold that makes it
+unwise to send more. Otherwise, the method returns `true`. The `callback`
+function can be used to implement flow control.
 
-If no `callback` function is provided and the message cannot be sent, an
-`'error'` event will be emitted by the `ChildProcess` object. This can happen,
-for instance, when the child process has already exited.
+When no `callback` is provided, a [`Promise`][def-promise] will be returned.
+This promise will resolve after the message has been sent but before the
+child has received it.
 
-`child.send()` will return `false` if the channel has closed or when the
-backlog of unsent messages exceeds a threshold that makes it unwise to send
-more. Otherwise, the method returns `true`. The `callback` function can be
-used to implement flow control.
+If no `callback` function is provided and the message cannot be sent, the
+returned [`Promise`][def-promise] will reject with an Error object. This can
+happen, for instance, when the child process has already exited.
 
 #### Example: sending a server object
 
@@ -986,4 +1019,6 @@ to the same value.
 [`options.detached`]: #child_process_options_detached
 [`options.stdio`]: #child_process_options_stdio
 [`stdio`]: #child_process_options_stdio
+[def-promise]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise
+[def-string]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String
 [synchronous counterparts]: #child_process_synchronous_process_creation
diff --git a/lib/child_process.js b/lib/child_process.js
@@ -2,6 +2,7 @@
 
 const util = require('util');
 const internalUtil = require('internal/util');
+const promisify = require('internal/promisify');
 const debug = util.debuglog('child_process');
 const constants = require('constants');
 
@@ -102,6 +103,9 @@ exports.exec = function(command /*, options, callback*/) {
 };
 
 
+exports.execAsync = promisify(exports.exec);
+
+
 exports.execFile = function(file /*, args, options, callback*/) {
   var args = [], callback;
   var options = {
@@ -288,6 +292,10 @@ exports.execFile = function(file /*, args, options, callback*/) {
   return child;
 };
 
+
+exports.execFileAsync = promisify(exports.execFile);
+
+
 var _deprecatedCustomFds = internalUtil.deprecate(function(options) {
   options.stdio = options.customFds.map(function(fd) {
     return fd === -1 ? 'pipe' : fd;

diff --git a/lib/cluster.js b/lib/cluster.js
@@ -1,5 +1,6 @@
 'use strict';
 
+const promisify = require('internal/promisify');
 const EventEmitter = require('events');
 const assert = require('assert');
 const dgram = require('dgram');
@@ -393,7 +394,7 @@ function masterInit() {
     cluster.emit('fork', worker);
   }
 
-  cluster.disconnect = function(cb) {
+  cluster.disconnect = promisify(function(cb) {
     var workers = Object.keys(cluster.workers);
     if (workers.length === 0) {
       process.nextTick(intercom.emit.bind(intercom, 'disconnect'));
@@ -405,7 +406,7 @@ function masterInit() {
       }
     }
     if (cb) intercom.once('disconnect', cb);
-  };
+  });
 
   Worker.prototype.disconnect = function() {
     this.suicide = true;

diff --git a/lib/internal/child_process.js b/lib/internal/child_process.js
@@ -1,5 +1,6 @@
 'use strict';
 
+const promisify = require('internal/promisify');
 const StringDecoder = require('string_decoder').StringDecoder;
 const Buffer = require('buffer').Buffer;
 const EventEmitter = require('events');
@@ -498,11 +499,15 @@ function setupChannel(target, channel) {
     });
   });
 
-  target.send = function(message, handle, callback) {
+  target.send = promisify(function(message, handle, callback) {
     if (typeof handle === 'function') {
       callback = handle;
       handle = undefined;
     }
+    if (typeof message === 'function') {
+      callback = message;
+      message = undefined;
+    }
     if (this.connected) {
       return this._send(message, handle, false, callback);
     }
@@ -513,7 +518,7 @@ function setupChannel(target, channel) {
       this.emit('error', ex);  // FIXME(bnoordhuis) Defer to next tick.
     }
     return false;
-  };
+  });
 
   target._send = function(message, handle, swallowErrors, callback) {
     assert(this.connected || this._channel);

diff --git a/test/parallel/test-child-process-send-returns-boolean.js b/test/parallel/test-child-process-send-returns-boolean.js
@@ -10,7 +10,7 @@ const emptyFile = path.join(common.fixturesDir, 'empty.js');
 
 const n = fork(emptyFile);
 
-const rv = n.send({ hello: 'world' });
+const rv = n.send({ hello: 'world' }, noop);
 assert.strictEqual(rv, true);
 
 const spawnOptions = { stdio: ['pipe', 'pipe', 'pipe', 'ipc'] };
@@ -22,8 +22,11 @@ s.on('exit', function() {
 
 net.createServer(common.fail).listen(common.PORT, function() {
   handle = this._handle;
-  assert.strictEqual(s.send('one', handle), true);
-  assert.strictEqual(s.send('two', handle), true);
-  assert.strictEqual(s.send('three'), false);
-  assert.strictEqual(s.send('four'), false);
+  assert.strictEqual(s.send('one', handle, noop), true);
+  assert.strictEqual(s.send('two', handle, noop), true);
+  assert.strictEqual(s.send('three', noop), false);
+  assert.strictEqual(s.send('four', noop), false);
 });
+
+function noop() {
+}