Soft deprecation of 'listening' event.

Add callback param to listen() instead

doc/api.markdown

@@ -1665,25 +1665,24 @@ sent to the server on that socket.
 If a client connection emits an 'error' event - it will forwarded here.
 
 
-### server.listen(port, hostname)
+### server.listen(port, hostname=null, callback=null)
 
 Begin accepting connections on the specified port and hostname.  If the
 hostname is omitted, the server will accept connections directed to any
-address.
+IPv4 address (`INADDR_ANY`).
 
 To listen to a unix socket, supply a filename instead of port and hostname.
 
-**If you give a port number as a string, the system will interpret it as a filename in the current directory and create a unix socket.**
+This function is asynchronous. The last parameter `callback` will be called
+when the server has been bound to the port.
 
-This function is asynchronous. `listening` will be emitted when the server
-is ready to accept connections.
 
-
-### server.listen(path)
+### server.listen(path, callback=null)
 
 Start a UNIX socket server listening for connections on the given `path`.
-This function is asynchronous. `listening` will be emitted when the server
-is ready to accept connections.
+
+This function is asynchronous. The last parameter `callback` will be called
+when the server has been bound.
 
 
 ### server.setSecure(credentials)
@@ -2077,13 +2076,6 @@ changed to
 
 This is an EventEmitter with the following events:
 
-### Event: 'listening'
-
-`function () {}`
-
-After `listen()` is called, this event will notify that the server is ready
-to accept connections.
-
 ### Event: 'connection'
 
 `function (stream) {}`
@@ -2104,15 +2096,23 @@ Creates a new TCP server. The `connection_listener` argument is
 automatically set as a listener for the `'connection'` event.
 
 
-### server.listen(port, host=null)
+### server.listen(port, host=null, callback=null)
 
-Tells the server to listen for TCP connections to `port` and `host`.
+Begin accepting connections on the specified `port` and `host`.  If the
+`host` is omitted, the server will accept connections directed to any
+IPv4 address (`INADDR_ANY`).
+
+This function is asynchronous. The last parameter `callback` will be called
+when the server has been bound.
+
+
+### server.listen(path, callback=null)
+
+Start a UNIX socket server listening for connections on the given `path`.
 
-`host` is optional. If `host` is not specified the server will accept client
-connections on any network address.
+This function is asynchronous. The last parameter `callback` will be called
+when the server has been bound.
 
-This function is asynchronous. The server will emit `'listening'` when it is
-safe to connect to it.
 
 
 ### server.close()

lib/net.js

@@ -1112,6 +1112,11 @@ Server.prototype.listen = function () {
   var self = this;
   if (self.fd) throw new Error('Server already opened');
 
+  var lastArg = arguments[arguments.length - 1];
+  if (typeof lastArg == 'function') {
+    self.addListener('listening', lastArg);
+  }
+
   if (!isPort(arguments[0])) {
     // the first argument specifies a path
     self.fd = socket('unix');

test/pummel/test-keep-alive.js

@@ -12,7 +12,6 @@ server = http.createServer(function (req, res) {
   res.write(body);
   res.end();
 });
-server.listen(PORT);
 
 var keepAliveReqSec = 0;
 var normalReqSec = 0;
@@ -42,7 +41,7 @@ function runAb(opts, callback) {
   });
 }
 
-server.addListener('listening', function () {
+server.listen(PORT, function () {
   runAb("-k -c 100 -t 2", function (reqSec, keepAliveRequests) {
     keepAliveReqSec = reqSec;
     assert.equal(true, keepAliveRequests > 0);

test/pummel/test-tcp-many-clients.js

@@ -21,7 +21,6 @@ var server = net.createServer(function (c) {
     c.end();
   });
 });
-server.listen(PORT);
 
 function runClient (callback) {
   var client = net.createConnection(PORT);
@@ -67,7 +66,7 @@ function runClient (callback) {
   });
 }
 
-server.addListener('listening', function () {
+server.listen(PORT, function () {
   var finished_clients = 0;
   for (var i = 0; i < concurrency; i++) {
     runClient(function () {

test/pummel/test-tcp-timeout.js

@@ -29,8 +29,9 @@ var echo_server = net.createServer(function (socket) {
   });
 });
 
-echo_server.listen(PORT);
-puts("server listening at " + PORT);
+echo_server.listen(PORT, function () {
+  puts("server listening at " + PORT);
+});
 
 var client = net.createConnection(PORT);
 client.setEncoding("UTF8");

test/simple/test-http-304.js

@@ -8,17 +8,14 @@ s = http.createServer(function (request, response) {
   response.writeHead(304);
   response.end();
 });
-s.listen(PORT);
-sys.puts('Server running at http://127.0.0.1:'+PORT+'/')
-
-s.addListener('listening', function () {
 
+s.listen(PORT, function () {
   childProcess.exec('curl -i http://127.0.0.1:'+PORT+'/', function (err, stdout, stderr) {
     if (err) throw err;
     s.close();
     error('curled response correctly');
     error(sys.inspect(stdout));
   });
-
 });
 
+sys.puts('Server running at http://127.0.0.1:'+PORT+'/')

test/simple/test-http-cat.js

@@ -10,12 +10,11 @@ var server = http.createServer(function (req, res) {
   ]);
   res.end(body);
 });
-server.listen(PORT);
 
 var got_good_server_content = false;
 var bad_server_got_error = false;
 
-server.addListener('listening', function () {
+server.listen(PORT, function () {
   http.cat("http://localhost:"+PORT+"/", "utf8", function (err, content) {
     if (err) {
       throw err;

test/simple/test-http-full-response.js

@@ -15,7 +15,6 @@ server = http.createServer(function (req, res) {
   });
   res.end(body);
 });
-server.listen(PORT);
 
 runs = 0;
 
@@ -46,7 +45,7 @@ function runAb(opts, callback) {
   });
 }
 
-server.addListener('listening', function () {
+server.listen(PORT, function () {
   runAb("-c 1 -n 10", function () {
     puts("-c 1 -n 10 okay");
 

test/simple/test-http-head-request.js

@@ -13,11 +13,10 @@ server = http.createServer(function (req, res) {
   res.end();
   server.close();
 });
-server.listen(PORT);
 
 var gotEnd = false;
 
-server.addListener('listening', function () {
+server.listen(PORT, function () {
   var client = http.createClient(PORT);
   var request = client.request("HEAD", "/");
   request.addListener('response', function (response) {

test/simple/test-http-proxy.js

@@ -11,8 +11,6 @@ var backend = http.createServer(function (req, res) {
   res.write("hello world\n");
   res.end();
 });
-debug("listen backend")
-backend.listen(BACKEND_PORT);
 
 var proxy_client = http.createClient(BACKEND_PORT);
 var proxy = http.createServer(function (req, res) {
@@ -30,8 +28,6 @@ var proxy = http.createServer(function (req, res) {
   });
   proxy_req.end();
 });
-debug("listen proxy")
-proxy.listen(PROXY_PORT);
 
 var body = "";
 
@@ -57,8 +53,11 @@ function startReq () {
   req.end();
 }
 
-proxy.addListener('listening', startReq);
-backend.addListener('listening', startReq);
+debug("listen proxy")
+proxy.listen(PROXY_PORT, startReq);
+
+debug("listen backend")
+backend.listen(BACKEND_PORT, startReq);
 
 process.addListener("exit", function () {
   assert.equal(body, "hello world\n");

test/simple/test-http-set-timeout.js

@@ -11,10 +11,8 @@ server = http.createServer(function (req, res) {
     server.close();
   });
 });
-server.listen(PORT);
 
-
-server.addListener('listening', function () {
+server.listen(PORT, function () {
   sys.puts('Server running at http://127.0.0.1:'+PORT+'/');
 
   errorTimer =setTimeout(function () {

test/simple/test-http-upgrade.js

@@ -143,13 +143,12 @@ function test_standard_http(){
 
 
 var server = createTestServer();
-server.addListener("listening", function(){
+
+server.listen(PORT, function(){
   // All tests get chained after this:
   test_upgrade_with_listener(server);
 });
 
-server.listen(PORT);
-
 
 /*-----------------------------------------------
   Fin.

test/simple/test-http-upgrade2.js

@@ -25,10 +25,7 @@ process.addListener('uncaughtException', function (e) {
 });
 
 
-server.listen(PORT);
-
-
-server.addListener('listening', function () {
+server.listen(PORT, function () {
   var c = net.createConnection(PORT);
 
   c.addListener('connect', function () {

test/simple/test-http-write-empty-string.js

@@ -16,7 +16,6 @@ server = http.createServer(function (request, response) {
 
   this.close();
 })
-server.listen(PORT);
 
 var response="";
 
@@ -25,7 +24,7 @@ process.addListener('exit', function () {
 });
 
 
-server.addListener('listening', function () {
+server.listen(PORT, function () {
   var client = http.createClient(PORT);
   var req = client.request("/");
   req.end();

test/simple/test-net-pingpong.js

@@ -45,7 +45,8 @@ function pingPongTest (port, host) {
     });
   });
 
-  server.addListener("listening", function () {
+
+  server.listen(port, host, function () {
     puts("server listening on " + port + " " + host);
 
     var client = net.createConnection(port, host);
@@ -92,8 +93,6 @@ function pingPongTest (port, host) {
       throw e;
     });
   });
-
-  server.listen(port, host);
 }
 
 /* All are run at once, so run on different ports */

test/simple/test-repl.js

@@ -42,7 +42,7 @@ function tcp_test() {
     repl.start(prompt_tcp, socket);
   });
 
-  server_tcp.addListener('listening', function () {
+  server_tcp.listen(PORT, function () {
     var read_buffer = "";
 
     client_tcp = net.createConnection(PORT);
@@ -88,7 +88,6 @@ function tcp_test() {
     });
   });
 
-  server_tcp.listen(PORT);
 }
 
 function unix_test() {

test/simple/test-tcp-reconnect.js

@@ -21,9 +21,7 @@ var server = net.createServer(function (socket) {
   });
 });
 
-server.listen(PORT);
-
-server.addListener('listening', function () {
+server.listen(PORT, function () {
   puts('listening');
   var client = net.createConnection(PORT);