-
Notifications
You must be signed in to change notification settings - Fork 0
/
package.json
38 lines (38 loc) · 12.5 KB
/
package.json
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
{
"name": "generic-pool-redux",
"description": "Generic resource pooling in Javascript",
"version": "0.1.0",
"author": {
"name": "Tim Griesser",
"email": "tgriesser@gmail.com"
},
"keywords": [
"pool",
"pooling",
"throttle"
],
"main": "pool.js",
"repository": {
"type": "git",
"url": "git+ssh://git@github.com/bookshelf/generic-pool-redux.git"
},
"devDependencies": {
"expresso": ">0.0.0"
},
"engines": {
"node": ">= 0.2.0"
},
"scripts": {
"test": "expresso -I lib test/*.js"
},
"readme": "# About\nForked from [generic pool](https://github.com/coopernurse/node-pool), it can be used to reuse or throttle\nexpensive resources such as database connections.\n\n[![Build Status](https://travis-ci.org/bookshelf/generic-pool-redux.png?branch=master)](https://travis-ci.org/bookshelf/generic-pool-redux)\n\n## Example\n\n### Step 1 - Create pool using a factory object\n\n```js\n// Create a MySQL connection pool with\n// a max of 10 connections, a min of 2, and a 30 second max idle time\nvar poolModule = require('generic-pool');\nvar pool = poolModule.Pool({\n name : 'mysql',\n create : function(callback) {\n var Client = require('mysql').Client;\n var c = new Client();\n c.user = 'scott';\n c.password = 'tiger';\n c.database = 'mydb';\n c.connect();\n callback(null, c);\n },\n destroy : function(client) { client.end(); },\n max : 10,\n // optional. if you set this, make sure to drain() (see step 3)\n min : 2,\n // specifies how long a resource can stay idle in pool before being removed\n idleTimeoutMillis : 30000,\n // if true, logs via console.log - can also be a function\n log : true\n});\n```\n\n### Step 2 - Use pool in your code to acquire/release resources\n\n```js\n// acquire connection - callback function is called\n// once a resource becomes available\npool.acquire(function(err, client) {\n if (err) {\n // handle error - this is generally the err from your\n // factory.create function\n }\n else {\n client.query(\"select * from foo\", [], function() {\n // return object back to pool\n pool.release(client);\n });\n }\n});\n```\n\n### Step 3 - Drain pool during shutdown (optional)\n\nIf you are shutting down a long-lived process, you may notice\nthat node fails to exit for 30 seconds or so. This is a side\neffect of the idleTimeoutMillis behavior -- the pool has a\nsetTimeout() call registered that is in the event loop queue, so\nnode won't terminate until all resources have timed out, and the pool\nstops trying to manage them.\n\nThis behavior will be more problematic when you set factory.min > 0,\nas the pool will never become empty, and the setTimeout calls will\nnever end.\n\nIn these cases, use the pool.drain() function. This sets the pool\ninto a \"draining\" state which will gracefully wait until all\nidle resources have timed out. For example, you can call:\n\n```js\n// Only call this once in your application -- at the point you want\n// to shutdown and stop using this pool.\npool.drain(function() {\n pool.destroyAllNow();\n});\n```\n\nIf you do this, your node process will exit gracefully.\n\n## Documentation\n\n Pool() accepts an object with these slots:\n\n name : name of pool (string, optional)\n create : function that returns a new resource\n should call callback() with the created resource\n destroy : function that accepts a resource and destroys it\n max : maximum number of resources to create at any given time\n optional (default=1)\n min : minimum number of resources to keep in pool at any given time\n if this is set > max, the pool will silently set the min\n to factory.max - 1\n optional (default=0)\n refreshIdle : boolean that specifies whether idle resources at or below the min threshold\n should be destroyed/re-created. optional (default=true)\n idleTimeoutMillis : max milliseconds a resource can go unused before it should be destroyed\n (default 30000)\n reapIntervalMillis : frequency to check for idle resources (default 1000),\n priorityRange : int between 1 and x - if set, borrowers can specify their\n relative priority in the queue if no resources are available.\n see example. (default 1)\n validate : function that accepts a pooled resource and returns true if the resource\n is OK to use, or false if the object is invalid. Invalid objects will be destroyed.\n This function is called in acquire() before returning a resource from the pool.\n Optional. Default function always returns true.\n\n## Priority Queueing\n\nThe pool now supports optional priority queueing. This becomes relevant when no resources\nare available and the caller has to wait. `acquire()` accepts an optional priority int which\nspecifies the caller's relative position in the queue.\n\n```js\n // create pool with priorityRange of 3\n // borrowers can specify a priority 0 to 2\n var pool = poolModule.Pool({\n name : 'mysql',\n create : function(callback) {\n // do something\n },\n destroy : function(client) {\n // cleanup. omitted for this example\n },\n max : 10,\n idleTimeoutMillis : 30000,\n priorityRange : 3\n });\n\n // acquire connection - no priority - will go at end of line\n pool.acquire(function(err, client) {\n pool.release(client);\n });\n\n // acquire connection - high priority - will go into front slot\n pool.acquire(function(err, client) {\n pool.release(client);\n }, 0);\n\n // acquire connection - medium priority - will go into middle slot\n pool.acquire(function(err, client) {\n pool.release(client);\n }, 1);\n\n // etc..\n```\n\n## Draining\n\nIf you know would like to terminate all the resources in your pool before\ntheir timeouts have been reached, you can use `destroyAllNow()` in conjunction\nwith `drain()`:\n\n```js\npool.drain(function() {\n pool.destroyAllNow();\n});\n```\n\nOne side-effect of calling `drain()` is that subsequent calls to `acquire()`\nwill throw an Error.\n\n## Pooled function decoration\n\nTo transparently handle object acquisition for a function,\none can use `pooled()`:\n\n```js\nvar privateFn, publicFn;\npublicFn = pool.pooled(privateFn = function(client, arg, cb) {\n // Do something with the client and arg. Client is auto-released when cb is called\n cb(null, arg);\n});\n```\n\nKeeping both private and public versions of each function allows for pooled\nfunctions to call other pooled functions with the same member. This is a handy\npattern for database transactions:\n\n```js\nvar privateTop, privateBottom, publicTop, publicBottom;\npublicBottom = pool.pooled(privateBottom = function(client, arg, cb) {\n //Use client, assumed auto-release\n});\n\npublicTop = pool.pooled(privateTop = function(client, cb) {\n // e.g., open a database transaction\n privateBottom(client, \"arg\", function(err, retVal) {\n if(err) { return cb(err); }\n // e.g., close a transaction\n cb();\n });\n});\n```\n\n## Run Tests\n\n $ npm install expresso\n $ expresso -I lib test/*.js\n\n## Generic Pool Redux\n\n 0.1.0 - Sepember 13 2013\n - Rewriting the API to use prototypes, remove logging, added a callback on release, for consistency.\n\n## Generic Pool History (old fork)\n\n 2.0.4 - July 27 2013\n - Merged #64 - Fix for not removing idle objects (contributed by PiotrWpl)\n\n 2.0.3 - January 16 2013\n - Merged #56/#57 - Add optional refreshIdle flag. If false, idle resources at the pool minimum will not be\n destroyed/re-created. (contributed by wshaver)\n - Merged #54 - Factory can be asked to validate pooled objects (contributed by tikonen)\n\n 2.0.2 - October 22 2012\n - Fix #51, #48 - createResource() should check for null clientCb in err case (contributed by pooyasencha)\n - Merged #52 - fix bug of infinite wait when create object aync error (contributed by windyrobin)\n - Merged #53 - change the position of dispense and callback to ensure the time order (contributed by windyrobin)\n\n 2.0.1 - August 29 2012\n - Fix #44 - leak of 'err' and 'obj' in createResource()\n - Add devDependencies block to package.json\n - Add travis-ci.org integration\n\n 2.0.0 - July 31 2012\n - Non-backwards compatible change: remove adjustCallback\n - acquire() callback must accept two params: (err, obj)\n - Add optional 'min' param to factory object that specifies minimum number of\n resources to keep in pool\n - Merged #38 (package.json/Makefile changes - contributed by strk)\n\n 1.0.12 - June 27 2012\n - Merged #37 (Clear remove idle timer after destroyAllNow - contributed by dougwilson)\n\n 1.0.11 - June 17 2012\n - Merged #36 (\"pooled\" method to perform function decoration for pooled methods - contributed by cosbynator)\n\n 1.0.10 - May 3 2012\n - Merged #35 (Remove client from availbleObjects on destroy(client) - contributed by blax)\n\n 1.0.9 - Dec 18 2011\n - Merged #25 (add getName() - contributed by BryanDonovan)\n - Merged #27 (remove sys import - contributed by botker)\n - Merged #26 (log levels - contributed by JoeZ99)\n\n 1.0.8 - Nov 16 2011\n - Merged #21 (add getter methods to see pool size, etc. - contributed by BryanDonovan)\n\n 1.0.7 - Oct 17 2011\n - Merged #19 (prevent release on the same obj twice - contributed by tkrynski)\n - Merged #20 (acquire() returns boolean indicating whether pool is full - contributed by tilgovi)\n\n 1.0.6 - May 23 2011\n - Merged #13 (support error variable in acquire callback - contributed by tmcw)\n - Note: This change is backwards compatible. But new code should use the two\n parameter callback format in pool.create() functions from now on.\n - Merged #15 (variable scope issue in dispense() - contributed by eevans)\n\n 1.0.5 - Apr 20 2011\n - Merged #12 (ability to drain pool - contributed by gdusbabek)\n\n 1.0.4 - Jan 25 2011\n - Fixed #6 (objects reaped with undefined timeouts)\n - Fixed #7 (objectTimeout issue)\n\n 1.0.3 - Dec 9 2010\n - Added priority queueing (thanks to sylvinus)\n - Contributions from Poetro\n - Name changes to match conventions described here: http://en.wikipedia.org/wiki/Object_pool_pattern\n - borrow() renamed to acquire()\n - returnToPool() renamed to release()\n - destroy() removed from public interface\n - added JsDoc comments\n - Priority queueing enhancements\n\n 1.0.2 - Nov 9 2010\n - First NPM release\n\n\n## License\n\n(The MIT License)\n\nCopyright (c) 2010-2013 James Cooper <james@bitmechanic.com>\n\nPermission is hereby granted, free of charge, to any person obtaining\na copy of this software and associated documentation files (the\n'Software'), to deal in the Software without restriction, including\nwithout limitation the rights to use, copy, modify, merge, publish,\ndistribute, sublicense, and/or sell copies of the Software, and to\npermit persons to whom the Software is furnished to do so, subject to\nthe following conditions:\n\nThe above copyright notice and this permission notice shall be\nincluded in all copies or substantial portions of the Software.\n\nTHE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND,\nEXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF\nMERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.\nIN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY\nCLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,\nTORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE\nSOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.\n",
"readmeFilename": "README.md",
"bugs": {
"url": "https://github.com/bookshelf/generic-pool-redux/issues"
},
"homepage": "https://github.com/bookshelf/generic-pool-redux#readme",
"_id": "generic-pool-redux@0.1.0",
"_shasum": "326c2594e17fba4d4f0622cfe09acc3c84cb3a82",
"_resolved": "https://registry.npmjs.org/generic-pool-redux/-/generic-pool-redux-0.1.0.tgz",
"_from": "https://registry.npmjs.org/generic-pool-redux/-/generic-pool-redux-0.1.0.tgz"
}