streams-like pattern to convey committment level

Callers can throttle requests to the pool to prevent unconstrained
queueing which can cause memory issues in extreme cases.

lib/generic-pool.js

@@ -248,13 +248,16 @@ exports.Pool = function (factory) {
    *   Optional.  Integer between 0 and (priorityRange - 1).  Specifies the priority
    *   of the caller if there are no available resources.  Lower numbers mean higher
    *   priority.
+   *
+   * @returns {Object} `true` if the pool is fully utilized, `false` otherwise.
    */
   me.acquire = function (callback, priority) {
     if (draining) {
       throw new Error("pool is draining and cannot accept work");
     }
     waitingClients.enqueue(callback, priority);
     dispense();
+    return (count < factory.max);
   };
 
   me.borrow = function (callback, priority) {

test/generic-pool.test.js

@@ -19,7 +19,7 @@ module.exports = {
         });
 
         for (var i = 0; i < 10; i++) {
-            pool.acquire(function(err, obj) {
+            var full = !pool.acquire(function(err, obj) {
                 return function(err, obj) {
                     assert.equal(typeof obj.count, 'number');
                     setTimeout(function() {
@@ -28,6 +28,7 @@ module.exports = {
                     }, 100);
                 };
             }());
+            assert.ok((i < 1) ^ full);
         }
 
         beforeExit(function() {