advanced-pool

Advanced resource pool for Node.JS

npm install advanced-pool
3 downloads in the last week
8 downloads in the last month

advanced-pool

About

advanced-pool provides a simple and generic ways to manage resource pools in NodeJS applications.

Unlike the other pool libraries I found, advanced-pool allows easy extension of both, the pool object as well as the container managing the request queue.

Installation

npm install advanced-pool

Current state

The current version is not proved to be working in any other way than the example in the tests/ directory.

This package was created to be used in one of my projects, so I'll be fixing bugs and add improvements with time.

API

Exports

var apool = require('advanced-pool');

advanced-pool comes with 2 constructors:

apool.Pool(options)
apool.SimpleQueue()

Pool(options)

Pool constructor.

Pool accepts a number of options in the options argument:

  • name - name of the pool (default pool)
  • create - the object creator function, accepts a single argument, which is a callback function The callback function takes two aguments, error and object. If error is set, it is assumed something when wrong, and object won't be added to the pool.
  • destroy - this function is called to destroy objects in the pool. It takes only one argument, the object (optional)
  • min - minimum number of objects in the pool (default 2)
  • max - maximum number of objects in the pool (default 4)
  • idleTimeout - time in milliseconds for an idle object above min to timeout (default 30000)
  • idleCheckInterval - interval in milliseconds for checking for timedout objects (default 1000)
  • log - logging accepts the following values:
    • true - console.log will be used for logging
    • function - a function with 2 arguments, message and severity
    • false and any other value - no logging

More information can be found in the source code.

Pool.acquire(client, queueOptions)

Acquire an object from the pool.

Arguments:

  • client is a function with two arguments, error and object. If error argument is null, the object argument will hold an object from the pool.
  • queueOptions should hold additional arguments for the queue, however SimpleQueue doesn't require any arguments.

An object received in client callback should either be released with the release() method or marked as bad object with removeBadObject() method.

Example:

pool.acquire(function (err, obj) {
    if (err) {
        console.log('Could not acquire object! ' + err);
    } else {
        // ...do something with the object
        pool.release(obj);
    }
});

Pool.release(object)

Release an object previously acquired with acquire() method.

Arguments:

  • object the object to release

Pool.removeBadObject(object)

Mark an object as bad and remove it from the pool.

This will only work for an object that is currently busy (acquired with the acquire() method).

Arguments:

  • object the object to remove

Example:

pool.acquire(function (err, obj) {
    if (err) {
        console.log('Could not acquire object! ' + err);
    } else {
        // ...do something with the object
        // ...something went wrong
        pool.removeBadObject(obj);
    }
});

Pool.adjustLimits(min, max)

Changes the limits of the pool.

If there is a need of creating additional objects right away, they will be created during this call.

If the limits lowered, resource objects will only be freed by the idleTimout handler.

Arguments:

  • min - minimum number of objects in the pool
  • max - maximum number of objects in the pool

Pool.close()

Close the pool.

This will remove all free objects, prevent the creation of new objects, send an error to all following and pending acquire() calls.

The pool won't remove objects currently busy and will wait until they get released by release() or removeBadObject() calls.

SimpleQueue()

SimpleQueue implements the simplest queue (First-In, First-Out queue) to be used with advanced-pool. The only methods needed are push(), pop() and size().

The constructor doesn't accept any arguments

SimpleQueue.push()

Pushes a client to the queue.

Arguments:

  • {function} client - a callback function with two arguments, error and object.
  • queueParams - queue parameters for this client - SimpleQueue doesn't handle any parameters

Returns: nothing

SimpleQueue.pop()

Returns the next client.

Returns: client callback function

SimpleQueue.size()

Returns: the number of clients in the queue

npm loves you