1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
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 }
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>
31 <div style="margin:15px;margin-left:20px;">
33 <br> <br><h3><a name=abstract class=none>Abstract</a></h3>
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 :
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.
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.
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.
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.
52 <br><br><p>Here are some sample performance statistics of CL-MEMCACHED and other memcached clients :
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>
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.
65 <p><font color=red>Download shortcut:</font> <a href="cl-memcached-latest.tar.gz">cl-memcached-latest.tar.gz</a>.
68 <br><br> <br><h3><a class=none name="lists">Lists</a></h3>
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>.
73 <br> <br><h3><a class=none name="example_usage">Example Usage</a></h3>
77 CL-USER> (asdf:oos 'asdf:load-op :cl-memcached)
79 CL-USER> (setf *my-cache* (cl-memcached:mc-make-memcache-instance :ip "127.0.0.1" :name "My test cache"))
80 #<CL-MEMCACHED:MEMCACHE My test cache on 127.0.0.1:11211 SIZE:64Mb>
82 CL-USER> (cl-memcached:mc-store "test-key" "This is Test-DATA" :memcache *my-cache* :use-pool t)
85 CL-USER> (cl-memcached:mc-get+ "test-key" :memcache *my-cache* :use-pool t)
88 CL-USER> (cl-memcached:mc-get '("test-key") :memcache *my-cache* :use-pool t)
90 #(84 104 105 115 32 105 115 32 84 101 115 116 45 68 65 84 65)))
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"))
95 CL-USER> (cl-memcached:mc-store "test-key-2" "This is Test-DATA Again" :memcache *my-cache* :use-pool t)
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"))
105 <br> <br><h3><a class=none name="contents">Contents</a></h3>
107 <li><a href="#download">Download</a>
108 <li><a href="#dictionary">The CL-MEMCACHED dictionary</a>
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>
125 <li><a href="#ack">Acknowledgements</a>
128 <br> <br><h3><a class=none name="download">Download</a></h3>
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)
134 <br> <br><h3><a class=none name="dictionary">The CL-MEMCACHED dictionary</a></h3>
138 <!-- Entry for *MEMCACHE* -->
140 <p><br>[Special variable]<br><a class=none name='*memcache*'><b>*memcache*</b></a>
143 We can set the current memcache instance to this if there is only one in use.
147 <!-- End of entry for *MEMCACHE* -->
150 <!-- Entry for *USE-POOL* -->
152 <p><br>[Special variable]<br><a class=none name='*use-pool*'><b>*use-pool*</b></a>
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.
158 Default value for the USE-POOL is <i>nil</i>, which means a new connection is make every request.
162 <!-- End of entry for *USE-POOL* -->
164 <!-- Entry for *POOL-GET-TRYS?* -->
166 <p><br>[Special variable]<br><a class=none name='*pool-get-trys?'><b>*pool-get-trys?*</b></a>
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.
173 The default value is nil which is the a) approach.
177 <!-- End of entry for *POOL-GET-TRYS?* -->
180 <!-- Entry for MC-STORE -->
182 <p><br>[Function]<br><a class=none name='mc-store'><b>mc-store</b> <i>key data <tt>&key</tt> memcache command timeout use-pool</i> => <i>result</i></a>
185 Stores data in the memcached server.
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 & replace.
192 <i>timeout</i> - The time in seconds when this data expires. 0 is never expire.
196 <!-- End of entry for MC-STORE -->
199 <!-- Entry for MC-GET -->
201 <p><br>[Function]<br><a class=none name='mc-get'><b>mc-get</b> <i>keys-list <tt>&key</tt> memcache use-pool is-string</i> => <i>result</i></a>
204 Retrive value for key from memcached server.
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.
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)
215 <!-- End of entry for MC-GET -->
218 <!-- Entry for MC-GET+ -->
220 <p><br>[Function]<br><a class=none name='mc-get+'><b>mc-get+</b> <i>key-or-list-of-keys <tt>&key</tt> memcache use-pool</i> => <i>result</i></a>
223 To be used for non-binary data only. If one key is given
224 returns the response in string format
228 <!-- End of entry for MC-GET+ -->
232 <!-- Entry for MC-DECR -->
234 <p><br>[Function]<br><a class=none name='mc-decr'><b>mc-decr</b> <i>key <tt>&key</tt> memcache value use-pool</i> => <i>result</i></a>
237 Implements the DECR command. Decrements the value of a key. Please read memcached documentation for more information
241 <!-- End of entry for MC-DECR -->
244 <!-- Entry for MC-DEL -->
246 <p><br>[Function]<br><a class=none name='mc-del'><b>mc-del</b> <i>key <tt>&key</tt> memcache time use-pool</i> => <i>result</i></a>
249 Deletes a particular 'key' and it's associated data from the memcached server
253 <!-- End of entry for MC-DEL -->
257 <!-- Entry for MC-INCR -->
259 <p><br>[Function]<br><a class=none name='mc-incr'><b>mc-incr</b> <i>key <tt>&key</tt> memcache value use-pool</i> => <i>result</i></a>
262 Implements the INCR command. Increments the value of a key. Please read memcached documentation for more information
266 <!-- End of entry for MC-INCR -->
269 <!-- Entry for MC-MAKE-MEMCACHE-INSTANCE -->
271 <p><br>[Function]<br><a class=none name='mc-make-memcache-instance'><b>mc-make-memcache-instance</b> <i><tt>&key</tt> ip port name pool-size</i> => <i>result</i></a>
274 Creates an instance of class MEMCACHE which represents a memcached server
278 <!-- End of entry for MC-MAKE-MEMCACHE-INSTANCE -->
281 <!-- Entry for MC-POOL-INIT -->
283 <p><br>[Function]<br><a class=none name='mc-pool-init'><b>mc-pool-init</b> <i><tt>&key</tt> memcache</i> => <i>result</i></a>
286 Cleans up the pool for this particular instance of memcache
287 & reinits it with POOL-SIZE number of objects required by this pool
291 <!-- End of entry for MC-POOL-INIT -->
294 <!-- Entry for MC-SERVER-CHECK -->
296 <p><br>[Function]<br><a class=none name='mc-server-check'><b>mc-server-check</b> <i><tt>&key</tt> memcache</i> => <i>result</i></a>
299 Performs some basic tests on the Memcache instance and outputs a status string
303 <!-- End of entry for MC-SERVER-CHECK -->
306 <!-- Entry for MC-STATS -->
308 <p><br>[Function]<br><a class=none name='mc-stats'><b>mc-stats</b> <i><tt>&key</tt> memcache use-pool</i> => <i>result</i></a>
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.
317 <!-- End of entry for MC-STATS -->
319 <!-- Entry for MEMCACHED-STATS -->
321 <p><br>[Structure]<br><a class=none name='memcache-stats'><b>memcache-stats</b></a>
323 The structure which holds the statistics from the memcached server. The fields are :
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.
350 <!-- End of entry for MC-STATS -->
354 <!-- Entry for MEMCACHE -->
356 <p><br>[Standard class]<br><a class=none name='memcache'><b>memcache</b></a>
359 This class represents an instance of the Memcached server
362 (defclass memcache ()
367 :documentation "Name of this Memcache instance")
370 :initform "127.0.0.1"
373 :documentation "The IP address of the Memcached server this instance represents")
379 :documentation "The port on which the Memcached server this instance represents runs")
380 (memcached-server-storage-size
382 :reader memcached-server-storage-size
384 :documentation "Memory allocated to the Memcached Server")
391 (:documentation "This class represents an instance of the Memcached server"))
396 <!-- End of entry for MEMCACHE -->
399 <br> <br><h3><a class=none name="known_isues">Known Issues</a></h3>
401 The pooling functionality is still experimental. This is mainly because strategies to deal with network errors are not in place.
403 <br> <br><h3><a class=none name="todo">TODO</a></h3>
405 <br>- Add facility to created a replicated memcached pair.
406 <br>- Support for a memcached cluster (distributedness)
410 <p>Abhijit 'quasi' Rao
414 <br> <br><h3><a class=none name="ack">Acknowledgements</a></h3>
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.
419 <P>This documentation was prepared with the help of <a href="http://weitz.de/documentation-template/">DOCUMENTATION-TEMPLATE</a>.