Class: MemCache
- Inherits:
-
Object
- Object
- MemCache
- Defined in:
- lib/memcache.rb,
lib/memcache/version.rb,
lib/memcache/event_machine.rb
Overview
A Ruby client library for memcached.
Defined Under Namespace
Modules: EventedServer Classes: BufferedIO, MemCacheError, Server
Constant Summary collapse
- DEFAULT_OPTIONS =
Default options for the cache object.
{ :namespace => nil, :readonly => false, :multithread => true, :failover => true, :timeout => 0.5, :logger => nil, :no_reply => false, :check_size => true, :autofix_keys => false, :namespace_separator => ':', }
- DEFAULT_PORT =
Default memcached port.
11211
- DEFAULT_WEIGHT =
Default memcached server weight.
1
- ONE_MB =
Add
key
to the cache with valuevalue
that expires inexpiry
seconds. Ifraw
is true,value
will not be Marshalled.Warning: Readers should not call this method in the event of a cache miss; see MemCache#add.
1024 * 1024
- VERSION =
The version of MemCache you are using.
"1.8.3"
Instance Attribute Summary collapse
-
#autofix_keys ⇒ Object
readonly
Whether to try to fix keys that are too long and will be truncated by using their SHA1 hash instead.
-
#failover ⇒ Object
readonly
Should the client try to failover to another server if the first server is down? Defaults to true.
-
#logger ⇒ Object
readonly
Log debug/info/warn/error to the given Logger, defaults to nil.
-
#multithread ⇒ Object
readonly
The multithread setting for this instance.
-
#namespace ⇒ Object
readonly
The namespace for this instance.
-
#no_reply ⇒ Object
readonly
Don’t send or look for a reply from the memcached server for write operations.
-
#servers ⇒ Object
The servers this client talks to.
-
#timeout ⇒ Object
readonly
Socket timeout limit with this client, defaults to 0.5 sec.
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.
-
#add(key, value, expiry = 0, raw = false) ⇒ Object
Add
key
to the cache with valuevalue
that expires inexpiry
seconds, but only ifkey
does not already exist in the cache. -
#append(key, value) ⇒ Object
Append - ‘add this data to an existing key after existing data’ Please note the value is always passed to memcached as raw since it doesn’t make a lot of sense to concatenate marshalled data together.
-
#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
. -
#cas(key, expiry = 0, raw = false) ⇒ Object
“cas” is a check and set operation which means “store this data but only if no one else has updated since I last fetched it.” This can be used as a form of optimistic locking.
- #check_multithread_status! ⇒ Object
- #create_continuum_for(servers) ⇒ Object
-
#decr(key, amount = 1) ⇒ Object
Decrements the value for
key
byamount
and returns the new value. -
#delete(key, expiry = 0) ⇒ Object
Removes
key
from the cache. - #entry_count_for(server, total_servers, total_weight) ⇒ Object
-
#fetch(key, expiry = 0, raw = false) ⇒ Object
Performs a
get
with the givenkey
. -
#flush_all(delay = 0) ⇒ Object
Flush the cache from all memcache servers.
-
#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, options = {}) ⇒ Object
Pick a server to handle the request based on a hash of the key.
- #gets(key, raw = false) ⇒ Object
-
#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 returns 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.
-
#key_length(key) ⇒ Object
Calculate length of the key, including the namespace and namespace-separator.
-
#make_cache_key(key) ⇒ Object
Create a key for the cache, incorporating the namespace qualifier if requested.
- #noreply ⇒ Object
-
#prepend(key, value) ⇒ Object
Prepend - ‘add this data to an existing key before existing data’ Please note the value is always passed to memcached as raw since it doesn’t make a lot of sense to concatenate marshalled data together.
- #raise_on_error_response!(response) ⇒ Object
-
#readonly? ⇒ Boolean
Returns whether or not the cache object was created read only.
-
#replace(key, value, expiry = 0, raw = false) ⇒ Object
Add
key
to the cache with valuevalue
that expires inexpiry
seconds, but only ifkey
already exists in the cache. -
#request_setup(key) ⇒ Object
Performs setup for making a request with
key
from memcached. -
#reset ⇒ Object
Reset the connection to all memcache servers.
- #set(key, value, expiry = 0, raw = false) ⇒ Object
-
#stats ⇒ Object
Returns statistics for each memcached server.
- #with_server(key) ⇒ Object
-
#with_socket_management(server, &block) ⇒ Object
Gets or creates a socket connected to the given server, and yields it to the block, wrapped in a mutex synchronization if @multithread is true.
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 exception on cache writes when true.
[:multithread] Wraps cache access in a Mutex for thread safety. Defaults to true.
[:failover] Should the client try to failover to another server if the
first server is down? Defaults to true.
[:timeout] Time to use as the socket read timeout. Defaults to 0.5 sec,
set to nil to disable timeouts.
[:logger] Logger to use for info/debug output, defaults to nil
[:no_reply] Don't bother looking for a reply for write operations (i.e. they
become 'fire and forget'), memcached 1.2.5 and later only, speeds up
set/add/delete/incr/decr significantly.
[:check_size] Raises a MemCacheError if the value to be set is greater than 1 MB, which
is the maximum key size for the standard memcached server. Defaults to true.
[:autofix_keys] If a key is longer than 250 characters or contains spaces,
use an SHA1 hash instead, to prevent collisions on truncated keys.
Other options are ignored.
137 138 139 140 141 142 143 144 145 146 147 148 149 150 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 176 177 |
# File 'lib/memcache.rb', line 137 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 @evented = defined?(EM) && EM.reactor_running? opts = DEFAULT_OPTIONS.merge opts @namespace = opts[:namespace] @readonly = opts[:readonly] @multithread = opts[:multithread] && !@evented @autofix_keys = opts[:autofix_keys] @timeout = opts[:timeout] @failover = opts[:failover] @logger = opts[:logger] @no_reply = opts[:no_reply] @check_size = opts[:check_size] @namespace_separator = opts[:namespace_separator] @mutex = Mutex.new if @multithread logger.info { "memcache-client #{VERSION} #{Array(servers).inspect}" } if logger Thread.current[:memcache_client] = self.object_id if !@multithread self.servers = servers end |
Instance Attribute Details
#autofix_keys ⇒ Object (readonly)
Whether to try to fix keys that are too long and will be truncated by using their SHA1 hash instead. The hash is only used on keys longer than 250 characters, or containing spaces, to avoid impacting performance unnecesarily.
In theory, your code should generate correct keys when calling memcache, so it’s your responsibility and you should try to fix this problem at its source.
But if that’s not possible, enable this option and memcache-client will give you a hand.
84 85 86 |
# File 'lib/memcache.rb', line 84 def autofix_keys @autofix_keys end |
#failover ⇒ Object (readonly)
Should the client try to failover to another server if the first server is down? Defaults to true.
101 102 103 |
# File 'lib/memcache.rb', line 101 def failover @failover end |
#logger ⇒ Object (readonly)
Log debug/info/warn/error to the given Logger, defaults to nil.
106 107 108 |
# File 'lib/memcache.rb', line 106 def logger @logger end |
#multithread ⇒ Object (readonly)
The multithread setting for this instance
71 72 73 |
# File 'lib/memcache.rb', line 71 def multithread @multithread end |
#namespace ⇒ Object (readonly)
The namespace for this instance
66 67 68 |
# File 'lib/memcache.rb', line 66 def namespace @namespace end |
#no_reply ⇒ Object (readonly)
Don’t send or look for a reply from the memcached server for write operations. Please note this feature only works in memcached 1.2.5 and later. Earlier versions will reply with “ERROR”.
112 113 114 |
# File 'lib/memcache.rb', line 112 def no_reply @no_reply end |
#servers ⇒ Object
The servers this client talks to. Play at your own peril.
89 90 91 |
# File 'lib/memcache.rb', line 89 def servers @servers end |
#timeout ⇒ Object (readonly)
Socket timeout limit with this client, defaults to 0.5 sec. Set to nil to disable timeouts.
95 96 97 |
# File 'lib/memcache.rb', line 95 def timeout @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.
660 661 662 |
# File 'lib/memcache.rb', line 660 def []=(key, value) set key, value end |
#active? ⇒ Boolean
Returns whether there is at least one active server for the object.
190 191 192 |
# File 'lib/memcache.rb', line 190 def active? not @servers.empty? end |
#add(key, value, expiry = 0, raw = false) ⇒ Object
Add key
to the cache with value value
that expires in expiry
seconds, but only if key
does not already exist in the cache. If raw
is true, value
will not be Marshalled.
Readers should call this method in the event of a cache miss, not MemCache#set.
439 440 441 442 443 444 445 446 447 448 449 450 451 452 453 454 |
# File 'lib/memcache.rb', line 439 def add(key, value, expiry = 0, raw = false) raise MemCacheError, "Update of readonly cache" if @readonly value = Marshal.dump value unless raw with_server(key) do |server, cache_key| logger.debug { "add #{key} to #{server}: #{value ? value.to_s.size : 'nil'}" } if logger command = "add #{cache_key} 0 #{expiry} #{value.to_s.size}#{noreply}\r\n#{value}\r\n" with_socket_management(server) do |socket| socket.write command break nil if @no_reply result = socket.gets raise_on_error_response! result result end end end |
#append(key, value) ⇒ Object
Append - ‘add this data to an existing key after existing data’ Please note the value is always passed to memcached as raw since it doesn’t make a lot of sense to concatenate marshalled data together.
481 482 483 484 485 486 487 488 489 490 491 492 493 494 495 |
# File 'lib/memcache.rb', line 481 def append(key, value) raise MemCacheError, "Update of readonly cache" if @readonly with_server(key) do |server, cache_key| logger.debug { "append #{key} to #{server}: #{value ? value.to_s.size : 'nil'}" } if logger command = "append #{cache_key} 0 0 #{value.to_s.size}#{noreply}\r\n#{value}\r\n" with_socket_management(server) do |socket| socket.write command break nil if @no_reply result = socket.gets raise_on_error_response! result result end end end |
#cache_decr(server, cache_key, amount) ⇒ Object
Performs a raw decr for cache_key
from server
. Returns nil if not found.
725 726 727 728 729 730 731 732 733 734 |
# File 'lib/memcache.rb', line 725 def cache_decr(server, cache_key, amount) with_socket_management(server) do |socket| socket.write "decr #{cache_key} #{amount}#{noreply}\r\n" break nil if @no_reply text = socket.gets raise_on_error_response! text return nil if text == "NOT_FOUND\r\n" return text.to_i end end |
#cache_get(server, cache_key) ⇒ Object
Fetches the raw data for cache_key
from server
. Returns nil on cache miss.
740 741 742 743 744 745 746 747 748 749 750 751 752 753 754 755 756 757 758 759 760 761 762 |
# File 'lib/memcache.rb', line 740 def cache_get(server, cache_key) with_socket_management(server) do |socket| socket.write "get #{cache_key}\r\n" keyline = socket.gets # "VALUE <key> <flags> <bytes>\r\n" if keyline.nil? then server.close raise MemCacheError, "lost connection to #{server.host}:#{server.port}" end raise_on_error_response! keyline 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 end |
#cache_get_multi(server, cache_keys) ⇒ Object
Fetches cache_keys
from server
using a multi-get.
799 800 801 802 803 804 805 806 807 808 809 810 811 812 813 814 815 816 817 818 819 820 821 |
# File 'lib/memcache.rb', line 799 def cache_get_multi(server, cache_keys) with_socket_management(server) do |socket| values = {} socket.write "get #{cache_keys}\r\n" while keyline = socket.gets do return values if keyline == "END\r\n" raise_on_error_response! keyline unless keyline =~ /\AVALUE (.+) (.+) (.+)/ 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 server.close raise MemCacheError, "lost connection to #{server.host}:#{server.port}" # TODO: retry here too end end |
#cache_incr(server, cache_key, amount) ⇒ Object
Performs a raw incr for cache_key
from server
. Returns nil if not found.
827 828 829 830 831 832 833 834 835 836 |
# File 'lib/memcache.rb', line 827 def cache_incr(server, cache_key, amount) with_socket_management(server) do |socket| socket.write "incr #{cache_key} #{amount}#{noreply}\r\n" break nil if @no_reply text = socket.gets raise_on_error_response! text return nil if text == "NOT_FOUND\r\n" return text.to_i end end |
#cas(key, expiry = 0, raw = false) ⇒ Object
“cas” is a check and set operation which means “store this data but only if no one else has updated since I last fetched it.” This can be used as a form of optimistic locking.
Works in block form like so:
cache.cas('some-key') do |value|
value + 1
end
Returns: nil
if the value was not found on the memcached server. STORED
if the value was updated successfully EXISTS
if the value was updated by someone else since last fetch
402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 419 420 421 422 423 424 425 426 427 428 429 |
# File 'lib/memcache.rb', line 402 def cas(key, expiry=0, raw=false) raise MemCacheError, "Update of readonly cache" if @readonly raise MemCacheError, "A block is required" unless block_given? (value, token) = gets(key, raw) return nil unless value updated = yield value value = raw ? updated : Marshal.dump(updated) with_server(key) do |server, cache_key| logger.debug { "cas #{key} to #{server.inspect}: #{value.to_s.size}" } if logger command = "cas #{cache_key} 0 #{expiry} #{value.to_s.size} #{token}#{noreply}\r\n#{value}\r\n" with_socket_management(server) do |socket| socket.write command break nil if @no_reply result = socket.gets raise_on_error_response! result if result.nil? server.close raise MemCacheError, "lost connection to #{server.host}:#{server.port}" end result end end end |
#check_multithread_status! ⇒ Object
950 951 952 953 954 955 956 957 958 959 960 961 |
# File 'lib/memcache.rb', line 950 def check_multithread_status! return if @multithread return if @evented if Thread.current[:memcache_client] != self.object_id raise MemCacheError, <<-EOM You are accessing this memcache-client instance from multiple threads but have not enabled multithread support. Normally: MemCache.new(['localhost:11211'], :multithread => true) In Rails: config.cache_store = [:mem_cache_store, 'localhost:11211', { :multithread => true }] EOM end end |
#create_continuum_for(servers) ⇒ Object
931 932 933 934 935 936 937 938 939 940 941 942 943 944 |
# File 'lib/memcache.rb', line 931 def create_continuum_for(servers) total_weight = servers.inject(0) { |memo, srv| memo + srv.weight } continuum = [] servers.each do |server| entry_count_for(server, servers.size, total_weight).times do |idx| hash = Digest::SHA1.hexdigest("#{server.host}:#{server.port}:#{idx}") value = Integer("0x#{hash[0..7]}") continuum << Continuum::Entry.new(value, server) end end continuum.sort { |a, b| a.value <=> b.value } end |
#decr(key, amount = 1) ⇒ Object
Decrements 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.
233 234 235 236 237 238 239 240 |
# File 'lib/memcache.rb', line 233 def decr(key, amount = 1) raise MemCacheError, "Update of readonly cache" if @readonly with_server(key) do |server, cache_key| cache_decr server, cache_key, amount end rescue TypeError => err handle_error nil, err end |
#delete(key, expiry = 0) ⇒ Object
Removes key
from the cache. expiry
is ignored as it has been removed from the latest memcached version.
521 522 523 524 525 526 527 528 529 530 531 532 533 |
# File 'lib/memcache.rb', line 521 def delete(key, expiry = 0) raise MemCacheError, "Update of readonly cache" if @readonly with_server(key) do |server, cache_key| with_socket_management(server) do |socket| logger.debug { "delete #{cache_key} on #{server}" } if logger socket.write "delete #{cache_key}#{noreply}\r\n" break nil if @no_reply result = socket.gets raise_on_error_response! result result end end end |
#entry_count_for(server, total_servers, total_weight) ⇒ Object
946 947 948 |
# File 'lib/memcache.rb', line 946 def entry_count_for(server, total_servers, total_weight) ((total_servers * Continuum::POINTS_PER_SERVER * server.weight) / Float(total_weight)).floor end |
#fetch(key, expiry = 0, raw = false) ⇒ Object
Performs a get
with the given key
. If the value does not exist and a block was given, the block will be called and the result saved via add
.
If you do not provide a block, using this method is the same as using get
.
266 267 268 269 270 271 272 273 274 275 |
# File 'lib/memcache.rb', line 266 def fetch(key, expiry = 0, raw = false) value = get(key, raw) if value.nil? && block_given? value = yield add(key, value, expiry, raw) end value end |
#flush_all(delay = 0) ⇒ Object
Flush the cache from all memcache servers. A non-zero value for delay
will ensure that the flush is propogated slowly through your memcached server farm. The Nth server will be flushed N*delay seconds from now, asynchronously so this method returns quickly. This prevents a huge database spike due to a total flush all at once.
544 545 546 547 548 549 550 551 552 553 554 555 556 557 558 559 560 561 562 563 564 565 566 567 568 |
# File 'lib/memcache.rb', line 544 def flush_all(delay=0) raise MemCacheError, 'No active servers' unless active? raise MemCacheError, "Update of readonly cache" if @readonly begin delay_time = 0 @servers.each do |server| with_socket_management(server) do |socket| logger.debug { "flush_all #{delay_time} on #{server}" } if logger if delay == 0 # older versions of memcached will fail silently otherwise socket.write "flush_all#{noreply}\r\n" else socket.write "flush_all #{delay_time}#{noreply}\r\n" end break nil if @no_reply result = socket.gets raise_on_error_response! result result end delay_time += delay end rescue IndexError => err handle_error nil, err end end |
#get(key, raw = false) ⇒ Object Also known as: []
Retrieves key
from memcache. If raw
is false, the value will be unmarshalled.
246 247 248 249 250 251 252 253 254 255 256 |
# File 'lib/memcache.rb', line 246 def get(key, raw = false) with_server(key) do |server, cache_key| logger.debug { "get #{key} from #{server.inspect}" } if logger value = cache_get server, cache_key return nil if value.nil? value = Marshal.load value unless raw return value end rescue TypeError => err handle_error nil, 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 }
Note that get_multi assumes the values are marshalled. You can pass in :raw => true to bypass value marshalling.
cache.get_multi('a', 'b', ..., :raw => true)
298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 |
# File 'lib/memcache.rb', line 298 def get_multi(*keys) raise MemCacheError, 'No active servers' unless active? opts = keys.last.is_a?(Hash) ? keys.pop : {} 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 = {} raw = opts[:raw] || false server_keys.each do |server, keys_for_server| keys_for_server_str = keys_for_server.join ' ' begin values = cache_get_multi server, keys_for_server_str values.each do |key, value| results[cache_keys[key]] = raw ? value : Marshal.load(value) end rescue IndexError => e # Ignore this server and try the others logger.warn { "Unable to retrieve #{keys_for_server.size} elements from #{server.inspect}: #{e.}"} if logger end end return results rescue TypeError => err handle_error nil, err end |
#get_server_for_key(key, options = {}) ⇒ Object
Pick a server to handle the request based on a hash of the key.
700 701 702 703 704 705 706 707 708 709 710 711 712 713 714 715 716 717 718 719 |
# File 'lib/memcache.rb', line 700 def get_server_for_key(key, = {}) raise ArgumentError, "illegal character in key #{key.inspect}" if key =~ /\s/ raise ArgumentError, "key cannot be blank" if key.nil? || key.strip.size == 0 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| entryidx = Continuum.binary_search(@continuum, hkey) server = @continuum[entryidx].server return server if server.alive? break unless failover hkey = hash_for "#{try}#{key}" end raise MemCacheError, "No servers available" end |
#gets(key, raw = false) ⇒ Object
764 765 766 767 768 769 770 771 772 773 774 775 776 777 778 779 780 781 782 783 784 785 786 787 788 789 790 791 792 793 |
# File 'lib/memcache.rb', line 764 def gets(key, raw = false) with_server(key) do |server, cache_key| logger.debug { "gets #{key} from #{server.inspect}" } if logger result = with_socket_management(server) do |socket| socket.write "gets #{cache_key}\r\n" keyline = socket.gets # "VALUE <key> <flags> <bytes> <cas token>\r\n" if keyline.nil? then server.close raise MemCacheError, "lost connection to #{server.host}:#{server.port}" end raise_on_error_response! keyline return nil if keyline == "END\r\n" unless keyline =~ /(\d+) (\w+)\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" [value, $2] end result[0] = Marshal.load result[0] unless raw result end rescue TypeError => err handle_error nil, err end |
#handle_error(server, error) ⇒ Object
Handles error
from server
.
902 903 904 905 906 907 908 |
# File 'lib/memcache.rb', line 902 def handle_error(server, error) raise error if error.is_a?(MemCacheError) server.close if server && server.status == "CONNECTED" 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).
693 694 695 |
# File 'lib/memcache.rb', line 693 def hash_for(key) Zlib.crc32(key) end |
#incr(key, amount = 1) ⇒ Object
Increments 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 0.
340 341 342 343 344 345 346 347 |
# File 'lib/memcache.rb', line 340 def incr(key, amount = 1) raise MemCacheError, "Update of readonly cache" if @readonly with_server(key) do |server, cache_key| cache_incr server, cache_key, amount end rescue TypeError => err handle_error nil, err end |
#inspect ⇒ Object
Returns a string representation of the cache object.
182 183 184 185 |
# File 'lib/memcache.rb', line 182 def inspect "<MemCache: %d servers, ns: %p, ro: %p>" % [@servers.length, @namespace, @readonly] end |
#key_length(key) ⇒ Object
Calculate length of the key, including the namespace and namespace-separator.
685 686 687 |
# File 'lib/memcache.rb', line 685 def key_length(key) key.length + (namespace.nil? ? 0 : ( namespace.length + (@namespace_separator.nil? ? 0 : @namespace_separator.length) ) ) end |
#make_cache_key(key) ⇒ Object
Create a key for the cache, incorporating the namespace qualifier if requested.
670 671 672 673 674 675 676 677 678 679 680 |
# File 'lib/memcache.rb', line 670 def make_cache_key(key) if @autofix_keys && (key =~ /\s/ || key_length(key) > 250) key = "#{Digest::SHA1.hexdigest(key)}-autofixed" end if namespace.nil? key else "#{@namespace}#{@namespace_separator}#{key}" end end |
#noreply ⇒ Object
910 911 912 |
# File 'lib/memcache.rb', line 910 def noreply @no_reply ? ' noreply' : '' end |
#prepend(key, value) ⇒ Object
Prepend - ‘add this data to an existing key before existing data’ Please note the value is always passed to memcached as raw since it doesn’t make a lot of sense to concatenate marshalled data together.
501 502 503 504 505 506 507 508 509 510 511 512 513 514 515 |
# File 'lib/memcache.rb', line 501 def prepend(key, value) raise MemCacheError, "Update of readonly cache" if @readonly with_server(key) do |server, cache_key| logger.debug { "prepend #{key} to #{server}: #{value ? value.to_s.size : 'nil'}" } if logger command = "prepend #{cache_key} 0 0 #{value.to_s.size}#{noreply}\r\n#{value}\r\n" with_socket_management(server) do |socket| socket.write command break nil if @no_reply result = socket.gets raise_on_error_response! result result end end end |
#raise_on_error_response!(response) ⇒ Object
925 926 927 928 929 |
# File 'lib/memcache.rb', line 925 def raise_on_error_response!(response) if response =~ /\A(?:CLIENT_|SERVER_)?ERROR(.*)/ raise MemCacheError, $1.strip end end |
#readonly? ⇒ Boolean
Returns whether or not the cache object was created read only.
197 198 199 |
# File 'lib/memcache.rb', line 197 def readonly? @readonly end |
#replace(key, value, expiry = 0, raw = false) ⇒ Object
Add key
to the cache with value value
that expires in expiry
seconds, but only if key
already exists in the cache. If raw
is true, value
will not be Marshalled.
460 461 462 463 464 465 466 467 468 469 470 471 472 473 474 475 |
# File 'lib/memcache.rb', line 460 def replace(key, value, expiry = 0, raw = false) raise MemCacheError, "Update of readonly cache" if @readonly value = Marshal.dump value unless raw with_server(key) do |server, cache_key| logger.debug { "replace #{key} to #{server}: #{value ? value.to_s.size : 'nil'}" } if logger command = "replace #{cache_key} 0 #{expiry} #{value.to_s.size}#{noreply}\r\n#{value}\r\n" with_socket_management(server) do |socket| socket.write command break nil if @no_reply result = socket.gets raise_on_error_response! result result end end 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.
918 919 920 921 922 923 |
# File 'lib/memcache.rb', line 918 def request_setup(key) raise MemCacheError, 'No active servers' unless active? cache_key = make_cache_key key server = get_server_for_key cache_key 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.
575 576 577 |
# File 'lib/memcache.rb', line 575 def reset @servers.each { |server| server.close } end |
#set(key, value, expiry = 0, raw = false) ⇒ Object
358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 |
# File 'lib/memcache.rb', line 358 def set(key, value, expiry = 0, raw = false) raise MemCacheError, "Update of readonly cache" if @readonly value = Marshal.dump value unless raw with_server(key) do |server, cache_key| logger.debug { "set #{key} to #{server.inspect}: #{value.to_s.size}" } if logger if @check_size && value.to_s.size > ONE_MB raise MemCacheError, "Value too large, memcached can only store 1MB of data per key" end command = "set #{cache_key} 0 #{expiry} #{value.to_s.size}#{noreply}\r\n#{value}\r\n" with_socket_management(server) do |socket| socket.write command break nil if @no_reply result = socket.gets raise_on_error_response! result if result.nil? server.close raise MemCacheError, "lost connection to #{server.host}:#{server.port}" end result end 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
611 612 613 614 615 616 617 618 619 620 621 622 623 624 625 626 627 628 629 630 631 632 633 634 635 636 637 638 639 640 641 642 643 644 645 646 647 648 649 |
# File 'lib/memcache.rb', line 611 def stats raise MemCacheError, "No active servers" unless active? server_stats = {} @servers.each do |server| next unless server.alive? with_socket_management(server) do |socket| value = nil socket.write "stats\r\n" stats = {} while line = socket.gets do raise_on_error_response! line break if line == "END\r\n" if line =~ /\ASTAT ([\S]+) ([\w\.\:]+)/ then name, value = $1, $2 stats[name] = case name when 'version' value when 'rusage_user', 'rusage_system' then seconds, microseconds = value.split(/:/, 2) microseconds ||= 0 Float(seconds) + (Float(microseconds) / 1_000_000) else if value =~ /\A\d+\Z/ then value.to_i else value end end end end server_stats["#{server.host}:#{server.port}"] = stats end end raise MemCacheError, "No active servers" if server_stats.empty? server_stats end |
#with_server(key) ⇒ Object
883 884 885 886 887 888 889 890 891 892 893 894 895 896 897 |
# File 'lib/memcache.rb', line 883 def with_server(key) retried = false begin server, cache_key = request_setup(key) yield server, cache_key rescue IndexError => e logger.warn { "Server failed: #{e.class.name}: #{e.}" } if logger if !retried && @servers.size > 1 logger.info { "Connection to server #{server.inspect} DIED! Retrying operation..." } if logger retried = true retry end handle_error(nil, e) end end |
#with_socket_management(server, &block) ⇒ Object
Gets or creates a socket connected to the given server, and yields it to the block, wrapped in a mutex synchronization if @multithread is true.
If a socket error (SocketError, SystemCallError, IOError) or protocol error (MemCacheError) is raised by the block, closes the socket, attempts to connect again, and retries the block (once). If an error is again raised, reraises it as MemCacheError.
If unable to connect to the server (or if in the reconnect wait period), raises MemCacheError. Note that the socket connect code marks a server dead for a timeout period, so retrying does not apply to connection attempt failures (but does still apply to unexpectedly lost connections etc.).
852 853 854 855 856 857 858 859 860 861 862 863 864 865 866 867 868 869 870 871 872 873 874 875 876 877 878 879 880 881 |
# File 'lib/memcache.rb', line 852 def with_socket_management(server, &block) check_multithread_status! @mutex.lock if @multithread retried = false begin socket = server.socket # Raise an IndexError to show this server is out of whack. If were inside # a with_server block, we'll catch it and attempt to restart the operation. raise IndexError, "No connection to server (#{server.status})" if socket.nil? block.call(socket) rescue SocketError, Errno::EAGAIN, Timeout::Error => err logger.warn { "Socket failure: #{err.}" } if logger server.mark_dead(err) handle_error(server, err) rescue MemCacheError, SystemCallError, IOError => err logger.warn { "Generic failure: #{err.class.name}: #{err.}" } if logger handle_error(server, err) if retried || socket.nil? retried = true retry end ensure @mutex.unlock if @multithread end |