child_process: do not keep list of sent sockets

Keeping list of all sockets that were sent to child process causes memory
leak and thus unacceptable (see #4587). However `server.close()` should
still work properly.

This commit introduces two options:

* child.send(socket, { track: true }) - will send socket and track its status.
  You should use it when you want to receive `close` event on sent sockets.
* child.send(socket) - will send socket without tracking it status. This
  performs much better, because of smaller number of RTT between master and
  child.

With both of these options `server.close()` will wait for all sent
sockets to get closed.

2 files changed, 18 insertions, 2 deletions

diff --git a/doc/api/child_process.markdown b/doc/api/child_process.markdown
index d803cffe9b..343030d53f 100644
--- a/doc/api/child_process.markdown
+++ b/doc/api/child_process.markdown
@@ -124,10 +124,11 @@ process may not actually kill it.  `kill` really just sends a signal to a proces
 
 See `kill(2)`
 
-### child.send(message, [sendHandle])
+### child.send(message, [sendHandle], [options])
 
 * `message` {Object}
 * `sendHandle` {Handle object}
+* `options` {Object}
 
 When using `child_process.fork()` you can write to the child using
 `child.send(message, [sendHandle])` and messages are received by
@@ -166,6 +167,11 @@ 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.
 
+The `options` object may have the following properties:
+
+ * `track` - Notify master process when `sendHandle` will be closed in child
+   process. (`false` by default)
+
 **send server object**
 
 Here is an example of sending a server:
diff --git a/doc/api/net.markdown b/doc/api/net.markdown
index 2b54dbeb0f..fcd673fa6c 100644
--- a/doc/api/net.markdown
+++ b/doc/api/net.markdown
@@ -229,12 +229,22 @@ with `child_process.fork()`.
 
 ### server.connections
 
+This function is **deprecated**; please use [server.getConnections()][] instead.
 The number of concurrent connections on the server.
 
-This becomes `null` when sending a socket to a child with `child_process.fork()`.
+This becomes `null` when sending a socket to a child with
+`child_process.fork()`. To poll forks and get current number of active
+connections use asynchronous `server.getConnections` instead.
 
 `net.Server` is an [EventEmitter][] with the following events:
 
+### server.getConnections(callback)
+
+Asynchronously get the number of concurrent connections on the server. Works
+when sockets were sent to forks.
+
+Callback should take two arguments `err` and `count`.
+
 ### Event: 'listening'
 
 Emitted when the server has been bound after calling `server.listen`.