Find file
Fetching contributors…
Cannot retrieve contributors at this time
112 lines (70 sloc) 3.59 KB
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[].
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 pipelined IO with no_reply
The <b>memcached</b> library wraps the pure-C libmemcached client via SWIG.
== Installation
You need Ruby 1.8.7 or Ruby 1.9.2. 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 ="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
$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 = do
cache = $cache.clone
# Perform operations on cache, not $cache
cache.set 'example', 1
cache.get 'example'
# Join the thread so that exceptions don't get lost
== Benchmarks
<b>memcached</b>, correctly configured, is up to 60x faster than <b>memcache-client</b> or <b>dalli</b>. See BENCHMARKS[link:files/BENCHMARKS.html] 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.
== Further resources
* {Memcached wiki}[]
* {Libmemcached homepage}[]