Object
Dalli::Client is the main class which developers will use to interact with the memcached server. Usage:
Dalli::Client.new(['localhost:11211:10', 'cache-2.example.com:11211:5', '192.168.0.1:22122:5'], :threadsafe => true, :failover => true, :expires_in => 300)
servers is an Array of "host:port:weight" where weight allows you to distribute cache unevenly. Both weight and port are optional. If you pass in nil, Dalli will use the MEMCACHE_SERVERS environment variable or default to 'localhost:11211' if it is not present.
Options:
:namespace - prepend each key with this value to provide simple namespacing.
:failover - if a server is down, look for and store values on another server in the ring. Default: true.
:threadsafe - ensure that only one thread is actively using a socket at a time. Default: true.
:expires_in - default TTL in seconds if you do not pass TTL as a parameter to an individual operation, defaults to 0 or forever
:compress - defaults to false, if true Dalli will compress values larger than 1024 bytes before sending them to memcached.
:serializer - defaults to Marshal
:compressor - defaults to zlib
# File lib/dalli/client.rb, line 28 def initialize(servers=nil, options={}) @servers = normalize_servers(servers || ENV["MEMCACHE_SERVERS"] || '127.0.0.1:11211') @options = normalize_options(options) @ring = nil end
Conditionally add a key/value pair, if the key does not already exist on the server. Returns true if the operation succeeded.
# File lib/dalli/client.rb, line 205 def add(key, value, ttl=nil, options=nil) ttl ||= @options[:expires_in].to_i perform(:add, key, value, ttl, options) end
Append value to the value already stored on the server for 'key'. Appending only works for values stored with :raw => true.
# File lib/dalli/client.rb, line 225 def append(key, value) perform(:append, key, value.to_s) end
compare and swap values using optimistic locking. Fetch the existing value for key. If it exists, yield the value to the block. Add the block's return value as the new value for the key. Add will fail if someone else changed the value.
Returns:
nil if the key did not exist.
false if the value was changed by someone else.
true if the value was successfully updated.
# File lib/dalli/client.rb, line 187 def cas(key, ttl=nil, options=nil, &block) ttl ||= @options[:expires_in].to_i (value, cas) = perform(:cas, key) value = (!value || value == 'Not found') ? nil : value if value newvalue = block.call(value) perform(:set, key, newvalue, ttl, cas, options) end end
Close our connection to each server. If you perform another operation after this, the connections will be re-established.
# File lib/dalli/client.rb, line 314 def close if @ring @ring.servers.each { |s| s.close } @ring = nil end end
Decr subtracts the given amount from the counter on the memcached server. Amt must be a positive integer value.
memcached counters are unsigned and cannot hold negative values. Calling decr on a counter which is 0 will just return 0.
If default is nil, the counter must already exist or the operation will fail and will return nil. Otherwise this method will return the new value for the counter.
Note that the ttl will only apply if the counter does not already exist. To decrease an existing counter and update its TTL, use cas.
# File lib/dalli/client.rb, line 274 def decr(key, amt=1, ttl=nil, default=nil) raise ArgumentError, "Positive values only: #{amt}" if amt < 0 ttl ||= @options[:expires_in].to_i perform(:decr, key, amt.to_i, ttl, default) end
# File lib/dalli/client.rb, line 218 def delete(key) perform(:delete, key) end
# File lib/dalli/client.rb, line 166 def fetch(key, ttl=nil, options=nil) ttl ||= @options[:expires_in].to_i val = get(key, options) if val.nil? && block_given? val = yield add(key, val, ttl, options) end val end
# File lib/dalli/client.rb, line 236 def flush(delay=0) time = -delay ring.servers.map { |s| s.request(:flush, time += delay) } end
# File lib/dalli/client.rb, line 61 def get(key, options=nil) resp = perform(:get, key) resp.nil? || 'Not found' == resp ? nil : resp end
Fetch multiple keys efficiently. Returns a hash of { 'key' => 'value', 'key2' => 'value1' }
# File lib/dalli/client.rb, line 69 def get_multi(*keys) perform do return {} if keys.empty? options = nil options = keys.pop if keys.last.is_a?(Hash) || keys.last.nil? ring.lock do begin mapped_keys = keys.flatten.map {|a| validate_key(a.to_s)} groups = mapped_keys.flatten.group_by do |key| begin ring.server_for_key(key) rescue Dalli::RingError Dalli.logger.debug { "unable to get key #{key}" } nil end end if unfound_keys = groups.delete(nil) Dalli.logger.debug { "unable to get keys for #{unfound_keys.length} keys because no matching server was found" } end groups.each do |server, keys_for_server| begin # TODO: do this with the perform chokepoint? # But given the fact that fetching the response doesn't take place # in that slot it's misleading anyway. Need to move all of this method # into perform to be meaningful server.request(:send_multiget, keys_for_server) rescue DalliError, NetworkError => e Dalli.logger.debug { e.inspect } Dalli.logger.debug { "unable to get keys for server #{server.hostname}:#{server.port}" } end end servers = groups.keys values = {} return values if servers.empty? servers.each do |server| next unless server.alive? begin server.multi_response_start rescue DalliError, NetworkError => e Dalli.logger.debug { e.inspect } Dalli.logger.debug { "results from this server will be missing" } servers.delete(server) end end start = Time.now loop do # remove any dead servers servers.delete_if { |s| s.sock.nil? } break if servers.empty? # calculate remaining timeout elapsed = Time.now - start timeout = servers.first.options[:socket_timeout] if elapsed > timeout readable = nil else sockets = servers.map(&:sock) readable, _ = IO.select(sockets, nil, nil, timeout - elapsed) end if readable.nil? # no response within timeout; abort pending connections servers.each do |server| Dalli.logger.debug { "memcached at #{server.name} did not response within timeout" } server.multi_response_abort end break else readable.each do |sock| server = sock.server begin server.multi_response_nonblock.each do |key, value| values[key_without_namespace(key)] = value end if server.multi_response_completed? servers.delete(server) end rescue NetworkError servers.delete(server) end end end end values end end end end
Incr adds the given amount to the counter on the memcached server. Amt must be a positive integer value.
If default is nil, the counter must already exist or the operation will fail and will return nil. Otherwise this method will return the new value for the counter.
Note that the ttl will only apply if the counter does not already exist. To increase an existing counter and update its TTL, use cas.
# File lib/dalli/client.rb, line 254 def incr(key, amt=1, ttl=nil, default=nil) raise ArgumentError, "Positive values only: #{amt}" if amt < 0 ttl ||= @options[:expires_in].to_i perform(:incr, key, amt.to_i, ttl, default) end
Turn on quiet aka noreply support. All relevant operations within this block will be effectively pipelined as Dalli will use 'quiet' operations where possible. Currently supports the set, add, replace and delete operations.
# File lib/dalli/client.rb, line 54 def multi old, Thread.current[:dalli_multi] = Thread.current[:dalli_multi], true yield ensure Thread.current[:dalli_multi] = old end
Normalizes the argument into an array of servers. If the argument is a string, it's expected to be of the format "memcache1.example.com:11211[,memcache2.example.com:11211[,memcache3.example.com:11211]]
# File lib/dalli/client.rb, line 37 def normalize_servers(servers) if servers.is_a? String return servers.split(",") else return servers end end
Prepend value to the value already stored on the server for 'key'. Prepending only works for values stored with :raw => true.
# File lib/dalli/client.rb, line 232 def prepend(key, value) perform(:prepend, key, value.to_s) end
Conditionally add a key/value pair, only if the key already exists on the server. Returns true if the operation succeeded.
# File lib/dalli/client.rb, line 213 def replace(key, value, ttl=nil, options=nil) ttl ||= @options[:expires_in].to_i perform(:replace, key, value, ttl, options) end
Reset stats for each server.
# File lib/dalli/client.rb, line 305 def reset_stats ring.servers.map do |server| server.alive? ? server.request(:reset_stats) : nil end end
# File lib/dalli/client.rb, line 197 def set(key, value, ttl=nil, options=nil) ttl ||= @options[:expires_in].to_i perform(:set, key, value, ttl, 0, options) end
Collect the stats for each server. You can optionally pass a type including :items or :slabs to get specific stats Returns a hash like { 'hostname:port' => { 'stat1' => 'value1', ... }, 'hostname2:port' => { ... } }
# File lib/dalli/client.rb, line 294 def stats(type=nil) type = nil if ![nil, :items,:slabs].include? type values = {} ring.servers.each do |server| values["#{server.hostname}:#{server.port}"] = server.alive? ? server.request(:stats,type.to_s) : nil end values end
Generated with the Darkfish Rdoc Generator 2.