memcached
An interface to the libmemcached C client.
Warning
This code is for testing of fixes intended for the mainline Fauna client. Only use it if you need fixes that are here and not in Fauna’s memcached 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.
If you use this software, please make a donation, or recommend Evan 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 memcached 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 the libsasl2-dev library, which should be provided through your system’s package manager.
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 Ruby-MemCache or memcache-client. In particular, nil
is a valid record value. Memcached#get does not return nil
on failure, rather it raises Memcached::NotFound. 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
memcached 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
memcached is up to 10x faster than memcache-client. See BENCHMARKS for details.
Reporting problems
The support forum is here.
Patches and contributions are very welcome. Please note that contributors are required to assign copyright for their additions to Cloudburst, LLC.