Permalink
Browse files

[doc] Document the options

  • Loading branch information...
1 parent c509d43 commit 97d43d60d004294bbf38966197fa889e4687906d @3rd-Eden committed Jul 23, 2013
Showing with 40 additions and 3 deletions.
  1. +40 −3 README.md
View
@@ -12,36 +12,73 @@ abilities.
```js
var ConnectionPool = require('jackpot');
-// first argument: size of the connection pool
-// second argument: optional connection factory
+// First argument: size of the connection pool.
+// Second argument: optional connection factory.
+// Third argument: optional options.
var pool = new ConnectionPool(100);
+```
+
+The following options can be configured:
+
+- `retries` the amount of retries the pull method should do.
+- `factor` exponential backoff factor.
+- `min` minimal delay for the backoff.
+- `max` maximum delay for the backoff.
+- `randomize` randomize the connection.
+
+```js
+var pool = new ConnectionPool(100, {
+ min: 100
+ max: 50000
+});
+```
+
+But you can also set the properties:
+```js
// you can optionally boost the amount of retries after you have
// constructed a new instance
pool.retries = 5 // allow 5 failures for the #pull method
+```
+You can set the required factory at the contructor but also through a helper
+method:
+
+```js
// every connection pool requires a factory which is used to generate / setup
// the initial net.Connection
//
// it should return a new net.Connection instance..
pool.factory(function () {
return net.connect(port, host)
});
+```
+There are 2 ways to retrieve a connection, using `allocate`:
+
+``js`
// now that the pool is setup we can allocate a connection, the allocate
// requires a callback as it can be async..
pool.allocate(function (err, connection) {
// error: when we failed to get a connection
// connection: the allocated net.connection if there isn't an error
});
+```
+And `pull`;
+
+```js
// in addition to the #allocate method, there is also the pull method, which is
// fault tolerant wrapper around the allocate function as it can give back an
// error if the pool is full, so the pull will then retry to get a new
connection.pull(function (err, connection) {
// same arguments as the #allocate method
});
+```
+And some misc methods:
+
+```js
// call pool.free if you want to free connections from the pool, the arugment
// you supply is the amount of connections you want to keep
pool.free(10); // keep only 10 healthy connections kill the rest.
@@ -55,7 +92,7 @@ file.
## LICENSE (MIT)
-Copyright (c) 2012 Observe.it (http://observe.it) <opensource@observe.it>
+Copyright (c) 2013 Observe.it (http://observe.it) <opensource@observe.it>
Permission is hereby granted, free of charge, to any person obtaining a copy of
this software and associated documentation files (the "Software"), to deal in

0 comments on commit 97d43d6

Please sign in to comment.