Skip to content

Commit

Permalink
Edited README.md via GitHub
Browse files Browse the repository at this point in the history
  • Loading branch information
3rd-Eden committed Apr 21, 2011
1 parent 277086a commit 83c1db6
Showing 1 changed file with 65 additions and 38 deletions.
103 changes: 65 additions & 38 deletions README.md
Expand Up @@ -8,19 +8,22 @@ When these issues occur the nMemcached client will emit different events where y

The client is configurable on different levels. There's a global configuration that you update so all you Memcached clusters will use the same failure configuration for example, but it's also possible to overwrite these changes per nMemcached instance.

**Project status** Working, but untested. There are still a couple of internal cavecats that needs to be overcome.
**Project status** Working, but untested. There are still a couple of internal caveats that needs to be overcome.
At this point compression and sending `Buffer` objects as values are not supported. The project is getting closer to
it's first alpha release. So at this point, I would not recommonend for production servers **yet**. Feel free to contribute
it's first alpha release. So at this point, I would not recommend for production servers **yet**. Feel free to contribute
and apply patches where needed.

## Setting up the client

The constructor of the nMemcached client take 2 different arguments `server locations` and `options`. Syntax:

var nMemcached = require('nMemcached');
var memcached = new nMemcached(Server locations, options);
``` js
var nMemcached = require('nMemcached');
var memcached = new nMemcached(Server locations, options);
```

### Server locations

The server locations is designed to work with different formats. These formats are all internally parsed to the correct format so our consistent hashing scheme can work with it. You can either use:

1. **String**, this only works if you have are running a single server instance of Memcached.
Expand All @@ -44,9 +47,11 @@ The server locations is designed to work with different formats. These formats a

If you would implement one of the above formats, your constructor would something like this:

var memcache = new nMemcached({ '192.168.0.102:11212': 1, '192.168.0.103:11212': 2, '192.168.0.104:11212': 1 });
var memcache = new nMemcached([ '192.168.0.102:11212', '192.168.0.103:11212', '192.168.0.104:11212' ]);
var memcache = new nMemcached('192.168.0.102:11212');
``` js
var memcache = new nMemcached({ '192.168.0.102:11212': 1, '192.168.0.103:11212': 2, '192.168.0.104:11212': 1 });
var memcache = new nMemcached([ '192.168.0.102:11212', '192.168.0.103:11212', '192.168.0.104:11212' ]);
var memcache = new nMemcached('192.168.0.102:11212');
```

### Options

Expand All @@ -68,13 +73,17 @@ There 2 kinds of options that can be configured. A global configuration that wil

Example usage:

var memcache = new nMemcached('localhost:11212', {retries:10,retry:10000,remove:true,failOverServers:['192.168.0.103:11212']});
``` js
var memcache = new nMemcached('localhost:11212', {retries:10,retry:10000,remove:true,failOverServers:['192.168.0.103:11212']});
```

If you wish to configure the options globally:

var nMemcached = require( 'nMemcached' ).Client;
// all global configurations should be applied to the .config object of the Client.
nMemcached.config.poolSize = 25;
``` js
var nMemcached = require( 'nMemcached' ).Client;
// all global configurations should be applied to the .config object of the Client.
nMemcached.config.poolSize = 25;
```

## API

Expand All @@ -95,11 +104,15 @@ If there are issues with the server connection, we are going to respond with cac

`callback`: *Function*, The callback function that receives the net.Stream connection. It will be called with 2 arguments `error` and `connection`.

Example
memcached.connect( '192.168.0.103:11212', function( err, conn ){
if( err ) throw new Error( err );
console.log( conn.server );
});
Example:

``` js
memcached.connect( '192.168.0.103:11212', function( err, conn ){
if( err ) throw new Error( err );
console.log( conn.server );
});
```

---------------------------------------
#### .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.
Expand All @@ -115,14 +128,18 @@ A small wrapper function that makes it easier to query multiple Memcached server
3. `index`: *Number*, The current index of the loop
4. `total`: *Number*, The total amount server retrieved.

Example
memcached.multi( false, function( server, key, index, totals ){
if( err ) throw new Error( err );

this.connect( server, function( err, conn ){
console.log( "connection ready" )
})
});
Example:

``` js
memcached.multi( false, function( server, key, index, totals ){
if( err ) throw new Error( err );

this.connect( server, function( err, conn ){
console.log( "connection ready" )
})
});
```

---------------------------------------
#### .command

Expand All @@ -136,17 +153,21 @@ is written to the Memcached server.

`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
memcached.command({
key: 'key', callback: function(){ console.dir( arguments ); },
Example:

``` js
memcached.command({
key: 'key', callback: function(){ console.dir( arguments ); },

// validate the arguments
validate: [[ 'key', String ], [ 'callback', Function ]],

// validate the arguments
validate: [[ 'key', String ], [ 'callback', Function ]],
// used for the query
type: 'delete',
command: 'delete key'
});
```

// used for the query
type: 'delete',
command: 'delete key'
});
---------------------------------------
#### .connectionIssue

Expand All @@ -161,8 +182,12 @@ all these cases. For example server could crash or the Memcached server could re

`callback`: *Function* **(optional)**, The callback function of a potential request, it will be marked as cache miss if it was provided

Example
memcached.connectionIssue( "Server down", connectionReference );
Example:

``` js
memcached.connectionIssue( "Server down", connectionReference );
```

## Callbacks

Each method requires a callback function. Once this function get executed there will be 2 variables applied:
Expand Down Expand Up @@ -217,6 +242,8 @@ There are `5` different events that the nMemcached client emits when connection

Example implementations:

var memcached = new nMemcached([ '192.168.0.102:11212', '192.168.0.103:11212' ]);
memcached.on('failure', function( details ){ sys.error( "Server " + details.server + "went down due to: " + details.messages.join( '' ) ) });
memcached.on('reconnecting', function( details ){ sys.debug( "Total downtime caused by server " + details.server + " :" + details.totalDownTime + "ms")})
``` js
var memcached = new nMemcached([ '192.168.0.102:11212', '192.168.0.103:11212' ]);
memcached.on('failure', function( details ){ sys.error( "Server " + details.server + "went down due to: " + details.messages.join( '' ) ) });
memcached.on('reconnecting', function( details ){ sys.debug( "Total downtime caused by server " + details.server + " :" + details.totalDownTime + "ms")});
```

0 comments on commit 83c1db6

Please sign in to comment.