child_process: add callback parameter to .send()

Add an optional callback parameter to `ChildProcess.prototype.send()`
that is invoked when the message has been sent.
Juggle the control channel's reference count so that in-flight messages
keep the event loop (and therefore the process) alive until they have
been sent.
`ChildProcess.prototype.send()` and `process.send()` used to operate
synchronously but became asynchronous in commit libuv/libuv@393c1c5
("unix: set non-block mode in uv_{pipe,tcp,udp}_open"), which landed
in io.js in commit 07bd05b ("deps: update libuv to 1.2.1").
Fixes: #760
PR-URL: #2620
Reviewed-By: trevnorris - Trevor Norris <trev.norris@gmail.com>
Reviewed-By: jasnell - James M Snell <jasnell@gmail.com>

Author: bnoordhuis

doc/api/child_process.markdown

@@ -214,13 +214,15 @@ to a process.
 
 See `kill(2)`
 
-### child.send(message[, sendHandle])
+### child.send(message[, sendHandle][, callback])
 
 *`message` {Object}
 *`sendHandle` {Handle object}
+*`callback` {Function}
+* Return: Boolean
 
 When using `child_process.fork()` you can write to the child using
-`child.send(message, [sendHandle])` and messages are received by
+`child.send(message[, sendHandle][, callback])` and messages are received by
 a `'message'` event on the child.
 
 For example:
@@ -246,11 +248,6 @@ And then the child script, `'sub.js'` might look like this:
 In the child the `process` object will have a `send()` method, and `process`
 will emit objects each time it receives a message on its channel.
 
-Please note that the `send()` method on both the parent and child are
-synchronous - sending large chunks of data is not advised (pipes can be used
-instead, see
-[`child_process.spawn`](#child_process_child_process_spawn_command_args_options)).
-
 There is a special case when sending a `{cmd: 'NODE_foo'}` message. All messages
 containing a `NODE_` prefix in its `cmd` property will not be emitted in
 the `message` event, since they are internal messages used by Node.js core.
@@ -261,8 +258,16 @@ The `sendHandle` option to `child.send()` is for sending a TCP server or
 socket object to another process. The child will receive the object as its
 second argument to the `message` event.
 
-Emits an `'error'` event if the message cannot be sent, for example because
-the child process has already exited.
+The `callback` option is a function that is invoked after the message is
+sent but before the target may have received it. It is called with a single
+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
+unsent messages exceeds a threshold that makes it unwise to send more.
+Use the callback mechanism to implement flow control.
 
 #### Example: sending server object
 

doc/api/cluster.markdown

@@ -426,10 +426,12 @@ exit, the master may choose not to respawn a worker based on this value.
 // kill worker
 worker.kill();
 
-### worker.send(message[, sendHandle])
+### worker.send(message[, sendHandle][, callback])
 
 *`message` {Object}
 *`sendHandle` {Handle object}
+*`callback` {Function}
+* Return: Boolean
 
 Send a message to a worker or master, optionally with a handle.
 

lib/child_process.js

@@ -48,16 +48,12 @@ exports._forkChild = function(fd) {
 varp=newPipe(true);
 p.open(fd);
 p.unref();
-setupChannel(process,p);
-
-varrefs=0;
+constcontrol=setupChannel(process,p);
 process.on('newListener',function(name){
-if(name!=='message'&&name!=='disconnect')return;
-if(++refs===1)p.ref();
+if(name==='message'||name==='disconnect')control.ref();
 });
 process.on('removeListener',function(name){
-if(name!=='message'&&name!=='disconnect')return;
-if(--refs===0)p.unref();
+if(name==='message'||name==='disconnect')control.unref();
 });
 };
 

lib/internal/child_process.js

@@ -397,6 +397,25 @@ function setupChannel(target, channel) {
 target._channel=channel;
 target._handleQueue=null;
 
+constcontrol=newclassextendsEventEmitter{
+constructor(){
+super();
+this.channel=channel;
+this.refs=0;
+}
+ref(){
+if(++this.refs===1){
+this.channel.ref();
+}
+}
+unref(){
+if(--this.refs===0){
+this.channel.unref();
+this.emit('unref');
+}
+}
+};
+
 vardecoder=newStringDecoder('utf8');
 varjsonBuffer='';
 channel.buffering=false;
@@ -446,7 +465,7 @@ function setupChannel(target, channel) {
 target._handleQueue=null;
 
 queue.forEach(function(args){
-target._send(args.message,args.handle,false);
+target._send(args.message,args.handle,false,args.callback);
 });
 
 // Process a pending disconnect (if any).
@@ -478,14 +497,24 @@ function setupChannel(target, channel) {
 });
 });
 
-target.send=function(message,handle){
-if(!this.connected)
-this.emit('error',newError('channel closed'));
-else
-this._send(message,handle,false);
+target.send=function(message,handle,callback){
+if(typeofhandle==='function'){
+callback=handle;
+handle=undefined;
+}
+if(this.connected){
+this._send(message,handle,false,callback);
+return;
+}
+constex=newError('channel closed');
+if(typeofcallback==='function'){
+process.nextTick(callback,ex);
+}else{
+this.emit('error',ex);// FIXME(bnoordhuis) Defer to next tick.
+}
 };
 
-target._send=function(message,handle,swallowErrors){
+target._send=function(message,handle,swallowErrors,callback){
 assert(this.connected||this._channel);
 
 if(message===undefined)
@@ -516,7 +545,11 @@ function setupChannel(target, channel) {
 
 // Queue-up message and handle if we haven't received ACK yet.
 if(this._handleQueue){
-this._handleQueue.push({message: message.msg,handle: handle});
+this._handleQueue.push({
+callback: callback,
+handle: handle,
+message: message.msg,
+});
 return;
 }
 
@@ -538,24 +571,43 @@ function setupChannel(target, channel) {
 }elseif(this._handleQueue&&
 !(message&&message.cmd==='NODE_HANDLE_ACK')){
 // Queue request anyway to avoid out-of-order messages.
-this._handleQueue.push({message: message,handle: null});
+this._handleQueue.push({
+callback: callback,
+handle: null,
+message: message,
+});
 return;
 }
 
 varreq=newWriteWrap();
-req.oncomplete=nop;
+req.async=false;
+
 varstring=JSON.stringify(message)+'\n';
 varerr=channel.writeUtf8String(req,string,handle);
 
-if(err){
-if(!swallowErrors)
-this.emit('error',errnoException(err,'write'));
-}elseif(handle&&!this._handleQueue){
-this._handleQueue=[];
-}
-
-if(obj&&obj.postSend){
-req.oncomplete=obj.postSend.bind(null,handle);
+if(err===0){
+if(handle&&!this._handleQueue)
+this._handleQueue=[];
+req.oncomplete=function(){
+if(this.async===true)
+control.unref();
+if(obj&&obj.postSend)
+obj.postSend(handle);
+if(typeofcallback==='function')
+callback(null);
+};
+if(req.async===true){
+control.ref();
+}else{
+process.nextTick(function(){req.oncomplete();});
+}
+}elseif(!swallowErrors){
+constex=errnoException(err,'write');
+if(typeofcallback==='function'){
+process.nextTick(callback,ex);
+}else{
+this.emit('error',ex);// FIXME(bnoordhuis) Defer to next tick.
+}
 }
 
 /* If the master is > 2 read() calls behind, please stop sending. */
@@ -616,6 +668,7 @@ function setupChannel(target, channel) {
 };
 
 channel.readStart();
+returncontrol;
 }
 
 

test/parallel/test-child-process-send-cb.js

@@ -0,0 +1,19 @@
+'use strict';
+constcommon=require('../common');
+constassert=require('assert');
+constfork=require('child_process').fork;
+
+if(process.argv[2]==='child'){
+process.send('ok',common.mustCall(function(err){
+assert.strictEqual(err,null);
+}));
+}else{
+constchild=fork(process.argv[1],['child']);
+child.on('message',common.mustCall(function(message){
+assert.strictEqual(message,'ok');
+}));
+child.on('exit',common.mustCall(function(exitCode,signalCode){
+assert.strictEqual(exitCode,0);
+assert.strictEqual(signalCode,null);
+}));
+}