зеркало из https://github.com/github/memcached.git
140 строки
5.2 KiB
Plaintext
140 строки
5.2 KiB
Plaintext
|
|
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]
|