Skip to content
This repository
Browse code

[doc] Reformat the doc & added travis ci badge

  • Loading branch information...
commit 24f2b755e007abc85ff39afee258f7a66dc5f9d8 1 parent fec8789
Arnout Kazemier authored October 20, 2012

Showing 1 changed file with 167 additions and 92 deletions. Show diff stats Hide diff stats

  1. 259  README.md
259  README.md
Source Rendered
... ...
@@ -1,20 +1,40 @@
1  
-#Memcached
2  
-
3  
-`memcached` is a fully featured Memcached client for Node.js. `memcached` is build with scaling, high availability and exceptional performance in mind. We use consistent hashing to store the data across different nodes. Consistent hashing is a scheme that provides a hash table functionality in a way that adding or removing a server node does not significantly change the mapping of the keys to server nodes. The algorithm that is used for consistent hashing is the same as `libketama`.
4  
-
5  
-There are different ways to handle errors for example, when a server becomes unavailable you can configure the client to see all requests to that server as cache misses until it goes up again. It's also possible to automatically remove the affected server from the consistent hashing algorithm or provide `memcached` with a failover server that can take the place of the unresponsive server.
6  
-
7  
-When these issues occur the `memcached` client will emit different events where you can subscribe to containing detailed information about the issues.
8  
-
9  
-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 `memcached` instance.
  1
+#Memcached [![Build Status](https://secure.travis-ci.org/3rd-Eden/node-memcached.png?branch=master)](http://travis-ci.org/3rd-Eden/node-memcached)
  2
+
  3
+`memcached` is a fully featured Memcached client for Node.js. `memcached` is
  4
+build with scaling, high availability and exceptional performance in mind. We
  5
+use consistent hashing to store the data across different nodes. Consistent
  6
+hashing is a scheme that provides a hash table functionality in a way that
  7
+adding or removing a server node does not significantly change the mapping of
  8
+the keys to server nodes. The algorithm that is used for consistent hashing is
  9
+the same as `libketama`.
  10
+
  11
+There are different ways to handle errors for example, when a server becomes
  12
+unavailable you can configure the client to see all requests to that server as
  13
+cache misses until it goes up again. It's also possible to automatically remove
  14
+the affected server from the consistent hashing algorithm or provide `memcached`
  15
+with a failover server that can take the place of the unresponsive server.
  16
+
  17
+When these issues occur the `memcached` client will emit different events where
  18
+you can subscribe to containing detailed information about the issues.
  19
+
  20
+The client is configurable on different levels. There's a global configuration
  21
+that you update so all you Memcached clusters will use the same failure
  22
+configuration for example, but it's also possible to overwrite these changes per
  23
+`memcached` instance.
10 24
 
11 25
 ### protocol
12 26
 
13  
-This module uses the ASCII protocol to communicate with the server, this makes it easier to debug for you are user as you can see what is send over the wire but also for me as developer. But this also means that SASL auth is not supported in this driver as that requires the use of the binary protocol. The ASCII protocol not only used by memcached but also by other databases and message queues, so that is a nice extra.
  27
+This module uses the ASCII protocol to communicate with the server, this makes
  28
+it easier to debug for you are user as you can see what is send over the wire
  29
+but also for me as developer. But this also means that SASL auth is not
  30
+supported in this driver as that requires the use of the binary protocol. The
  31
+ASCII protocol not only used by memcached but also by other databases and
  32
+message queues, so that is a nice extra.
14 33
 
15 34
 ## Setting up the client
16 35
 
17  
-The constructor of the `memcached` client take 2 different arguments `server locations` and `options`. Syntax:
  36
+The constructor of the `memcached` client take 2 different arguments `server
  37
+locations` and `options`. Syntax:
18 38
 
19 39
 ``` js
20 40
 var Memcached = require('memcached');
@@ -23,30 +43,37 @@ var memcached = new Memcached(Server locations, options);
23 43
 
24 44
 ### Server locations
25 45
 
26  
-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:
27  
-
28  
-1.	**String**, this only works if you have are running a single server instance of Memcached.
29  
-	It's as easy a suppling a string in the following format: `hostname:port`. For example
30  
-	`192.168.0.102:11212` This would tell the client to connect to host `192.168.0.102` on
31  
-	port number `11212`.
32  
-
33  
-2.	**Array**, if you are running a single server you would only have to supply one item in the array.
34  
-	The array format is particularly useful if you are running a cluster of Memcached servers. This will
35  
-	allow you to spread the keys and load between the different servers. Giving you higher availability for
36  
-	when one of your Memcached servers goes down.
37  
-	
38  
-3.	**Object**, when you are running a cluster of Memcached servers it could happen to not all server can
39  
-	allocate the same amount of memory. You might have a Memcached server with 128mb, 512, 128mb. If you would
40  
-	the array structure all servers would have the same weight in the consistent hashing scheme. Spreading the
41  
-	keys 33/33/33 over the servers. But as server 2 has more memory available you might want to give it more weight
42  
-	so more keys get stored on that server. When you are using a object, the `key` should represent the server
43  
-	location syntax and the value the weight of the server. By default all servers have a weight of 1. 
44  
-	`{ '192.168.0.102:11212': 1, '192.168.0.103:11212': 2, '192.168.0.104:11212': 1 }` would generate a 25/50/25 
45  
-	distribution of the keys.
46  
-
47  
-If you would implement one of the above formats, your constructor would something like this:
48  
-
49  
-``` js
  46
+The server locations is designed to work with different formats. These formats
  47
+are all internally parsed to the correct format so our consistent hashing scheme
  48
+can work with it. You can either use:
  49
+
  50
+1. **String**, this only works if you have are running a single server instance
  51
+   of Memcached.  It's as easy a suppling a string in the following format:
  52
+   `hostname:port`. For example `192.168.0.102:11212` This would tell the client
  53
+   to connect to host `192.168.0.102` on port number `11212`.
  54
+
  55
+2. **Array**, if you are running a single server you would only have to supply
  56
+  one item in the array.  The array format is particularly useful if you are
  57
+  running a cluster of Memcached servers. This will allow you to spread the keys
  58
+  and load between the different servers. Giving you higher availability for
  59
+  when one of your Memcached servers goes down.
  60
+  
  61
+3. **Object**, when you are running a cluster of Memcached servers it could
  62
+   happen to not all server can allocate the same amount of memory. You might
  63
+   have a Memcached server with 128mb, 512, 128mb. If you would the array
  64
+   structure all servers would have the same weight in the consistent hashing
  65
+   scheme. Spreading the keys 33/33/33 over the servers. But as server 2 has
  66
+   more memory available you might want to give it more weight so more keys get
  67
+   stored on that server. When you are using a object, the `key` should
  68
+   represent the server location syntax and the value the weight of the server.
  69
+   By default all servers have a weight of 1.  `{ '192.168.0.102:11212': 1,
  70
+   '192.168.0.103:11212': 2, '192.168.0.104:11212': 1 }` would generate a
  71
+   25/50/25 distribution of the keys.
  72
+
  73
+If you would implement one of the above formats, your constructor would
  74
+something like this:
  75
+
  76
+```js
50 77
 var memcached = new Memcached({ '192.168.0.102:11212': 1, '192.168.0.103:11212': 2, '192.168.0.104:11212': 1 });
51 78
 var memcached = new Memcached([ '192.168.0.102:11212', '192.168.0.103:11212', '192.168.0.104:11212' ]);
52 79
 var memcached = new Memcached('192.168.0.102:11212');
@@ -54,30 +81,42 @@ var memcached = new Memcached('192.168.0.102:11212');
54 81
 
55 82
 ### Options
56 83
 
57  
-There 2 kinds of options that can be configured. A global configuration that will be inherited by all Memcached servers instances and a client specific configuration that can be used to overwrite the globals. The options should be formatted in an JavaScript `object`. They both use the same object structure:
  84
+There 2 kinds of options that can be configured. A global configuration that
  85
+will be inherited by all Memcached servers instances and a client specific
  86
+configuration that can be used to overwrite the globals. The options should be
  87
+formatted in an JavaScript `object`. They both use the same object structure:
58 88
 
59 89
 * `maxKeySize`: *250*, the max size of they key allowed by the Memcached server.
60  
-* `maxExpiration`: *2592000*, the max expiration of keys by the Memcached server in milliseconds.
61  
-* `maxValue`: *1048576*, the max size of a value that is allowed by the Memcached server.
  90
+* `maxExpiration`: *2592000*, the max expiration of keys by the Memcached server
  91
+  in milliseconds.
  92
+* `maxValue`: *1048576*, the max size of a value that is allowed by the
  93
+  Memcached server.
62 94
 * `poolSize`: *10*, the maximum connections we can allocate in our connection pool.
63  
-* `algorithm`: *crc32*, the hashing algorithm that should be used to generate the hashRing values.
64  
-* `reconnect`: *18000000*, when the server is marked as dead we will attempt to reconnect every x milliseconds.
65  
-* `timeout`: *5000*, after x ms the server should send a timeout if we can't connect. This will also be used close the connection if we are idle.
  95
+* `algorithm`: *crc32*, the hashing algorithm that should be used to generate
  96
+  the hashRing values.
  97
+* `reconnect`: *18000000*, when the server is marked as dead we will attempt to
  98
+  reconnect every x milliseconds.
  99
+* `timeout`: *5000*, after x ms the server should send a timeout if we can't
  100
+  connect. This will also be used close the connection if we are idle.
66 101
 * `retries`: *5*, amount of tries before we mark the server as dead.
67 102
 * `retry`: *30000*, timeout between each retry in x milliseconds.
68  
-* `remove`: *false*, when the server is marked as dead you can remove it from the pool so all other will receive the keys instead.
69  
-* `failOverServers`: *undefined*, the ability use these servers as failover when the dead server get's removed from the consistent hashing scheme. This must be an array of servers confirm the server_locations specification.
70  
-* `keyCompression`: *true*, compress keys using md5 if they exceed the maxKeySize option.
  103
+* `remove`: *false*, when the server is marked as dead you can remove it from
  104
+  the pool so all other will receive the keys instead.
  105
+* `failOverServers`: *undefined*, the ability use these servers as failover when
  106
+  the dead server get's removed from the consistent hashing scheme. This must be
  107
+  an array of servers confirm the server_locations specification.
  108
+* `keyCompression`: *true*, compress keys using md5 if they exceed the
  109
+  maxKeySize option.
71 110
 
72 111
 Example usage:
73 112
 
74  
-``` js
  113
+```js
75 114
 var memcached = new Memcached('localhost:11212', {retries:10,retry:10000,remove:true,failOverServers:['192.168.0.103:11212']});
76 115
 ```
77 116
 
78 117
 If you wish to configure the options globally:
79 118
 
80  
-``` js
  119
+```js
81 120
 var Memcached = require('memcached');
82 121
 // all global configurations should be applied to the .config object of the Client.
83 122
 Memcached.config.poolSize = 25;
@@ -93,92 +132,107 @@ The following methods are intended for private usage:
93 132
 
94 133
 ---------------------------------------
95 134
 #### .connect
96  
-Fetches or generates a connection for the given server. The supplied callback function will receive a reference to the connection as argument.
  135
+Fetches or generates a connection for the given server. The supplied callback
  136
+function will receive a reference to the connection as argument.
97 137
 If there are issues with the server connection, we are going to respond with cache-miss pattern.
98 138
 
99 139
 **Arguments**
100 140
 
101  
-`server`: *String*, The server that needs a connection, the format must be confirm the server_locations specification.
  141
+`server`: *String*, The server that needs a connection, the format must be
  142
+confirm the server_locations specification.
102 143
 
103  
-`callback`: *Function*, The callback function that receives the net.Stream connection. It will be called with 2 arguments `error` and `connection`.
  144
+`callback`: *Function*, The callback function that receives the net.Stream
  145
+connection. It will be called with 2 arguments `error` and `connection`.
104 146
 
105 147
 Example:
106 148
 
107 149
 ``` js
108 150
 memcached.connect( '192.168.0.103:11212', function( err, conn ){
109  
-	if( err ) throw new Error( err );
110  
-	console.log( conn.server );
  151
+  if( err ) throw new Error( err );
  152
+  console.log( conn.server );
111 153
 });
112 154
 ```
113 155
 
114 156
 ---------------------------------------
115 157
 #### .multi
116  
-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.
  158
+A small wrapper function that makes it easier to query multiple Memcached
  159
+servers. It will return the location for each key or the complete list of
  160
+servers.
117 161
 
118 162
 **Arguments**
119 163
 
120 164
 `keys`: *Array* **(optional)**, They keys that needs to be converted to a server.
121 165
 
122  
-`callback`: *Function*, The callback function for the data, it will be called for **each** key. It will be called with 4 arguments:
  166
+`callback`: *Function*, The callback function for the data, it will be called
  167
+for **each** key. It will be called with 4 arguments:
123 168
 
124  
-1.	`server`: *String*, The server location.
125  
-2.	`key`: *String*, The key associated with the server, if you didn't specify keys, this variable will be undefined.
126  
-3.	`index`: *Number*, The current index of the loop
127  
-4.	`total`: *Number*, The total amount server retrieved.
  169
+1. `server`: *String*, The server location.
  170
+2. `key`: *String*, The key associated with the server, if you didn't specify
  171
+   keys, this variable will be undefined.
  172
+3. `index`: *Number*, The current index of the loop
  173
+4. `total`: *Number*, The total amount server retrieved.
128 174
 
129 175
 Example:
130 176
 
131 177
 ``` js
132 178
 memcached.multi( false, function( server, key, index, totals ){
133  
-	if( err ) throw new Error( err );
134  
-	
135  
-	this.connect( server, function( err, conn ){
136  
-		console.log( "connection ready" )
137  
-	})
  179
+  if( err ) throw new Error( err );
  180
+  
  181
+  this.connect( server, function( err, conn ){
  182
+    console.log( "connection ready" )
  183
+  })
138 184
 });
139 185
 ```
140 186
 
141 187
 ---------------------------------------
142 188
 #### .command
143 189
 
144  
-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
145  
-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
146  
-is written to the Memcached server.
  190
+This is the core functionality of the `memcached` client. All public API's are
  191
+routed through this function. It takes care of the argument validations Server
  192
+retrieval ( If the server argument isn't specified ). After all data ready a
  193
+connection is asked for the private `connect` method and the command is written
  194
+to the Memcached server.
147 195
 
148 196
 **Arguments**
149 197
 
150  
-`query`: *Object*, The metaData object, see the `Callbacks` section for the specification.
  198
+`query`: *Object*, The metaData object, see the `Callbacks` section for the
  199
+specification.
151 200
 
152  
-`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. 
  201
+`server`: *String*, The server the to connect. This is only needed when the
  202
+metaData object doesn't contain a key property to retrieve the server from. 
153 203
 
154 204
 Example:
155 205
 
156 206
 ``` js
157 207
 memcached.command({
158  
-	key: 'key', callback: function(){ console.dir( arguments ); },
  208
+  key: 'key', callback: function(){ console.dir( arguments ); },
159 209
 
160  
-	// validate the arguments
161  
-	validate: [[ 'key', String ], [ 'callback', Function ]],
  210
+  // validate the arguments
  211
+  validate: [[ 'key', String ], [ 'callback', Function ]],
162 212
 
163  
-	// used for the query
164  
-	type: 'delete',
165  
-	command: 'delete key'
  213
+  // used for the query
  214
+  type: 'delete',
  215
+  command: 'delete key'
166 216
 });
167 217
 ```
168 218
 
169 219
 ---------------------------------------
170 220
 #### .connectionIssue
171 221
 
172  
-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
173  
-all these cases. For example server could crash or the Memcached server could respond with `SERVER ERROR <broken>`.
  222
+A internal function for logging issues with connections. As there can be various
  223
+of ways that an error occurs we need solid issue manager to handle all these
  224
+cases. For example server could crash or the Memcached server could respond with
  225
+`SERVER ERROR <broken>`.
174 226
 
175 227
 **Arguments**
176 228
 
177 229
 `error`: *String*, The actual error message.
178 230
 
179  
-`Stream`: *net.Stream*, A reference to the connection stream where the error occurred on.
  231
+`Stream`: *net.Stream*, A reference to the connection stream where the error
  232
+occurred on.
180 233
 
181  
-`callback`: *Function* **(optional)**, The callback function of a potential request, it will be marked as cache miss if it was provided
  234
+`callback`: *Function* **(optional)**, The callback function of a potential
  235
+request, it will be marked as cache miss if it was provided
182 236
 
183 237
 Example:
184 238
 
@@ -188,12 +242,20 @@ memcached.connectionIssue( "Server down", connectionReference );
188 242
 
189 243
 ## Callbacks
190 244
 
191  
-Each method requires a callback function. Once this function get executed there will be 2 variables applied:
  245
+Each method requires a callback function. Once this function get executed there
  246
+will be 2 variables applied:
192 247
 
193  
-* `error`: A error response if something went wrong while retrieving data from the Memcached server. Depending on the type of request this will either be an string or an Array with multiple errors.
194  
-* `response`: The actual result from the Memcached server. If the response is `false` or `undefined` than a cache miss occurred. Cache misses will also occur when there is an error. So you might want to check on errors first.
  248
+* `error`: A error response if something went wrong while retrieving data from
  249
+  the Memcached server. Depending on the type of request this will either be an
  250
+  string or an Array with multiple errors.
  251
+* `response`: The actual result from the Memcached server. If the response is
  252
+  `false` or `undefined` than a cache miss occurred. Cache misses will also
  253
+  occur when there is an error. So you might want to check on errors first.
195 254
 
196  
-When we have a successful response, the context of the callback function will shift to a metaData object. The metaData object contains all information that we used to generate the request for the Memcached server. The metaData object contains the following properties:
  255
+When we have a successful response, the context of the callback function will
  256
+shift to a metaData object. The metaData object contains all information that we
  257
+used to generate the request for the Memcached server. The metaData object
  258
+contains the following properties:
197 259
 
198 260
 * `start`: Date in milliseconds when the request was received 
199 261
 * `execution`: Total execution time for the request, including response parsing.
@@ -202,35 +264,48 @@ When we have a successful response, the context of the callback function will sh
202 264
 * `command`: The compiled command that was send through the sockets
203 265
 * `validate`: The properties of metaData object that needs type validation.
204 266
 
205  
-And all the arguments you have send to the method, this depends on the method you have called. 
206  
-	
  267
+And all the arguments you have send to the method, this depends on the method
  268
+you have called. 
  269
+  
207 270
 ## Events
208 271
 
209  
-When connection issues occur we send out different notifications using the `EventEmitter` protocol. This can be useful for logging, notification and debugging purposes. Each event will receive details Object containing detailed information about the issues that occurred. 
  272
+When connection issues occur we send out different notifications using the
  273
+`EventEmitter` protocol. This can be useful for logging, notification and
  274
+debugging purposes. Each event will receive details Object containing detailed
  275
+information about the issues that occurred. 
210 276
 
211 277
 ### Details Object
212 278
 
213  
-The details Object contains the various of error messages that caused, the following 3 will always be present in all error events:
  279
+The details Object contains the various of error messages that caused, the
  280
+following 3 will always be present in all error events:
214 281
 
215 282
 * `server`: the server where the issue occurred on
216 283
 * `tokens`: a array of the parsed server string in `[port, hostname]` format.
217  
-* `messages`: a array containing all error messages that this server received. As messages are added to the array using .push(), the first issue will at the beginning and the latest error at the end of the array.
  284
+* `messages`: a array containing all error messages that this server received.
  285
+  As messages are added to the array using .push(), the first issue will at the
  286
+  beginning and the latest error at the end of the array.
218 287
 
219  
-The following properties depend on the type of event that is send. If we are still in our retry phase the details will also contain:
  288
+The following properties depend on the type of event that is send. If we are
  289
+still in our retry phase the details will also contain:
220 290
 
221 291
 * `retries`: the amount of retries left before we mark the server as dead.
222  
-* `totalRetries`: the total amount of retries we did on this server, as when the server has been reconnected after it's dead the `retries` will be rest to defaults and messages will be removed.
  292
+* `totalRetries`: the total amount of retries we did on this server, as when the
  293
+  server has been reconnected after it's dead the `retries` will be rest to
  294
+  defaults and messages will be removed.
223 295
 
224 296
 If the server is dead these details will be added:
225 297
 
226  
-* `totalReconnectsAttempted`: the total reconnects we have attempted. This is the success and failure combined.
  298
+* `totalReconnectsAttempted`: the total reconnects we have attempted. This is
  299
+the success and failure combined.
227 300
 * `totalReconnectsSuccess`: the total successful reconnects we have made.
228 301
 * `totalReconnectsFailed`: the total failed reconnects we have made.
229  
-* `totalDownTime`: the total down time that was generated. Formula: ( totalReconnectsFailed * reconnect_timeout ) + ( totalRetries * retry_timeout).
  302
+* `totalDownTime`: the total down time that was generated. Formula: (
  303
+  totalReconnectsFailed * reconnect_timeout ) + ( totalRetries * retry_timeout).
230 304
 
231 305
 ### Events
232 306
 
233  
-There are `5` different events that the `memcached` client emits when connection issues occur. 
  307
+There are `5` different events that the `memcached` client emits when connection
  308
+issues occur. 
234 309
 
235 310
 * `issue`: a issue occurred on one a server, we are going to attempt a retry next.
236 311
 * `failure`: a server has been marked as failure or dead.
@@ -240,7 +315,7 @@ There are `5` different events that the `memcached` client emits when connection
240 315
 
241 316
 Example implementations:
242 317
 
243  
-``` js
  318
+```js
244 319
 var memcached = new Memcached([ '192.168.0.102:11212', '192.168.0.103:11212' ]);
245 320
 memcached.on('failure', function( details ){ sys.error( "Server " + details.server + "went down due to: " + details.messages.join( '' ) ) });
246 321
 memcached.on('reconnecting', function( details ){ sys.debug( "Total downtime caused by server " + details.server + " :" + details.totalDownTime + "ms")});

0 notes on commit 24f2b75

Please sign in to comment.
Something went wrong with that request. Please try again.