memcache/doc/cl-memcached.html

   1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
   2 <html>
   3
   4 <head>
   5   <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
   6   <title>CL-MEMCACHED</title>
   7   <style type="text/css">
   8   body {font-family:'monaco','verdana','monospace'; font-size:12px; margin-left:0px; margin-right:0px;margin-top:0px;}
   9   pre { padding: 5px; font-family:'courier new','monospace';}
  10   .code { padding:5px; background-color:#f0f0f0; font-family:'courier', 'monospace'; font-size:9pt;}
  11   blockquote { font-family:'courier new', 'monospace', 'verdana'; font-size:10pt;}
  12   h3, h4 { text-decoration: underline; }
  13   a { text-decoration: none; }
  14   a.noborder { border:0px }
  15   a.noborder:hover { border:0px }  a.none { border:1px solid white; }
  16   a.none { border:1px solid white; }
  17   a.none:hover { border:1px solid white; }
  18   a { border:1px solid white; }
  19   a:hover   { border: 1px solid black; }
  20   a.noborder { border:0px }
  21   a.noborder:hover { border:0px }
  22   </style>
  23 </head>
  24
  25 <body bgcolor=white>
  26
  27 <div style="border:solid blue 0px;padding: 25px;background-color:pink; border-bottom:solid red 2px;">
  28 <h2>CL-MEMCACHED <small>- Common Lisp interface to the memcached object caching system.</small></h2>
  29 </div>
  30
  31 <div style="margin:15px;margin-left:20px;">
  32
  33 <br>&nbsp;<br><h3><a name=abstract class=none>Abstract</a></h3>
  34
  35 <p>CL-MEMCACHED is a library to interface with the <a href="http://www.danga.com/memcached/" >memcached</a> object caching system.
  36 <p><i>What is Memcached??</i> According to the home page :
  37 <blockquote>
  38
  39 <a href="http://www.danga.com/memcached/" >memcached</a> is a high-performance, distributed memory object caching system, generic in nature, but intended for use in speeding up dynamic web applications by alleviating database load.
  40
  41 <br><br>
  42
  43 <a href="http://www.danga.com/" >Danga</a> Interactive developed memcached to enhance the speed of <a href="http://livejournal.com" >LiveJournal.com</a>, a site which was already doing 20 million+ dynamic page views per day for 1 million users with a bunch of webservers and a bunch of database servers. memcached dropped the database load to almost nothing, yielding faster page load times for users, better resource utilization, and faster access to the databases on a memcache miss.
  44 </blockquote>
  45
  46 <p>CL-MEMCACHED implements most of the memcached <a href="http://code.sixapart.com/svn/memcached/trunk/server/doc/protocol.txt" >protocol</a>.  The code has been tested on Allegro CL and does not work on other Lisp's right now.  See file compat.lisp to help.
  47
  48 <p>We have used memcached (1.1.2) in production for over 20 months and have found it to give excellent performance and good stability.  The CL-MEMCACHED has evolved over this period of time from a hack to it's current state.  Our memcached servers have been up for over 60 days at a time having served over a terabyte of data to the network in this period.
  49
  50
  51
  52 <br><br><p>Here are some sample performance statistics of CL-MEMCACHED and other memcached clients :
  53 <br>
  54 <table border=1 style="font-size:9pt;text-align:right;" cellpadding='10px'>
  55   <tr><th>client</th><th>lang implementation</th><th>10,000 writes<br>1K data (in msec)</th><th>10,000 reads<br>1K data (in msec)</th><th>10,000 writes<br>10K data (in msec)</th><th>10,000 reads<br>10K data (in msec)</th></tr>
  56   <tr><td>cl-memcached</td><td>Allegro 8.0 (AMD64)</td><td>950</td><td>830</td><td>2,130</td><td>1,330</td></tr>
  57   <tr><td>memcached-client-1.2.0</td><td>ruby 1.8.5</td><td>727</td><td>874</td><td>1,129</td><td>1,296</td></tr>
  58   <tr><td>python-memcached-1.36</td><td>python 2.5.1</td><td>892</td><td>951</td><td>1,092</td><td>1,259</td></tr>
  59   <tr><td>php-memcached-2.1.2</td><td>php 4.3.9</td><td>507</td><td>513</td><td>400,000</td><td>660</td></tr>
  60 </table>
  61
  62 <br>
  63 <p>The code comes with a <a href="http://www.opensource.org/licenses/bsd-license.php">BSD-style license</a> so you can basically do with it whatever you want.
  64
  65 <p><font color=red>Download shortcut:</font> <a href="cl-memcached-latest.tar.gz">cl-memcached-latest.tar.gz</a>.
  66
  67
  68 <br><br>&nbsp;<br><h3><a class=none name="lists">Lists</a></h3>
  69
  70 <br>The devel mailing list is <a href="http://common-lisp.net/mailman/listinfo/cl-memcached-devel" >cl-memcached-devel</a>.
  71 <br>The announce mailing list is <a href="http://common-lisp.net/mailman/listinfo/cl-memcached-announce" >cl-memcached-announce</a>.
  72
  73 <br>&nbsp;<br><h3><a class=none name="example_usage">Example Usage</a></h3>
  74
  75 <p>quick start
  76 <pre class='code'>
  77 CL-USER> (asdf:oos 'asdf:load-op :cl-memcached)
  78
  79 CL-USER> (setf *my-cache* (cl-memcached:mc-make-memcache-instance :ip "127.0.0.1" :name "My test cache"))
  80 #&lt;CL-MEMCACHED:MEMCACHE My test cache on 127.0.0.1:11211 SIZE:64Mb&gt;
  81
  82 CL-USER> (cl-memcached:mc-store "test-key" "This is Test-DATA" :memcache *my-cache* :use-pool t)
  83 "STORED"
  84
  85 CL-USER> (cl-memcached:mc-get+ "test-key" :memcache *my-cache* :use-pool t)
  86 "This is Test-DATA"
  87
  88 CL-USER> (cl-memcached:mc-get '("test-key") :memcache *my-cache* :use-pool t)
  89 (("test-key"
  90   #(84 104 105 115 32 105 115 32 84 101 115 116 45 68 65 84 65)))
  91
  92 CL-USER> (cl-memcached:mc-get '("test-key") :memcache *my-cache* :use-pool t :is-string t)
  93 (("test-key" "This is Test-DATA"))
  94
  95 CL-USER> (cl-memcached:mc-store "test-key-2" "This is Test-DATA Again" :memcache *my-cache* :use-pool t)
  96 "STORED"
  97
  98 CL-USER> (cl-memcached:mc-get '("test-key" "test-key-2") :memcache *my-cache* :use-pool t :is-string t)
  99 (("test-key" "This is Test-DATA")
 100  ("test-key-2" "This is Test-DATA Again"))
 101
 102 </pre>
 103
 104
 105 <br>&nbsp;<br><h3><a class=none name="contents">Contents</a></h3>
 106 <ol>
 107   <li><a href="#download">Download</a>
 108   <li><a href="#dictionary">The CL-MEMCACHED dictionary</a>
 109     <ol>
 110       <li><a href="#*memcache*"><code>*memcache*</code></a>
 111       <li><a href="#*use-pool*"><code>*use-pool*</code></a>
 112       <li><a href="#*pool-get-trys?*"><code>*pool-get-trys?*</code></a>
 113       <li><a href="#mc-decr"><code>mc-decr</code></a>
 114       <li><a href="#mc-del"><code>mc-del</code></a>
 115       <li><a href="#mc-get"><code>mc-get</code></a>
 116       <li><a href="#mc-get+"><code>mc-get+</code></a>
 117       <li><a href="#mc-incr"><code>mc-incr</code></a>
 118       <li><a href="#mc-make-memcache-instance"><code>mc-make-memcache-instance</code></a>
 119       <li><a href="#mc-pool-init"><code>mc-pool-init</code></a>
 120       <li><a href="#mc-server-check"><code>mc-server-check</code></a>
 121       <li><a href="#mc-stats"><code>mc-stats</code></a>
 122       <li><a href="#mc-store"><code>mc-store</code></a>
 123       <li><a href="#memcache"><code>memcache</code></a>
 124     </ol>
 125   <li><a href="#ack">Acknowledgements</a>
 126 </ol>
 127
 128 <br>&nbsp;<br><h3><a class=none name="download">Download</a></h3>
 129
 130 CL-MEMCACHED together with this documentation can be downloaded from <a
 131 href="cl-memcached-latest.tar.gz">cl-memcached-latest.tar.gz</a>. The
 132 current version is 0.4.1. (I will be setting up a SVN repo soon)
 133
 134 <br>&nbsp;<br><h3><a class=none name="dictionary">The CL-MEMCACHED dictionary</a></h3>
 135
 136
 137
 138 <!-- Entry for *MEMCACHE* -->
 139
 140 <p><br>[Special variable]<br><a class=none name='*memcache*'><b>*memcache*</b></a>
 141 <blockquote><br>
 142
 143 We can set the current memcache instance to this if there is only one in use.
 144
 145 </blockquote>
 146
 147 <!-- End of entry for *MEMCACHE* -->
 148
 149
 150 <!-- Entry for *USE-POOL* -->
 151
 152 <p><br>[Special variable]<br><a class=none name='*use-pool*'><b>*use-pool*</b></a>
 153 <blockquote><br>
 154 <pre>
 155 This controls if we use the connection pool by default. One can set it at each call level, but it is also
 156 possible to set this global policy.
 157
 158 Default value for the USE-POOL is <i>nil</i>, which means a new connection is make every request.
 159 </pre>
 160 </blockquote>
 161
 162 <!-- End of entry for *USE-POOL* -->
 163
 164 <!-- Entry for *POOL-GET-TRYS?* -->
 165
 166 <p><br>[Special variable]<br><a class=none name='*pool-get-trys?'><b>*pool-get-trys?*</b></a>
 167 <blockquote><br>
 168 <pre>
 169 This controls the policy for the fetching connectors from the pool.  There are two approaches :
 170 a) where we throw an error if pool is empty
 171 b) where we sleep an try again to see if one is available.
 172
 173 The default value is nil which is the a) approach.
 174 </pre>
 175 </blockquote>
 176
 177 <!-- End of entry for *POOL-GET-TRYS?* -->
 178
 179
 180 <!-- Entry for MC-STORE -->
 181
 182 <p><br>[Function]<br><a class=none name='mc-store'><b>mc-store</b> <i>key data <tt>&amp;key</tt> memcache command timeout use-pool</i> =&gt; <i>result</i></a>
 183 <blockquote><br>
 184
 185 Stores data in the memcached server.
 186
 187 <pre><i>key</i> - key by which the data is stored. this is of type SIMPLE-STRING
 188 <i>data</i> - data to be stored into the cache. data is a sequence of type (UNSIGNED-BYTE 8)
 189 <i>length</i> - size of data
 190 <i>memcache</i> - The instance of class memcache which represnts the memcached we want to use.
 191 <i>command</i> - The storage command we want to use.  There are 3 available : set, add &amp; replace.
 192 <i>timeout</i> - The time in seconds when this data expires.  0 is never expire.
 193 </pre>
 194 </blockquote>
 195
 196 <!-- End of entry for MC-STORE -->
 197
 198
 199 <!-- Entry for MC-GET -->
 200
 201 <p><br>[Function]<br><a class=none name='mc-get'><b>mc-get</b> <i>keys-list <tt>&amp;key</tt> memcache use-pool is-string</i> =&gt; <i>result</i></a>
 202 <blockquote><br>
 203
 204 Retrive value for key from memcached server.
 205 <pre>
 206 <i>keys-list</i> - is a list of the keys, seperated by whitespace, by which data is stored in memcached
 207 <i>memcache</i> - The instance of class memcache which represnts the memcached we want to use.
 208
 209 Returns a list of lists where each list has two elements key and value
 210 <i>key</i> - is of type SIMPLE-STRING
 211 <i>value</i> is of type (UNSIGNED-BYTE 8)
 212 </pre>
 213 </blockquote>
 214
 215 <!-- End of entry for MC-GET -->
 216
 217
 218 <!-- Entry for MC-GET+ -->
 219
 220 <p><br>[Function]<br><a class=none name='mc-get+'><b>mc-get+</b> <i>key-or-list-of-keys <tt>&amp;key</tt> memcache use-pool</i> =&gt; <i>result</i></a>
 221 <blockquote><br>
 222
 223 To be used for non-binary data only. If one key is given
 224 returns the response in string format
 225
 226 </blockquote>
 227
 228 <!-- End of entry for MC-GET+ -->
 229
 230
 231
 232 <!-- Entry for MC-DECR -->
 233
 234 <p><br>[Function]<br><a class=none name='mc-decr'><b>mc-decr</b> <i>key <tt>&amp;key</tt> memcache value use-pool</i> =&gt; <i>result</i></a>
 235 <blockquote><br>
 236
 237 Implements the DECR command.  Decrements the value of a key. Please read memcached documentation for more information
 238
 239 </blockquote>
 240
 241 <!-- End of entry for MC-DECR -->
 242
 243
 244 <!-- Entry for MC-DEL -->
 245
 246 <p><br>[Function]<br><a class=none name='mc-del'><b>mc-del</b> <i>key <tt>&amp;key</tt> memcache time use-pool</i> =&gt; <i>result</i></a>
 247 <blockquote><br>
 248
 249 Deletes a particular &#039;key&#039; and it&#039;s associated data from the memcached server
 250
 251 </blockquote>
 252
 253 <!-- End of entry for MC-DEL -->
 254
 255
 256
 257 <!-- Entry for MC-INCR -->
 258
 259 <p><br>[Function]<br><a class=none name='mc-incr'><b>mc-incr</b> <i>key <tt>&amp;key</tt> memcache value use-pool</i> =&gt; <i>result</i></a>
 260 <blockquote><br>
 261
 262 Implements the INCR command.  Increments the value of a key. Please read memcached documentation for more information
 263
 264 </blockquote>
 265
 266 <!-- End of entry for MC-INCR -->
 267
 268
 269 <!-- Entry for MC-MAKE-MEMCACHE-INSTANCE -->
 270
 271 <p><br>[Function]<br><a class=none name='mc-make-memcache-instance'><b>mc-make-memcache-instance</b> <i><tt>&amp;key</tt> ip port name pool-size</i> =&gt; <i>result</i></a>
 272 <blockquote><br>
 273
 274 Creates an instance of class MEMCACHE which represents a memcached server
 275
 276 </blockquote>
 277
 278 <!-- End of entry for MC-MAKE-MEMCACHE-INSTANCE -->
 279
 280
 281 <!-- Entry for MC-POOL-INIT -->
 282
 283 <p><br>[Function]<br><a class=none name='mc-pool-init'><b>mc-pool-init</b> <i><tt>&amp;key</tt> memcache</i> =&gt; <i>result</i></a>
 284 <blockquote><br>
 285
 286 Cleans up the pool for this particular instance of memcache
 287 &amp; reinits it with POOL-SIZE number of objects required by this pool
 288
 289 </blockquote>
 290
 291 <!-- End of entry for MC-POOL-INIT -->
 292
 293
 294 <!-- Entry for MC-SERVER-CHECK -->
 295
 296 <p><br>[Function]<br><a class=none name='mc-server-check'><b>mc-server-check</b> <i><tt>&amp;key</tt> memcache</i> =&gt; <i>result</i></a>
 297 <blockquote><br>
 298
 299 Performs some basic tests on the Memcache instance and outputs a status string
 300
 301 </blockquote>
 302
 303 <!-- End of entry for MC-SERVER-CHECK -->
 304
 305
 306 <!-- Entry for MC-STATS -->
 307
 308 <p><br>[Function]<br><a class=none name='mc-stats'><b>mc-stats</b> <i><tt>&amp;key</tt> memcache use-pool</i> =&gt; <i>result</i></a>
 309 <blockquote><br>
 310
 311 Returns a struct of type memcache-stats which contains internal statistics from the
 312 memcached server instance.  Please refer to documentation of <a href="#memcache-stats" >memcache-stats</a> for detailed
 313 information about each slot.
 314
 315 </blockquote>
 316
 317 <!-- End of entry for MC-STATS -->
 318
 319 <!-- Entry for MEMCACHED-STATS -->
 320
 321 <p><br>[Structure]<br><a class=none name='memcache-stats'><b>memcache-stats</b></a>
 322 <blockquote><br>
 323 The structure which holds the statistics from the memcached server. The fields are :
 324 <pre>
 325 field-name                 accessor-function                 documentation
 326 ----------                 -----------------                 -------------
 327 pid                        mc-stats-pid                      Process id of this server process
 328 uptime                     mc-stats-uptime                   Number of seconds this server has been running
 329 time                       mc-stats-time                     current UNIX time according to the server
 330 version                    mc-stats-version                  Version string of this server
 331 rusage-user                mc-stats-rusage-user              Accumulated user time for this process
 332 rusage-system              mc-stats-rusage-system            Accumulated system time for this process
 333 curr-items                 mc-stats-curr-items               Current number of items stored by the server
 334 total-items                mc-stats-total-items              Total number of items stored by this server ever since it started
 335 bytes                      mc-stats-bytes                    Current number of bytes used by this server to store items
 336 curr-connections           mc-stats-curr-connections         Number of open connections
 337 total-connections          mc-stats-total-connections        Total number of connections opened since the server started running
 338 connection-structures      mc-stats-connection-structures    Number of connection structures allocated by the server
 339 cmd-get                    mc-stats-cmd-get                  Cumulative number of retrieval requests
 340 cmd-set                    mc-stats-cmd-set                  Cumulative number of storage requests
 341 get-hits                   mc-stats-get-hits                 Number of keys that have been requested and found present
 342 get-misses                 mc-stats-get-misses               Number of items that have been requested and not found
 343 evictions                  mc-stats-evictions                Number of items removed from cache because they passed their expiration time
 344 bytes-read                 mc-stats-bytes-read               Total number of bytes read by this server from network
 345 bytes-written              mc-stats-bytes-written            Total number of bytes sent by this server to network
 346 limit-maxbytes             mc-stats-limit-maxbytes           Number of bytes this server is allowed to use for storage.
 347 </pre>
 348 </blockquote>
 349
 350 <!-- End of entry for MC-STATS -->
 351
 352
 353
 354 <!-- Entry for MEMCACHE -->
 355
 356 <p><br>[Standard class]<br><a class=none name='memcache'><b>memcache</b></a>
 357 <blockquote><br>
 358
 359 This class represents an instance of the Memcached server
 360
 361 <pre class='code'>
 362 (defclass memcache ()
 363   ((name
 364     :initarg :name
 365     :reader name
 366     :type simple-string
 367     :documentation "Name of this Memcache instance")
 368    (ip
 369     :initarg :ip
 370     :initform "127.0.0.1"
 371     :accessor ip
 372     :type simple-string
 373     :documentation "The IP address of the Memcached server this instance represents")
 374    (port
 375     :initarg :port
 376     :initform 11211
 377     :accessor port
 378     :type fixnum
 379     :documentation "The port on which the Memcached server this instance represents runs")
 380    (memcached-server-storage-size
 381     :initform 0
 382     :reader memcached-server-storage-size
 383     :type fixnum
 384     :documentation "Memory allocated to the Memcached Server")
 385    (pool-size
 386     :initarg :pool-size
 387     :initform 2
 388     :reader pool-size)
 389    (pool
 390     :reader pool))
 391   (:documentation "This class represents an instance of the Memcached server"))
 392 </pre>
 393
 394 </blockquote>
 395
 396 <!-- End of entry for MEMCACHE -->
 397
 398
 399 <br>&nbsp;<br><h3><a class=none name="known_isues">Known Issues</a></h3>
 400
 401 The pooling functionality is still experimental. This is mainly because strategies to deal with network errors are not in place.
 402
 403 <br>&nbsp;<br><h3><a class=none name="todo">TODO</a></h3>
 404
 405 <br>- Add facility to created a replicated memcached pair.
 406 <br>- Support for a memcached cluster (distributedness)
 407
 408
 409 <br><h3>People</h3>
 410 <p>Abhijit 'quasi' Rao
 411 <p>Chaitanya Gupta
 412
 413
 414 <br>&nbsp;<br><h3><a class=none name="ack">Acknowledgements</a></h3>
 415
 416 <p>Thanks to Mr. <a href="http://blog.cleartrip.com/" >Hrush Bhatt</a> of <a href="http://www.cleartrip.com/" >Cleartrip</a> for allowing us to make this library available under a BSD licence.
 417
 418
 419 <P>This documentation was prepared with the help of <a href="http://weitz.de/documentation-template/">DOCUMENTATION-TEMPLATE</a>.
 420 </p>
 421 </div>
 422 </body>
 423 </html>