generic-pool
Advanced tools
Comparing version 2.4.2 to 3.0.0-alpha
{ | ||
"name": "generic-pool", | ||
"description": "Generic resource pooling for Node.JS", | ||
"version": "2.4.2", | ||
"version": "3.0.0-alpha", | ||
"author": "James Cooper <james@bitmechanic.com>", | ||
@@ -57,3 +57,3 @@ "contributors": [ | ||
], | ||
"main": "lib/generic-pool.js", | ||
"main": "index.js", | ||
"repository": { | ||
@@ -64,13 +64,17 @@ "type": "git", | ||
"devDependencies": { | ||
"expresso": ">0.0.0" | ||
"eslint": "^3.4.0", | ||
"eslint-config-standard": "^6.0.0", | ||
"eslint-plugin-promise": "^2.0.1", | ||
"eslint-plugin-standard": "^2.0.0", | ||
"tap": "^7.0.0" | ||
}, | ||
"engines": { | ||
"node": ">= 0.2.0" | ||
"node": ">= 4" | ||
}, | ||
"scripts": { | ||
"lint": "eslint lib test", | ||
"lint-install": "npm install eslint@^1.10.2 eslint-config-standard@^4.4.0 eslint-plugin-standard@^1.3.1" , | ||
"test": "expresso test/*.js" | ||
"lint-fix": "eslint --fix lib test", | ||
"test": "tap test/*-test.js --timeout 2" | ||
}, | ||
"license": "MIT" | ||
} |
365
README.md
[![build status](https://secure.travis-ci.org/coopernurse/node-pool.png)](http://travis-ci.org/coopernurse/node-pool) | ||
# About | ||
# Generic Pool | ||
Generic resource pool. Can be used to reuse or throttle expensive resources such as | ||
database connections. | ||
## About | ||
## Installation | ||
Generic resource pool. Can be used to reuse or throttle usage of expensive resources such as database connections. | ||
$ npm install generic-pool | ||
**Node.js Version Warning** | ||
Generic-Pool v3 requires a nodejs version of at least 4 | ||
## History | ||
@@ -16,56 +17,174 @@ | ||
## Installation | ||
```sh | ||
$ npm install generic-pool [--save] | ||
``` | ||
## Example | ||
### Step 1 - Create pool using a factory object | ||
Here is an example using a fictional generic database driver that doesn't implement any pooling whatsoever itself. | ||
```js | ||
// Create a MySQL connection pool with | ||
// a max of 10 connections, a min of 2, and a 30 second max idle time | ||
var Pool = require('generic-pool').Pool; | ||
var mysql = require('mysql'); // v2.10.x | ||
var DbDriver = require('some-db-driver'); | ||
var pool = new Pool({ | ||
name : 'mysql', | ||
create : function(callback) { | ||
var c = mysql.createConnection({ | ||
user: 'scott', | ||
password: 'tiger', | ||
database:'mydb' | ||
/** | ||
* Step 1 - Create pool using a factory object | ||
*/ | ||
const factory = { | ||
create: function(){ | ||
return new Promise(function(resolve, reject{ | ||
var client = DbDriver.createClient() | ||
client.on('connected', function(){ | ||
resolve(client) | ||
}) | ||
}) | ||
} | ||
destroy: function(client){ | ||
return new Promise(function(resolve){ | ||
client.on('end', function(){ | ||
resolve() | ||
}) | ||
client.disconnect() | ||
}) | ||
} | ||
} | ||
// parameter order: err, resource | ||
callback(null, c); | ||
}, | ||
destroy : function(client) { client.end(); }, | ||
max : 10, | ||
// optional. if you set this, make sure to drain() (see step 3) | ||
min : 2, | ||
// specifies how long a resource can stay idle in pool before being removed | ||
idleTimeoutMillis : 30000, | ||
// if true, logs via console.log - can also be a function | ||
log : true | ||
var opts = { | ||
max: 10, // maximum size of the pool | ||
min: 2 // minimum size of the pool | ||
} | ||
var myPool = new Pool(factory, opts) | ||
/** | ||
* Step 2 - Use pool in your code to acquire/release resources | ||
*/ | ||
// acquire connection - Promise is resolved | ||
// once a resource becomes available | ||
const resourcePromise = myPool.acquire() | ||
resourcePromise.then(function(client) { | ||
client.query("select * from foo", [], function() { | ||
// return object back to pool | ||
pool.release(client); | ||
}); | ||
}) | ||
.catch(function(err){ | ||
// handle error - this is generally a timeout or maxWaitingClients | ||
// error | ||
}); | ||
/** | ||
* Step 3 - Drain pool during shutdown (optional) | ||
*/ | ||
// Only call this once in your application -- at the point you want | ||
// to shutdown and stop using this pool. | ||
pool.drain(function() { | ||
pool.clear(); | ||
}); | ||
``` | ||
### Step 2 - Use pool in your code to acquire/release resources | ||
## Documentation | ||
### Constructor | ||
The `Pool` constructor takes two arguments: | ||
- `factory` : an object containing functions to create/destroy/test resources for the `Pool` | ||
- `opts` : an optional object/dictonary to allow configuring/altering behaviour the of the `Pool` | ||
```js | ||
// acquire connection - callback function is called | ||
// once a resource becomes available | ||
pool.acquire(function(err, client) { | ||
if (err) { | ||
// handle error - this is generally the err from your | ||
// factory.create function | ||
} | ||
else { | ||
client.query("select * from foo", [], function() { | ||
// return object back to pool | ||
pool.release(client); | ||
}); | ||
} | ||
}); | ||
var pool = new Pool(factory, opts) | ||
``` | ||
### Step 3 - Drain pool during shutdown (optional) | ||
**factory** | ||
Can be any object/instance but must have the following properties: | ||
- `create` : a function that the pool will call when it wants a new resource. It should return a Promise that either resolves to a `resource` or rejects to an `Error` if it is unable to create a resourse for whatever. | ||
- `destroy`: a function that the pool will call when it wants to destroy a resource. It should accept one argument `resource` where `resource` is whatever `factory.create` made. The `destroy` function should return a `Promise` that resolves once it has destroyed the resource. | ||
optionally it can also have the following property: | ||
- `validate`: a function that the pool will call if it wants to validate a resource. It should accept one argument `resource` where `resource` is whatever `factory.create` made. Should return a `Promise` that resolves a `boolean` where `true` indicates the resource is still valid or `false` if the resource is invalid. | ||
**opts** | ||
An optional object/dictionary with the any of the following properties: | ||
- `max`: maximum number of resources to create at any given time. (default=1) | ||
- `min`: minimum number of resources to keep in pool at any given time. If this is set >= max, the pool will silently set the min to equal `max`. (default=0) | ||
- `maxWaitingClients`: maximum number of queued requests allowed, additional `acquire` calls will be callback with an `err` in a future cycle of the event loop. | ||
- `testOnBorrow`: `boolean`: should the pool validate resources before giving them to clients. Requires that either `factory.validate` or `factory.validateAsync` to be specified. | ||
- `refreshIdle`: `boolean` that specifies whether idle resources at or below the min threshold should be destroyed/re-created. (default=true) | ||
- `idleTimeoutMillis`: max milliseconds a resource can stay unused in the pool without being borrowed before it should be destroyed (default 30000) | ||
- `reapIntervalMillis`: interval to check for idle resources (default 1000). (remove me!) | ||
- `acquireTimeoutMillis`: max milliseconds an `acquire` call will wait for a resource before timing out. (default no limit), if supplied should non-zero positive integer. | ||
- `lifo` : if true the oldest resources will be first to be allocated. If false the most recently released resources will be the first to be allocated. This in effect turns the pool's behaviour from a queue into a stack. `boolean`, (default true) | ||
- `priorityRange`: int between 1 and x - if set, borrowers can specify their relative priority in the queue if no resources are available. | ||
see example. (default 1) | ||
- `autostart`: boolean, should the pool start creating resources etc once the constructor is called, (default true) | ||
### pool.acquire | ||
```js | ||
const onfulfilled = function(resource){ | ||
resource.doStuff() | ||
// release/destroy/etc | ||
} | ||
pool.acquire().then(onfulfilled) | ||
//or | ||
const priority = 2 | ||
pool.acquire(priority).then(onfulfilled) | ||
``` | ||
This function is for when you want to "borrow" a resource from the pool. | ||
`acquire` takes one optional argument: | ||
- `priority`: optional, number, see **Priority Queueing** below. | ||
and returns a `Promise` | ||
Once a resource in the pool is available, the promise will be resolved with a `resource` (whatever `factory.create` makes for you). If the Pool is unable to give a resource (e.g timeout) then the promise will be rejected with an `Error` | ||
### pool.release | ||
```js | ||
pool.release(resource) | ||
``` | ||
This function is for when you want to return a resource to the pool. | ||
`release` takes one required argument: | ||
- `resource`: a previously borrowed resource | ||
### pool.destroy | ||
This function is for when you want to return a resource to the pool but want it destroyed rather than being made available to other resources. E.g you may know the resource has timed out or crashed. | ||
`destroy` takes one required argument: | ||
- `resource`: a previously borrow resource | ||
### pool.on | ||
The pool is an event emitter. Below are the events it emits and any args for those events | ||
`factoryCreateError` : emitted when a promise returned by `factory.create` is rejected. If this event has no listeners then the `error` will be silently discarded | ||
- `err`: whatever `reason` the promise was rejected with. | ||
## Draining | ||
If you are shutting down a long-lived process, you may notice | ||
@@ -86,90 +205,35 @@ that node fails to exit for 30 seconds or so. This is a side | ||
```js | ||
// Only call this once in your application -- at the point you want | ||
// to shutdown and stop using this pool. | ||
pool.drain(function() { | ||
pool.destroyAllNow(); | ||
}); | ||
``` | ||
If you do this, your node process will exit gracefully. | ||
## Priority Queueing | ||
## Documentation | ||
The pool supports optional priority queueing. This becomes relevant when no resources are available and the caller has to wait. `acquire()` accepts an optional priority int which | ||
specifies the caller's relative position in the queue. Each priority slot has it's own internal queue created for it. When a resource is available for borrowing, the first request in the highest priority queue will be given it. | ||
Pool() accepts an object with these slots: | ||
Specifying a `priority` to `acquire` that is outside the `priorityRange` set at `Pool` creation time will result in the `priority` being converted the lowest possible `priority` | ||
name : name of pool (string, optional) | ||
create : function that returns a new resource | ||
should call callback() with the created resource | ||
destroy : function that accepts a resource and destroys it | ||
max : maximum number of resources to create at any given time | ||
optional (default=1) | ||
min : minimum number of resources to keep in pool at any given time | ||
if this is set >= max, the pool will silently set the min | ||
to factory.max - 1 (Note: min==max case is expected to change in v3 release) | ||
optional (default=0) | ||
refreshIdle : boolean that specifies whether idle resources at or below the min threshold | ||
should be destroyed/re-created. optional (default=true) | ||
idleTimeoutMillis : max milliseconds a resource can go unused before it should be destroyed | ||
(default 30000) | ||
reapIntervalMillis : frequency to check for idle resources (default 1000), | ||
returnToHead : boolean, if true the most recently released resources will be the first to be allocated. | ||
This in effect turns the pool's behaviour from a queue into a stack. optional (default false) | ||
priorityRange : int between 1 and x - if set, borrowers can specify their | ||
relative priority in the queue if no resources are available. | ||
see example. (default 1) | ||
validate : function that accepts a pooled resource and returns true if the resource | ||
is OK to use, or false if the object is invalid. Invalid objects will be destroyed. | ||
This function is called in acquire() before returning a resource from the pool. | ||
Optional. Default function always returns true. | ||
validateAsync : Asynchronous validate function. Receives a callback function as its second argument, | ||
which should be called with a single boolean argument being true if the item is still | ||
valid and false if it should be removed from the pool. Called before item is acquired | ||
from pool. Default is undefined. Only one of validate/validateAsync may be specified | ||
log : true/false or function - | ||
If a log is a function, it will be called with two parameters: | ||
- log string | ||
- log level ('verbose', 'info', 'warn', 'error') | ||
Else if log is true, verbose log info will be sent to console.log() | ||
Else internal log messages be ignored (this is the default) | ||
## Priority Queueing | ||
The pool now supports optional priority queueing. This becomes relevant when no resources | ||
are available and the caller has to wait. `acquire()` accepts an optional priority int which | ||
specifies the caller's relative position in the queue. | ||
```js | ||
// create pool with priorityRange of 3 | ||
// borrowers can specify a priority 0 to 2 | ||
var pool = new Pool({ | ||
name : 'mysql', | ||
create : function(callback) { | ||
// do something | ||
}, | ||
destroy : function(client) { | ||
// cleanup. omitted for this example | ||
}, | ||
max : 10, | ||
idleTimeoutMillis : 30000, | ||
priorityRange : 3 | ||
}); | ||
// create pool with priorityRange of 3 | ||
// borrowers can specify a priority 0 to 2 | ||
var opts = { | ||
priorityRange : 3 | ||
} | ||
var pool = new Pool(someFactory,opts); | ||
// acquire connection - no priority - will go at front of line (same as high priority) | ||
pool.acquire(function(err, client) { | ||
pool.release(client); | ||
}); | ||
// acquire connection - no priority specified - will go onto lowest priority queue | ||
pool.acquire().thenfunction(client) { | ||
pool.release(client); | ||
}); | ||
// acquire connection - high priority - will go into front slot | ||
pool.acquire(function(err, client) { | ||
pool.release(client); | ||
}, 0); | ||
// acquire connection - high priority - will go into highest priority queue | ||
pool.acquire(0).then(function(client) { | ||
pool.release(client); | ||
}); | ||
// acquire connection - medium priority - will go into middle slot | ||
pool.acquire(function(err, client) { | ||
pool.release(client); | ||
}, 1); | ||
// acquire connection - medium priority - will go into 'mid' priority queue | ||
pool.acquire(1).then(function(client) { | ||
pool.release(client); | ||
}); | ||
// etc.. | ||
// etc.. | ||
``` | ||
@@ -179,11 +243,28 @@ | ||
If you know would like to terminate all the resources in your pool before | ||
their timeouts have been reached, you can use `destroyAllNow()` in conjunction | ||
with `drain()`: | ||
If you are shutting down a long-lived process, you may notice | ||
that node fails to exit for 30 seconds or so. This is a side | ||
effect of the idleTimeoutMillis behavior -- the pool has a | ||
setTimeout() call registered that is in the event loop queue, so | ||
node won't terminate until all resources have timed out, and the pool | ||
stops trying to manage them. | ||
This behavior will be more problematic when you set factory.min > 0, | ||
as the pool will never become empty, and the setTimeout calls will | ||
never end. | ||
In these cases, use the pool.drain() function. This sets the pool | ||
into a "draining" state which will gracefully wait until all | ||
idle resources have timed out. For example, you can call: | ||
If you do this, your node process will exit gracefully. | ||
If you know you would like to terminate all the available resources in your pool before any timeouts they might have are reached, you can use `clear()` in conjunction with `drain()`: | ||
```js | ||
pool.drain(function() { | ||
pool.destroyAllNow(); | ||
const p = pool.drain() | ||
.then(function() { | ||
return pool.clear(); | ||
}); | ||
``` | ||
The `promise` returned will resolve once all waiting clients have acquired and return resources, and any available resources have been destroyed | ||
@@ -231,20 +312,18 @@ One side-effect of calling `drain()` is that subsequent calls to `acquire()` | ||
```js | ||
// returns factory.name for this pool | ||
pool.getName() | ||
// returns number of resources in the pool regardless of | ||
// whether they are free or in use | ||
pool.getPoolSize() | ||
pool.size | ||
// returns number of unused resources in the pool | ||
pool.availableObjectsCount() | ||
pool.available | ||
// returns number of callers waiting to acquire a resource | ||
pool.waitingClientsCount() | ||
pool.pending | ||
// returns number of maxixmum number of resources allowed by ppol | ||
pool.getMaxPoolSize() | ||
pool.max | ||
// returns number of minimum number of resources allowed by ppol | ||
pool.getMinPoolSize() | ||
pool.min | ||
@@ -255,26 +334,12 @@ ``` | ||
$ npm install expresso | ||
$ npm install | ||
$ npm test | ||
The test runner runs every test in parallel, so tests cannot safely share | ||
resources. If a test fails, its thrown assertion error may bubble up and halt | ||
execution/cause failures in other running tests; these are spurious. If you | ||
have a failing test, try running it in isolation until you get it to pass. | ||
The tests are run/written using Tap. Most are ports from the old espresso tests and are not in great condition. Most cases are inside `test/generic-pool-test.js` with newer cases in their own files (legacy reasons). | ||
The individual tests "wait" by repeatedly checking the condition in the | ||
`beforeExit` callback. The test is marked as "passed" if the `beforeExit` | ||
callback runs successfully. Generally, this is accomplished by counting the | ||
number of assertions and checking that all of the test's assertions have been | ||
asserted. | ||
## Linting | ||
We use eslint and the `standard` ruleset. At the moment linting is not done as part of the test suite but this will probably change in the future. You should ideally lint your code before making any PR's patches etc. | ||
We use eslint and the `standard` ruleset. | ||
Becuase the linting tools require nodejs >= `0.10` but we test against `0.8` and `0.6` installation of the tools is done via `npm run lint-install`. Some kind of optionalDevDependencies would be great! | ||
$ npm run lint-install | ||
$ npm run lint | ||
## License | ||
@@ -281,0 +346,0 @@ |
Sorry, the diff of this file is not supported yet
Sorry, the diff of this file is not supported yet
License Policy Violation
LicenseThis package is not allowed per your license policy. Review the package's license to ensure compliance.
Found 1 instance in 1 package
Major refactor
Supply chain riskPackage has recently undergone a major refactor. It may be unstable or indicate significant internal changes. Use caution when updating to versions that include significant changes.
Found 1 instance in 1 package
No v1
QualityPackage is not semver >=1. This means it is not stable and does not support ^ ranges.
Found 1 instance in 1 package
License Policy Violation
LicenseThis package is not allowed per your license policy. Review the package's license to ensure compliance.
Found 1 instance in 1 package
77121
26
1898
364
5
2
1