Commit 4a714988 authored by Fabrice Colas's avatar Fabrice Colas

Focus on vertical reading given 'DRY' for func/arg

parent 2224ded5
......@@ -106,30 +106,20 @@ Memcached.config.poolSize = 25;
### Public methods
#### memcached.touch(key, lifetime, callback);
**memcached.touch** Touches the given key.
Touches the given key.
**Arguments**
`key`: **String** The key
`lifetime`: **Number** After how long should the key expire measured in `seconds`
`callback`: **Function**
* `key`: **String** The key
* `lifetime`: **Number** After how long should the key expire measured in `seconds`
* `callback`: **Function**
```js
memcached.touch('key', 10, function (err) {
// stuff
});
memcached.touch('key', 10, function (err) { /* stuff */ });
```
#### memcached.get(key, callback);
Get the value for the given key.
**memcached.get** Get the value for the given key.
**Arguments**
`key`: **String**, the key
`callback`: **Function**, the callback.
* `key`: **String**, the key
* `callback`: **Function**, the callback.
```js
memcached.get('foo', function (err, data) {
......@@ -137,14 +127,10 @@ memcached.get('foo', function (err, data) {
});
```
#### memcached.gets(key, callback);
Get the value and the CAS id.
**Arguments**
**memcached.gets** Get the value and the CAS id.
`key`: **String**, the key
`callback`: **Function**, the callback.
* `key`: **String**, the key
* `callback`: **Function**, the callback.
```js
memcached.gets('foo', function (err, data) {
......@@ -154,15 +140,10 @@ memcached.gets('foo', function (err, data) {
// Please note that the data is stored under the name of the given key.
});
```
**memcached.getMulti** Retrieves a bunch of values from multiple keys.
#### memcached.getMulti(keys, callback);
Retrieves a bunch of values from multiple keys.
**Arguments**
`keys`: **Array**, all the keys that needs to be fetched
`callback`: **Function**, the callback.
* `keys`: **Array**, all the keys that needs to be fetched
* `callback`: **Function**, the callback.
```js
memcached.getMulti(['foo', 'bar'], function (err, data) {
......@@ -171,206 +152,146 @@ memcached.getMulti(['foo', 'bar'], function (err, data) {
});
```
#### memcached.set(key, value, lifetime, callback);
Stores a new value in Memcached.
**memcached.set** Stores a new value in Memcached.
**Arguments**
`key`: **String** the name of the key
`value`: **Mixed** Either a buffer, JSON, number or string that you want to store.
`lifetime`: **Number**, how long the data needs to be stored measured in `seconds`
`callback`: **Function** the callback
* `key`: **String** the name of the key
* `value`: **Mixed** Either a buffer, JSON, number or string that you want to store.
* `lifetime`: **Number**, how long the data needs to be stored measured in `seconds`
* `callback`: **Function** the callback
```js
memcached.set('foo', 'bar', 10, function (err) {
// stuff
});
memcached.set('foo', 'bar', 10, function (err) { /* stuff */ });
```
#### memcached.replace(key, value, lifetime, callback);
Replaces the value in memcached.
**memcached.replace** Replaces the value in memcached.
**Arguments**
`key`: **String** the name of the key
`value`: **Mixed** Either a buffer, JSON, number or string that you want to store.
`lifetime`: **Number**, how long the data needs to be replaced measured in `seconds`
`callback`: **Function** the callback
* `key`: **String** the name of the key
* `value`: **Mixed** Either a buffer, JSON, number or string that you want to store.
* `lifetime`: **Number**, how long the data needs to be replaced measured in `seconds`
* `callback`: **Function** the callback
```js
memcached.replace('foo', 'bar', 10, function (err) {
// stuff
});
memcached.replace('foo', 'bar', 10, function (err) { /* stuff */ });
```
#### memcached.add(key, value, lifetime, callback);
Add the value, only if it's not in memcached already.
**Arguments**
**memcached.add** Add the value, only if it's not in memcached already.
`key`: **String** the name of the key
`value`: **Mixed** Either a buffer, JSON, number or string that you want to store.
`lifetime`: **Number**, how long the data needs to be replaced measured in `seconds`
`callback`: **Function** the callback
* `key`: **String** the name of the key
* `value`: **Mixed** Either a buffer, JSON, number or string that you want to store.
* `lifetime`: **Number**, how long the data needs to be replaced measured in `seconds`
* `callback`: **Function** the callback
```js
memcached.add('foo', 'bar', 10, function (err) {
// stuff
});
memcached.add('foo', 'bar', 10, function (err) { /* stuff */ });
```
#### memcached.cas(key, value, cas, lifetime, callback);
Add the value, only if it matches the given CAS value.
**Arguments**
**memcached.cas** Add the value, only if it matches the given CAS value.
`key`: **String** the name of the key
`value`: **Mixed** Either a buffer, JSON, number or string that you want to store.
`lifetime`: **Number**, how long the data needs to be replaced measured in `seconds`
`cas`: **String** the CAS value
`callback`: **Function** the callback
* `key`: **String** the name of the key
* `value`: **Mixed** Either a buffer, JSON, number or string that you want to store.
* `lifetime`: **Number**, how long the data needs to be replaced measured in `seconds`
* `cas`: **String** the CAS value
* `callback`: **Function** the callback
```js
memcached.gets('foo', function (err, data) {
memcached.cas('foo', 'bar', data.cas, 10, function (err) {
// stuff
});
memcached.cas('foo', 'bar', data.cas, 10, function (err) { /* stuff */ });
});
```
#### memcached.append(key, value, callback);
**memcached.append** Add the given value string to the value of an existing item.
Add the given value string to the value of an existing item.
**Arguments**
`key`: **String** the name of the key
`value`: **Mixed** Either a buffer, JSON, number or string that you want to store.
`callback`: **Function** the callback
* `key`: **String** the name of the key
* `value`: **Mixed** Either a buffer, JSON, number or string that you want to store.
* `callback`: **Function** the callback
```js
memcached.append('foo', 'bar', function (err) {
// stuff
});
memcached.append('foo', 'bar', function (err) { /* stuff */ });
```
#### memcached.prepend(key, value, callback);
**memcached.prepend** Add the given value string to the value of an existing item.
Add the given value string to the value of an existing item.
**Arguments**
`key`: **String** the name of the key
`value`: **Mixed** Either a buffer, JSON, number or string that you want to store.
`callback`: **Function** the callback
* `key`: **String** the name of the key
* `value`: **Mixed** Either a buffer, JSON, number or string that you want to store.
* `callback`: **Function** the callback
```js
memcached.preprend('foo', 'bar', function (err) {
// stuff
});
memcached.preprend('foo', 'bar', function (err) { /* stuff */ });
```
#### memcached.incr(key, amount, callback);
**memcached.incr** Increment a given key.
Increment a given key.
**Arguments**
`key`: **String** the name of the key
`amount`: **Number** The increment
`callback`: **Function** the callback
* `key`: **String** the name of the key
* `amount`: **Number** The increment
* `callback`: **Function** the callback
```js
memcached.incr('foo', 10, function (err) {
// stuff
});
memcached.incr('foo', 10, function (err) { /* stuff */ });
```
#### memcached.decr(key, amount, callback);
Decrement a given key.
**memcached.decr** Decrement a given key.
**Arguments**
`key`: **String** the name of the key
`amount`: **Number** The increment
`callback`: **Function** the callback
* `key`: **String** the name of the key
* `amount`: **Number** The increment
* `callback`: **Function** the callback
```js
memcached.incr('foo', 10, function (err) {
// stuff
});
memcached.incr('foo', 10, function (err) { /* stuff */ });
```
#### memcached.del(key, callback);
Remove the key from memcached.
**memcached.del** Remove the key from memcached.
**Arguments**
`key`: **String** the name of the key
`callback`: **Function** the callback
* `key`: **String** the name of the key
* `callback`: **Function** the callback
```js
memcached.del('foo', function (err) {
// stuff
});
memcached.del('foo', function (err) { /* stuff */ });
```
#### memcached.version(callback);
**memcached.version** Retrieves the version number of your server.
Retrieves the version number of your server.
* `callback`
#### memcached.flush(callback);
**memcached.flush** Flushes the memcached server.
Flushes the memcached server.
* `callback`
#### memcached.stats(callback);
**memcached.stats** Retrieves stats from your memcached server.
Retrieves stats from your memcached server.
* `callback`
#### memcached.settings(callback);
**memcached.settings** Retrieves your `stats settings`.
Retrieves your `stats settings`.
* `callback`
#### memcached.slabs(callback);
**memcached.slabs** Retrieves `stats slabs` information.
Retrieves `stats slabs` information.
* `callback`
#### memcached.items(callback);
**memcached.items** Retrieves `stats items` information.
Retrieves `stats items` information.
* `callback`
#### memcached.cachedump(server, slabid, number, callback);
**memcached.cachedump** Inspect cache, see examples for a detailed explanation.
Inspect cache, see examples for a detailed explanation.
* `server`
* `slabid`
* `number`
* `callback`
#### memcached.end();
Closes all active memcached connections.
**memcached.end** Closes all active memcached connections.
### Private methods
The following methods are intended for private usage:
---------------------------------------
#### .connect
Fetches or generates a connection for the given server. The supplied callback
The following methods are intended for private usage
**.connect** Fetches or generates a connection for the given server. The supplied callback
function will receive a reference to the connection as argument.
If there are issues with the server connection, we are going to respond with cache-miss pattern.
**Arguments**
`server`: *String*, The server that needs a connection, the format must be
* `server`: *String*, The server that needs a connection, the format must be
confirm the server_locations specification.
`callback`: *Function*, The callback function that receives the net.Stream
connection. It will be called with 2 arguments `error` and `connection`.
Example:
* `callback`: *Function*, The callback function that receives the net.Stre
``` js
memcached.connect( '192.168.0.103:11212', function( err, conn ){
......@@ -379,18 +300,12 @@ memcached.connect( '192.168.0.103:11212', function( err, conn ){
});
```
---------------------------------------
#### .multi
A small wrapper function that makes it easier to query multiple Memcached
**.multi** A small wrapper function that makes it easier to query multiple Memcached
servers. It will return the location for each key or the complete list of
servers.
**Arguments**
`keys`: *Array* **(optional)**, They keys that needs to be converted to a server.
`callback`: *Function*, The callback function for the data, it will be called
* `keys`: *Array* **(optional)**, They keys that needs to be converted to a server.
* `callback`: *Function*, The callback function for the data, it will be called
for **each** key. It will be called with 4 arguments:
1. `server`: *String*, The server location.
......@@ -399,8 +314,6 @@ for **each** key. It will be called with 4 arguments:
3. `index`: *Number*, The current index of the loop
4. `total`: *Number*, The total amount server retrieved.
Example:
``` js
memcached.multi( false, function( server, key, index, totals ){
if( err ) throw new Error( err );
......@@ -411,25 +324,17 @@ memcached.multi( false, function( server, key, index, totals ){
});
```
---------------------------------------
#### .command
This is the core functionality of the `memcached` client. All public API's are
**.command** This is the core functionality of the `memcached` client. All public API's are
routed through this function. It takes care of the argument validations Server
retrieval ( If the server argument isn't specified ). After all data ready a
connection is asked for the private `connect` method and the command is written
to the Memcached server.
**Arguments**
`query`: *Object*, The metaData object, see the `Callbacks` section for the
* `query`: *Object*, The metaData object, see the `Callbacks` section for the
specification.
`server`: *String*, The server the to connect. This is only needed when the
* `server`: *String*, The server the to connect. This is only needed when the
metaData object doesn't contain a key property to retrieve the server from.
Example:
``` js
memcached.command({
key: 'key', callback: function(){ console.dir( arguments ); },
......@@ -443,26 +348,17 @@ memcached.command({
});
```
---------------------------------------
#### .connectionIssue
A internal function for logging issues with connections. As there can be various
**.connectionIssue** A internal function for logging issues with connections. As there can be various
of ways that an error occurs we need solid issue manager to handle all these
cases. For example server could crash or the Memcached server could respond with
`SERVER ERROR <broken>`.
**Arguments**
`error`: *String*, The actual error message.
`Stream`: *net.Stream*, A reference to the connection stream where the error
* `error`: *String*, The actual error message.
* `Stream`: *net.Stream*, A reference to the connection stream where the error
occurred on.
`callback`: *Function* **(optional)**, The callback function of a potential
* `callback`: *Function* **(optional)**, The callback function of a potential
request, it will be marked as cache miss if it was provided
Example:
``` js
memcached.connectionIssue( "Server down", connectionReference );
```
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment