Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
A Ruby interface to the libmemcached C client
Shell C Ruby Perl C++ Objective-C

Fetching latest commit…

Cannot retrieve the latest commit at this time

Failed to load latest commit information.
ext
lib
test
.gitignore
.gitmodules
BENCHMARKS
CHANGELOG
LICENSE
Manifest
README
Rakefile
TODO

README

memcached

An interface to the libmemcached C client.

== License

Copyright 2009-2011 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.

== 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 = 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. Note that you must initialize it with an integer, encoded as an unmarshalled ASCII string:

  start = 1
  $cache.set 'counter', start.to_s, 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

== Pipelining

Pipelining updates is extremely effective in <b>memcached</b>, leading to more than 25x write throughput than the default settings. Use the following options to enable it:

  :no_block => true,
  :buffer_requests => true,
  :noreply => true,
  :binary_protocol => false

Currently #append, #prepend, #set, and #delete are pipelined. Note that when you perform a read, all pending writes are flushed to the servers.

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

== Legacy applications

There is a compatibility wrapper for legacy applications called Memcached::Rails.

== Benchmarks

<b>memcached</b>, correctly configured, is at least twice as fast as <b>memcache-client</b> and <b>dalli</b>. See BENCHMARKS[link:files/BENCHMARKS.html] for details.

== Reporting problems

The support forum is here[http://github.com/fauna/memcached/issues].

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]
Something went wrong with that request. Please try again.