memcached
 
An interface to the libmemcached C client.
 
== License
 
Copyright 2009 Cloudburst, LLC. Licensed under the AFL 3. See the included LICENSE file. Portions copyright 2007-2009 TangentOrg, Brian Aker, licensed under the BSD license, and used with permission.
 
The public certificate for this gem is here[http://rubyforge.org/frs/download.php/25331/evan_weaver-original-public_cert.pem]. 
 
If you use this software, please {make a donation}[http://blog.evanweaver.com/donate/], or {recommend Evan}[http://www.workingwithrails.com/person/7739-evan-weaver] at Working with Rails.
 
== Features
 
* clean API
* robust access to all memcached features
* multiple hashing modes, including consistent hashing
* ludicrous speed, including optional non-blocking IO
 
The <b>memcached</b> library wraps the pure-C libmemcached client via SWIG.
 
== Installation
 
You need Ruby 1.8.7 or Ruby 1.9.1. Other versions may work, but are not guaranteed. You also need {memcached itself}[http://www.danga.com/memcached/] if you want to test against a local server.
 
Install the gem:
  sudo gem install memcached --no-rdoc --no-ri
  
== Usage
 
Start a local networked memcached server:
  $ memcached -p 11211 &
 
Now, in Ruby, require the library and instantiate a Memcached object at a global level:
 
  require 'memcached'
  $cache = Memcached.new("localhost:11211")
  
Now you can set things and get things:
 
  value = 'hello'
  $cache.set 'test', value
  $cache.get 'test' #=> "hello"
 
You can set with an expiration timeout:
 
  value = 'hello'
  $cache.set 'test', value, 1
  sleep(2)
  $cache.get 'test' #=> raises Memcached::NotFound
 
You can get multiple values at once:
 
  value = 'hello'
  $cache.set 'test', value
  $cache.set 'test2', value
  $cache.get ['test', 'test2', 'missing'] 
    #=> {"test" => "hello", "test2" => "hello"}
  
You can set a counter and increment it:
 
  start = 1
  $cache.set 'counter', start, 0, false
  $cache.increment 'counter' #=> 2
  $cache.increment 'counter' #=> 3
  $cache.get('counter', false).to_i #=> 3
 
You can get some server stats:
 
  $cache.stats #=> {..., :bytes_written=>[62], :version=>["1.2.4"] ...}
  
Note that the API is not the same as that of <b>Ruby-MemCache</b> or <b>memcache-client</b>. In particular, <tt>nil</tt> is a valid record value. Memcached#get does not return <tt>nil</tt> on failure, rather it raises <b>Memcached::NotFound</b>. This is consistent with the behavior of memcached itself. For example:
 
  $cache.set 'test', nil
  $cache.get 'test' #=> nil
  $cache.delete 'test'
  $cache.get 'test' #=> raises Memcached::NotFound
 
== Legacy applications
 
There is a compatibility wrapper for legacy applications called Memcached::Rails. 
 
== Threading
 
<b>memcached</b> is threadsafe, but each thread requires its own Memcached instance. Create a global Memcached, and then call Memcached#clone each time you spawn a thread.
 
  thread = Thread.new do
    cache = $cache.clone
    # Perform operations on cache, not $cache
    cache.set 'example', 1
    cache.get 'example'
  end  
 
  # Join the thread so that exceptions don't get lost
  thread.join
  
== Benchmarks
 
<b>memcached</b> is up to 10x faster than <b>memcache-client</b>. See BENCHMARKS[link:files/BENCHMARKS.html] for details.
 
== Reporting problems
 
The support forum is here[http://rubyforge.org/forum/forum.php?forum_id=20894].
 
Patches and contributions are very welcome. Please note that contributors are required to assign copyright for their additions to Cloudburst, LLC.
 
== Further resources
 
* {Memcached wiki}[http://www.socialtext.net/memcached/index.cgi]
* {Libmemcached homepage}[http://tangent.org/552/libmemcached.html]