Add enqueue event to pool

closes mysqljs#716

Author: dougwilson

Changes.md

@@ -7,6 +7,7 @@ you spot any mistakes.
 ## HEAD
 
 * Add code `POOL_ENQUEUELIMIT` to error reaching `queueLimit`
+* Add `enqueue` event to pool #716
 * Add `enqueue` event to protocol and connection #381
 * Blacklist unsupported connection flags #881
 * Make only column names enumerable in `RowDataPacket` #549 #895

Readme.md

@@ -348,6 +348,19 @@ addition to those options pools accept a few extras:
   before returning an error from `getConnection`. If set to `0`, there is no
   limit to the number of queued connection requests. (Default: `0`)
 
+## Pool events
+
+### enqueue
+
+The pool will emit an `enqueue` event when a callback has been queued to wait for
+an available connection.
+
+```js
+pool.on('enqueue', function () {
+  console.log('Waiting for available connection slot');
+});
+```
+
 ## PoolCluster
 
 PoolCluster provides multiple hosts connection. (group & retry & selector)

lib/Pool.js

@@ -201,6 +201,7 @@ Pool.prototype._enqueueCallback = function _enqueueCallback(callback) {
     : callback;
 
   this._connectionQueue.push(cb);
+  this.emit('enqueue');
 };
 
 Pool.prototype._purgeConnection = function _purgeConnection(connection) {

test/unit/pool/test-enqueue-event.js

@@ -0,0 +1,47 @@
+var assert = require('assert');
+var common = require('../../common');
+var pool   = common.createPool({
+  connectionLimit : 1,
+  port            : common.fakeServerPort
+});
+
+var index  = 0;
+var server = common.createFakeServer();
+
+server.listen(common.fakeServerPort, function (err) {
+  assert.ifError(err);
+
+  var count = 0;
+  pool.on('enqueue', function () {
+    count++;
+  });
+
+  pool.getConnection(function (err, connection) {
+    assert.ifError(err);
+    assert.ok(connection);
+    assert.equal(++index, 1);
+    assert.equal(count, 0);
+
+    pool.getConnection(function (err) {
+      assert.ifError(err);
+      assert.equal(++index, 2);
+      assert.equal(count, 2);
+
+      connection.release();
+    });
+
+    pool.getConnection(function (err) {
+      assert.ifError(err);
+      assert.equal(++index, 3);
+      assert.equal(count, 2);
+
+      connection.destroy();
+      server.destroy();
+    });
+
+    process.nextTick(function () {
+      assert.equal(count, 2);
+      connection.release();
+    });
+  });
+});