Class: MemCache
- Inherits:
-
Object
- Object
- MemCache
- Defined in:
- lib/memcache.rb
Overview
A Ruby client library for memcached.
This is intended to provide access to basic memcached functionality. It does not attempt to be complete implementation of the entire API, but it is approaching a complete implementation.
Defined Under Namespace
Classes: MemCacheError, Server
Constant Summary collapse
- VERSION =
The version of MemCache you are using.
'1.3.0'
- DEFAULT_OPTIONS =
Default options for the cache object.
{ :namespace => nil, :readonly => false, :multithread => false, }
- DEFAULT_PORT =
Default memcached port.
11211
- DEFAULT_WEIGHT =
Default memcached server weight.
1
Instance Attribute Summary collapse
-
#multithread ⇒ Object
readonly
The multithread setting for this instance.
-
#namespace ⇒ Object
readonly
The namespace for this instance.
-
#request_timeout ⇒ Object
The amount of time to wait for a response from a memcached server.
Instance Method Summary collapse
-
#[]=(key, value) ⇒ Object
Shortcut to save a value in the cache.
-
#active? ⇒ Boolean
Returns whether there is at least one active server for the object.
-
#cache_decr(server, cache_key, amount) ⇒ Object
Performs a raw decr for
cache_key
fromserver
. -
#cache_get(server, cache_key) ⇒ Object
Fetches the raw data for
cache_key
fromserver
. -
#cache_get_multi(server, cache_keys) ⇒ Object
Fetches
cache_keys
fromserver
using a multi-get. -
#cache_incr(server, cache_key, amount) ⇒ Object
Performs a raw incr for
cache_key
fromserver
. -
#decr(key, amount = 1) ⇒ Object
Deceremets the value for
key
byamount
and returns the new value. -
#delete(key, expiry = 0) ⇒ Object
Removes
key
from the cache inexpiry
seconds. -
#get(key, raw = false) ⇒ Object
(also: #[])
Retrieves
key
from memcache. -
#get_multi(*keys) ⇒ Object
Retrieves multiple values from memcached in parallel, if possible.
-
#get_server_for_key(key) ⇒ Object
Pick a server to handle the request based on a hash of the key.
-
#handle_error(server, error) ⇒ Object
Handles
error
fromserver
. -
#hash_for(key) ⇒ Object
Returns an interoperable hash value for
key
. -
#incr(key, amount = 1) ⇒ Object
Increments the value for
key
byamount
and retruns the new value. -
#initialize(*args) ⇒ MemCache
constructor
Accepts a list of
servers
and a list ofopts
. -
#inspect ⇒ Object
Returns a string representation of the cache object.
-
#make_cache_key(key) ⇒ Object
Create a key for the cache, incorporating the namespace qualifier if requested.
-
#readonly? ⇒ Boolean
Returns whether or not the cache object was created read only.
-
#request_setup(key) ⇒ Object
Performs setup for making a request with
key
from memcached. -
#reset ⇒ Object
Reset the connection to all memcache servers.
-
#servers=(servers) ⇒ Object
Set the servers that the requests will be distributed between.
-
#set(key, value, expiry = 0, raw = false) ⇒ Object
Add
key
to the cache with valuevalue
that expires inexpiry
seconds. -
#stats ⇒ Object
Returns statistics for each memcached server.
-
#threadsafe_cache_decr(server, cache_key, amount) ⇒ Object
:nodoc:.
-
#threadsafe_cache_get(server, cache_key) ⇒ Object
:nodoc:.
-
#threadsafe_cache_get_multi(socket, cache_key) ⇒ Object
:nodoc:.
-
#threadsafe_cache_incr(server, cache_key, amount) ⇒ Object
:nodoc:.
Constructor Details
#initialize(*args) ⇒ MemCache
Accepts a list of servers
and a list of opts
. servers
may be omitted. See servers=
for acceptable server list arguments.
Valid options for opts
are:
[:namespace] Prepends this value to all keys added or retrieved.
[:readonly] Raises an exeception on cache writes when true.
[:multithread] Wraps cache access in a Mutex for thread safety.
Other options are ignored.
95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 |
# File 'lib/memcache.rb', line 95 def initialize(*args) servers = [] opts = {} case args.length when 0 then # NOP when 1 then arg = args.shift case arg when Hash then opts = arg when Array then servers = arg when String then servers = [arg] else raise ArgumentError, 'first argument must be Array, Hash or String' end when 2 then servers, opts = args else raise ArgumentError, "wrong number of arguments (#{args.length} for 2)" end opts = DEFAULT_OPTIONS.merge opts @namespace = opts[:namespace] @readonly = opts[:readonly] @multithread = opts[:multithread] @mutex = Mutex.new if @multithread @buckets = [] self.servers = servers end |
Instance Attribute Details
#multithread ⇒ Object (readonly)
The multithread setting for this instance
81 82 83 |
# File 'lib/memcache.rb', line 81 def multithread @multithread end |
#namespace ⇒ Object (readonly)
The namespace for this instance
76 77 78 |
# File 'lib/memcache.rb', line 76 def namespace @namespace end |
#request_timeout ⇒ Object
The amount of time to wait for a response from a memcached server. If a response is not completed within this time, the connection to the server will be closed and an error will be raised.
71 72 73 |
# File 'lib/memcache.rb', line 71 def request_timeout @request_timeout end |
Instance Method Details
#[]=(key, value) ⇒ Object
Shortcut to save a value in the cache. This method does not set an expiration on the entry. Use set to specify an explicit expiry.
408 409 410 |
# File 'lib/memcache.rb', line 408 def []=(key, value) set key, value end |
#active? ⇒ Boolean
Returns whether there is at least one active server for the object.
135 136 137 |
# File 'lib/memcache.rb', line 135 def active? not @servers.empty? end |
#cache_decr(server, cache_key, amount) ⇒ Object
Performs a raw decr for cache_key
from server
. Returns nil if not found.
459 460 461 462 463 464 465 |
# File 'lib/memcache.rb', line 459 def cache_decr(server, cache_key, amount) socket = server.socket socket.write "decr #{cache_key} #{amount}\r\n" text = socket.gets return nil if text == "NOT_FOUND\r\n" return text.to_i end |
#cache_get(server, cache_key) ⇒ Object
Fetches the raw data for cache_key
from server
. Returns nil on cache miss.
471 472 473 474 475 476 477 478 479 480 481 482 483 484 485 |
# File 'lib/memcache.rb', line 471 def cache_get(server, cache_key) socket = server.socket socket.write "get #{cache_key}\r\n" keyline = socket.gets # "VALUE <key> <flags> <bytes>\r\n" return nil if keyline == "END\r\n" unless keyline =~ /(\d+)\r/ then server.close raise MemCacheError, "unexpected response #{keyline.inspect}" end value = socket.read $1.to_i socket.read 2 # "\r\n" socket.gets # "END\r\n" return value end |
#cache_get_multi(server, cache_keys) ⇒ Object
Fetches cache_keys
from server
using a multi-get.
490 491 492 493 494 495 496 497 498 499 500 501 502 503 504 505 506 507 |
# File 'lib/memcache.rb', line 490 def cache_get_multi(server, cache_keys) values = {} socket = server.socket socket.write "get #{cache_keys}\r\n" while keyline = socket.gets break if keyline == "END\r\n" unless keyline =~ /^VALUE (.+) (.+) (.+)/ then server.close raise MemCacheError, "unexpected response #{keyline.inspect}" end key, data_length = $1, $3 values[$1] = socket.read data_length.to_i socket.read(2) # "\r\n" end return values end |
#cache_incr(server, cache_key, amount) ⇒ Object
Performs a raw incr for cache_key
from server
. Returns nil if not found.
513 514 515 516 517 518 519 |
# File 'lib/memcache.rb', line 513 def cache_incr(server, cache_key, amount) socket = server.socket socket.write "incr #{cache_key} #{amount}\r\n" text = socket.gets return nil if text == "NOT_FOUND\r\n" return text.to_i end |
#decr(key, amount = 1) ⇒ Object
Deceremets the value for key
by amount
and returns the new value. key
must already exist. If key
is not an integer, it is assumed to be
-
key
can not be decremented below 0.
182 183 184 185 186 187 188 189 190 191 192 |
# File 'lib/memcache.rb', line 182 def decr(key, amount = 1) server, cache_key = request_setup key if @multithread then threadsafe_cache_decr server, cache_key, amount else cache_decr server, cache_key, amount end rescue TypeError, SocketError, SystemCallError, IOError => err handle_error server, err end |
#delete(key, expiry = 0) ⇒ Object
Removes key
from the cache in expiry
seconds.
310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 |
# File 'lib/memcache.rb', line 310 def delete(key, expiry = 0) @mutex.lock if @multithread raise MemCacheError, "No active servers" unless active? cache_key = make_cache_key key server = get_server_for_key cache_key sock = server.socket raise MemCacheError, "No connection to server" if sock.nil? begin sock.write "delete #{cache_key} #{expiry}\r\n" sock.gets rescue SocketError, SystemCallError, IOError => err server.close raise MemCacheError, err. end ensure @mutex.unlock if @multithread end |
#get(key, raw = false) ⇒ Object Also known as: []
Retrieves key
from memcache. If raw
is false, the value will be unmarshalled.
198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 |
# File 'lib/memcache.rb', line 198 def get(key, raw = false) server, cache_key = request_setup key value = if @multithread then threadsafe_cache_get server, cache_key else cache_get server, cache_key end return nil if value.nil? value = Marshal.load value unless raw return value rescue TypeError, SocketError, SystemCallError, IOError => err handle_error server, err end |
#get_multi(*keys) ⇒ Object
Retrieves multiple values from memcached in parallel, if possible.
The memcached protocol supports the ability to retrieve multiple keys in a single request. Pass in an array of keys to this method and it will:
-
map the key to the appropriate memcached server
-
send a single request to each server that has one or more key values
Returns a hash of values.
cache["a"] = 1
cache["b"] = 2
cache.get_multi "a", "b" # => { "a" => 1, "b" => 2 }
232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 |
# File 'lib/memcache.rb', line 232 def get_multi(*keys) raise MemCacheError, 'No active servers' unless active? keys.flatten! key_count = keys.length cache_keys = {} server_keys = Hash.new { |h,k| h[k] = [] } # map keys to servers keys.each do |key| server, cache_key = request_setup key cache_keys[cache_key] = key server_keys[server] << cache_key end results = {} server_keys.each do |server, keys| keys = keys.join ' ' values = if @multithread then threadsafe_cache_get_multi server, keys else cache_get_multi server, keys end values.each do |key, value| results[cache_keys[key]] = Marshal.load value end end return results rescue TypeError, SocketError, SystemCallError, IOError => err handle_error server, err end |
#get_server_for_key(key) ⇒ Object
Pick a server to handle the request based on a hash of the key.
429 430 431 432 433 434 435 436 437 438 439 440 441 442 443 444 445 |
# File 'lib/memcache.rb', line 429 def get_server_for_key(key) raise ArgumentError, "illegal character in key #{key.inspect}" if key =~ /\s/ raise ArgumentError, "key too long #{key.inspect}" if key.length > 250 raise MemCacheError, "No servers available" if @servers.empty? return @servers.first if @servers.length == 1 hkey = hash_for key 20.times do |try| server = @buckets[hkey % @buckets.nitems] return server if server.alive? hkey += hash_for "#{try}#{key}" end raise MemCacheError, "No servers available" end |
#handle_error(server, error) ⇒ Object
Handles error
from server
.
524 525 526 527 528 529 |
# File 'lib/memcache.rb', line 524 def handle_error(server, error) server.close if server new_error = MemCacheError.new error. new_error.set_backtrace error.backtrace raise new_error end |
#hash_for(key) ⇒ Object
Returns an interoperable hash value for key
. (I think, docs are sketchy for down servers).
451 452 453 |
# File 'lib/memcache.rb', line 451 def hash_for(key) (key.crc32_ITU_T >> 16) & 0x7fff end |
#incr(key, amount = 1) ⇒ Object
Increments the value for key
by amount
and retruns the new value. key
must already exist. If key
is not an integer, it is assumed to be 0.
271 272 273 274 275 276 277 278 279 280 281 |
# File 'lib/memcache.rb', line 271 def incr(key, amount = 1) server, cache_key = request_setup key if @multithread then threadsafe_cache_incr server, cache_key, amount else cache_incr server, cache_key, amount end rescue TypeError, SocketError, SystemCallError, IOError => err handle_error server, err end |
#inspect ⇒ Object
Returns a string representation of the cache object.
127 128 129 130 |
# File 'lib/memcache.rb', line 127 def inspect "<MemCache: %d servers, %d buckets, ns: %p, ro: %p>" % [@servers.length, @buckets.length, @namespace, @readonly] end |
#make_cache_key(key) ⇒ Object
Create a key for the cache, incorporating the namespace qualifier if requested.
418 419 420 421 422 423 424 |
# File 'lib/memcache.rb', line 418 def make_cache_key(key) if namespace.nil? then key else "#{@namespace}:#{key}" end end |
#readonly? ⇒ Boolean
Returns whether or not the cache object was created read only.
142 143 144 |
# File 'lib/memcache.rb', line 142 def readonly? @readonly end |
#request_setup(key) ⇒ Object
Performs setup for making a request with key
from memcached. Returns the server to fetch the key from and the complete key to use.
535 536 537 538 539 540 541 |
# File 'lib/memcache.rb', line 535 def request_setup(key) raise MemCacheError, 'No active servers' unless active? cache_key = make_cache_key key server = get_server_for_key cache_key raise MemCacheError, 'No connection to server' if server.socket.nil? return server, cache_key end |
#reset ⇒ Object
Reset the connection to all memcache servers. This should be called if there is a problem with a cache lookup that might have left the connection in a corrupted state.
336 337 338 |
# File 'lib/memcache.rb', line 336 def reset @servers.each { |server| server.close } end |
#servers=(servers) ⇒ Object
Set the servers that the requests will be distributed between. Entries can be either strings of the form “hostname:port” or “hostname:port:weight” or MemCache::Server objects.
151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 |
# File 'lib/memcache.rb', line 151 def servers=(servers) # Create the server objects. @servers = servers.collect do |server| case server when String host, port, weight = server.split ':', 3 port ||= DEFAULT_PORT weight ||= DEFAULT_WEIGHT Server.new self, host, port, weight when Server if server.memcache.multithread != @multithread then raise ArgumentError, "can't mix threaded and non-threaded servers" end server else raise TypeError, "cannot convert #{server.class} into MemCache::Server" end end # Create an array of server buckets for weight selection of servers. @buckets = [] @servers.each do |server| server.weight.times { @buckets.push(server) } end end |
#set(key, value, expiry = 0, raw = false) ⇒ Object
Add key
to the cache with value value
that expires in expiry
seconds. If raw
is true, value
will not be Marshalled.
287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 |
# File 'lib/memcache.rb', line 287 def set(key, value, expiry = 0, raw = false) raise MemCacheError, "Update of readonly cache" if @readonly server, cache_key = request_setup key socket = server.socket value = Marshal.dump value unless raw command = "set #{cache_key} 0 #{expiry} #{value.size}\r\n#{value}\r\n" begin @mutex.lock if @multithread socket.write command socket.gets rescue SocketError, SystemCallError, IOError => err server.close raise MemCacheError, err. ensure @mutex.unlock if @multithread end end |
#stats ⇒ Object
Returns statistics for each memcached server. An explanation of the statistics can be found in the memcached docs:
code.sixapart.com/svn/memcached/trunk/server/doc/protocol.txt
Example:
>> pp CACHE.stats
{"localhost:11211"=>
{"bytes"=>"4718",
"pid"=>"20188",
"connection_structures"=>"4",
"time"=>"1162278121",
"pointer_size"=>"32",
"limit_maxbytes"=>"67108864",
"cmd_get"=>"14532",
"version"=>"1.2.0",
"bytes_written"=>"432583",
"cmd_set"=>"32",
"get_misses"=>"0",
"total_connections"=>"19",
"curr_connections"=>"3",
"curr_items"=>"4",
"uptime"=>"1557",
"get_hits"=>"14532",
"total_items"=>"32",
"rusage_system"=>"0.313952",
"rusage_user"=>"0.119981",
"bytes_read"=>"190619"}}
=> nil
372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 |
# File 'lib/memcache.rb', line 372 def stats raise MemCacheError, "No active servers" unless active? server_stats = {} @servers.each do |server| sock = server.socket raise MemCacheError, "No connection to server" if sock.nil? value = nil begin sock.write "stats\r\n" stats = {} while line = sock.gets break if line == "END\r\n" line =~ /^STAT ([\w]+) ([\d.]+)/ stats[$1] = $2 end server_stats["#{server.host}:#{server.port}"] = stats.clone rescue SocketError, SystemCallError, IOError => err server.close raise MemCacheError, err. end end server_stats end |
#threadsafe_cache_decr(server, cache_key, amount) ⇒ Object
:nodoc:
543 544 545 546 547 548 |
# File 'lib/memcache.rb', line 543 def threadsafe_cache_decr(server, cache_key, amount) # :nodoc: @mutex.lock cache_decr server, cache_key, amount ensure @mutex.unlock end |
#threadsafe_cache_get(server, cache_key) ⇒ Object
:nodoc:
550 551 552 553 554 555 |
# File 'lib/memcache.rb', line 550 def threadsafe_cache_get(server, cache_key) # :nodoc: @mutex.lock cache_get server, cache_key ensure @mutex.unlock end |
#threadsafe_cache_get_multi(socket, cache_key) ⇒ Object
:nodoc:
557 558 559 560 561 562 |
# File 'lib/memcache.rb', line 557 def threadsafe_cache_get_multi(socket, cache_key) # :nodoc: @mutex.lock cache_get_multi socket, cache_key ensure @mutex.unlock end |
#threadsafe_cache_incr(server, cache_key, amount) ⇒ Object
:nodoc:
564 565 566 567 568 569 |
# File 'lib/memcache.rb', line 564 def threadsafe_cache_incr(server, cache_key, amount) # :nodoc: @mutex.lock cache_incr server, cache_key, amount ensure @mutex.unlock end |