memcached

An interface to the libmemcached C client.

== License

Copyright 2008 Cloudburst, LLC. Licensed under the AFL 3. See the included LICENSE file. Portions copyright 2008 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 like 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. Both libraries are very new; use caution.

== Installation

You need {libmemcached 0.15}[http://tangent.org/552/libmemcached.html]. Other versions of libmemcached are not supported. You also need {memcached itself}[http://www.danga.com/memcached/] if you want to test against a local server.

Download and extract the {libmemcached tarball}[http://download.tangent.org/libmemcached-0.15.tar.gz]. Then for Linux, run:
  ./configure
  make && sudo make install
  
For OS X/MacPorts, run:
  ./configure --prefix=/opt/local
  make && sudo make install
  
Now install the gem:
  sudo gem install memcached --no-rdoc --no-ri
  
== Usage

Start a local 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("127.0.0.1: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.get ['test', 'test2'] #=> ["hello", Memcached::NotFound]
  
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. 

The easiest way to use it in your app is by installing Interlock[http://blog.evanweaver.com/files/doc/fauna/interlock] and setting <tt>client: memcached</tt> in <tt>config/memcached.yml</tt>. This gives you memcached fragments by default. You do not have to use the other Interlock features unless you want to.
  
== 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 much, much faster than <b>memcache-client</b>:

                                       user     system      total        real
  set:ruby:noblock:memcached       0.050000   0.000000   0.050000 (  0.054205)
  set:ruby:memcached               0.130000   0.160000   0.290000 (  0.338529)
  set:ruby:memcache-client         3.690000   0.130000   3.820000 (  4.030806)
  ...
  get:ruby:memcached               0.110000   0.020000   0.130000 (  0.316446)
  get:ruby:memcache-client         3.730000   0.120000   3.850000 (  4.040446)
  ...
  missing:ruby:memcached           0.160000   0.090000   0.250000 (  0.401891)
  missing:ruby:memcache-client     3.650000   0.090000   3.740000 (  3.880192)
  ...
  mixed:ruby:noblock:memcached     0.190000   0.230000   0.420000 (  0.667130)
  mixed:ruby:memcached             0.250000   0.250000   0.500000 (  0.663093)
  mixed:ruby:memcache-client       7.410000   0.210000   7.620000 (  7.942145)

These benchmarks were run on x86-64 Linux. You can easily run your own benchmarks, as long as you have memcached itself on your system:
  $ ruby -e 'system("ruby #{File.dirname(`gem which memcached`.split("\n").
    last)}/../test/benchmark/benchmark.rb")'

== 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]