net,dgram: return this from ref and unref methods

Modifies the following methods to return the instance instead
of undefined, to allow for chaining these methods:

- net.Server.ref
- net.Server.unref
- net.Socket.ref
- net.Socket.unref
- dgram.Socket.ref
- dgram.Socket.unref

PR-URL: https://github.com/nodejs/io.js/pull/1768
Reviewed-By: Evan Lucas <evanlucas@me.com>

doc/api/dgram.markdown

@@ -306,8 +306,12 @@ Calling `unref` on a socket will allow the program to exit if this is the only
 active socket in the event system. If the socket is already `unref`d calling
 `unref` again will have no effect.
 
+Returns `socket`.
+
 ### socket.ref()
 
 Opposite of `unref`, calling `ref` on a previously `unref`d socket will *not*
 let the program exit if it's the only socket left (the default behavior). If
 the socket is `ref`d calling `ref` again will have no effect.
+
+Returns `socket`.

doc/api/net.markdown

@@ -261,12 +261,16 @@ Calling `unref` on a server will allow the program to exit if this is the only
 active server in the event system. If the server is already `unref`d calling
 `unref` again will have no effect.
 
+Returns `server`.
+
 ### server.ref()
 
 Opposite of `unref`, calling `ref` on a previously `unref`d server will *not*
 let the program exit if it's the only server left (the default behavior). If
 the server is `ref`d calling `ref` again will have no effect.
 
+Returns `server`.
+
 ### server.maxConnections
 
 Set this property to reject connections when the server's connection count gets
@@ -484,12 +488,16 @@ Calling `unref` on a socket will allow the program to exit if this is the only
 active socket in the event system. If the socket is already `unref`d calling
 `unref` again will have no effect.
 
+Returns `socket`.
+
 ### socket.ref()
 
 Opposite of `unref`, calling `ref` on a previously `unref`d socket will *not*
 let the program exit if it's the only socket left (the default behavior). If
 the socket is `ref`d calling `ref` again will have no effect.
 
+Returns `socket`.
+
 ### socket.remoteAddress
 
 The string representation of the remote IP address. For example,

lib/dgram.js

@@ -481,10 +481,14 @@ function onMessage(nread, handle, buf, rinfo) {
 Socket.prototype.ref = function() {
   if (this._handle)
     this._handle.ref();
+
+  return this;
 };
 
 
 Socket.prototype.unref = function() {
   if (this._handle)
     this._handle.unref();
+
+  return this;
 };

lib/net.js

@@ -984,20 +984,24 @@ function connectErrorNT(self, err, options) {
 Socket.prototype.ref = function() {
   if (!this._handle) {
     this.once('connect', this.ref);
-    return;
+    return this;
   }
 
   this._handle.ref();
+
+  return this;
 };
 
 
 Socket.prototype.unref = function() {
   if (!this._handle) {
     this.once('connect', this.unref);
-    return;
+    return this;
   }
 
   this._handle.unref();
+
+  return this;
 };
 
 
@@ -1506,6 +1510,8 @@ Server.prototype.ref = function() {
 
   if (this._handle)
     this._handle.ref();
+
+  return this;
 };
 
 Server.prototype.unref = function() {
@@ -1513,6 +1519,8 @@ Server.prototype.unref = function() {
 
   if (this._handle)
     this._handle.unref();
+
+  return this;
 };
 
 

test/parallel/test-ref-unref-return.js

@@ -0,0 +1,12 @@
+'use strict';
+var assert = require('assert');
+var net = require('net');
+var dgram = require('dgram');
+var common = require('../common');
+
+assert.ok((new net.Server()).ref() instanceof net.Server);
+assert.ok((new net.Server()).unref() instanceof net.Server);
+assert.ok((new net.Socket()).ref() instanceof net.Socket);
+assert.ok((new net.Socket()).unref() instanceof net.Socket);
+assert.ok((new dgram.Socket('udp4')).ref() instanceof dgram.Socket);
+assert.ok((new dgram.Socket('udp6')).unref() instanceof dgram.Socket);