Class: Dalli::Client
- Inherits:
-
Object
- Object
- Dalli::Client
- Defined in:
- lib/dalli/client.rb
Instance Method Summary collapse
-
#add(key, value, ttl = nil, options = nil) ⇒ Object
Conditionally add a key/value pair, if the key does not already exist on the server.
-
#append(key, value) ⇒ Object
Append value to the value already stored on the server for ‘key’.
-
#cas(key, ttl = nil, options = nil, &block) ⇒ Object
compare and swap values using optimistic locking.
-
#close ⇒ Object
(also: #reset)
Close our connection to each server.
-
#decr(key, amt = 1, ttl = nil, default = nil) ⇒ Object
Decr subtracts the given amount from the counter on the memcached server.
- #delete(key) ⇒ Object
- #fetch(key, ttl = nil, options = nil) ⇒ Object
- #flush(delay = 0) ⇒ Object (also: #flush_all)
- #get(key, options = nil) ⇒ Object
-
#get_multi(*keys) ⇒ Object
Fetch multiple keys efficiently.
-
#incr(key, amt = 1, ttl = nil, default = nil) ⇒ Object
Incr adds the given amount to the counter on the memcached server.
-
#initialize(servers = nil, options = {}) ⇒ Client
constructor
Dalli::Client is the main class which developers will use to interact with the memcached server.
-
#multi ⇒ Object
Turn on quiet aka noreply support.
-
#normalize_servers(servers) ⇒ Object
Normalizes the argument into an array of servers.
-
#prepend(key, value) ⇒ Object
Prepend value to the value already stored on the server for ‘key’.
-
#replace(key, value, ttl = nil, options = nil) ⇒ Object
Conditionally add a key/value pair, only if the key already exists on the server.
-
#reset_stats ⇒ Object
Reset stats for each server.
- #set(key, value, ttl = nil, options = nil) ⇒ Object
-
#stats(type = nil) ⇒ Object
Collect the stats for each server.
-
#touch(key, ttl = nil) ⇒ Object
Touch updates expiration time for a given key.
Constructor Details
#initialize(servers = nil, options = {}) ⇒ Client
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
28 29 30 31 32 |
# File 'lib/dalli/client.rb', line 28 def initialize(servers=nil, ={}) @servers = normalize_servers(servers || ENV["MEMCACHE_SERVERS"] || '127.0.0.1:11211') @options = () @ring = nil end |
Instance Method Details
#add(key, value, ttl = nil, options = nil) ⇒ Object
Conditionally add a key/value pair, if the key does not already exist on the server. Returns true if the operation succeeded.
189 190 191 192 |
# File 'lib/dalli/client.rb', line 189 def add(key, value, ttl=nil, =nil) ttl ||= @options[:expires_in].to_i perform(:add, key, value, ttl, ) end |
#append(key, value) ⇒ Object
Append value to the value already stored on the server for ‘key’. Appending only works for values stored with :raw => true.
209 210 211 |
# File 'lib/dalli/client.rb', line 209 def append(key, value) perform(:append, key, value.to_s) end |
#cas(key, ttl = nil, options = nil, &block) ⇒ Object
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.
171 172 173 174 175 176 177 178 179 |
# File 'lib/dalli/client.rb', line 171 def cas(key, ttl=nil, =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, ) end end |
#close ⇒ Object Also known as: reset
Close our connection to each server. If you perform another operation after this, the connections will be re-established.
298 299 300 301 302 303 |
# File 'lib/dalli/client.rb', line 298 def close if @ring @ring.servers.each { |s| s.close } @ring = nil end end |
#decr(key, amt = 1, ttl = nil, default = nil) ⇒ Object
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.
258 259 260 261 262 |
# File 'lib/dalli/client.rb', line 258 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 |
#delete(key) ⇒ Object
202 203 204 |
# File 'lib/dalli/client.rb', line 202 def delete(key) perform(:delete, key) end |
#fetch(key, ttl = nil, options = nil) ⇒ Object
150 151 152 153 154 155 156 157 158 |
# File 'lib/dalli/client.rb', line 150 def fetch(key, ttl=nil, =nil) ttl ||= @options[:expires_in].to_i val = get(key, ) if val.nil? && block_given? val = yield add(key, val, ttl, ) end val end |
#flush(delay = 0) ⇒ Object Also known as: flush_all
220 221 222 223 |
# File 'lib/dalli/client.rb', line 220 def flush(delay=0) time = -delay ring.servers.map { |s| s.request(:flush, time += delay) } end |
#get(key, options = nil) ⇒ Object
61 62 63 64 |
# File 'lib/dalli/client.rb', line 61 def get(key, =nil) resp = perform(:get, key) resp.nil? || 'Not found' == resp ? nil : resp end |
#get_multi(*keys) ⇒ Object
Fetch multiple keys efficiently. Returns a hash of { ‘key’ => ‘value’, ‘key2’ => ‘value1’ }
69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 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 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 |
# File 'lib/dalli/client.rb', line 69 def get_multi(*keys) return {} if keys.empty? = nil = keys.pop if keys.last.is_a?(Hash) || keys.last.nil? ring.lock do begin servers = self.servers_in_use = Set.new keys.flatten.each do |key| begin perform(:getkq, key) rescue DalliError, NetworkError => e Dalli.logger.debug { e.inspect } Dalli.logger.debug { "unable to get key #{key}" } end end 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.[: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| puts "Abort!" 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 ensure self.servers_in_use = nil end end end |
#incr(key, amt = 1, ttl = nil, default = nil) ⇒ Object
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.
238 239 240 241 242 |
# File 'lib/dalli/client.rb', line 238 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 |
#multi ⇒ Object
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.
54 55 56 57 58 59 |
# 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 |
#normalize_servers(servers) ⇒ Object
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]]
37 38 39 40 41 42 43 |
# 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(key, value) ⇒ Object
Prepend value to the value already stored on the server for ‘key’. Prepending only works for values stored with :raw => true.
216 217 218 |
# File 'lib/dalli/client.rb', line 216 def prepend(key, value) perform(:prepend, key, value.to_s) end |
#replace(key, value, ttl = nil, options = nil) ⇒ Object
Conditionally add a key/value pair, only if the key already exists on the server. Returns true if the operation succeeded.
197 198 199 200 |
# File 'lib/dalli/client.rb', line 197 def replace(key, value, ttl=nil, =nil) ttl ||= @options[:expires_in].to_i perform(:replace, key, value, ttl, ) end |
#reset_stats ⇒ Object
Reset stats for each server.
289 290 291 292 293 |
# File 'lib/dalli/client.rb', line 289 def reset_stats ring.servers.map do |server| server.alive? ? server.request(:reset_stats) : nil end end |
#set(key, value, ttl = nil, options = nil) ⇒ Object
181 182 183 184 |
# File 'lib/dalli/client.rb', line 181 def set(key, value, ttl=nil, =nil) ttl ||= @options[:expires_in].to_i perform(:set, key, value, ttl, 0, ) end |
#stats(type = nil) ⇒ Object
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’ => { … } }
278 279 280 281 282 283 284 285 |
# File 'lib/dalli/client.rb', line 278 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 |
#touch(key, ttl = nil) ⇒ Object
Touch updates expiration time for a given key.
Returns true if key exists, otherwise nil.
268 269 270 271 272 |
# File 'lib/dalli/client.rb', line 268 def touch(key, ttl=nil) ttl ||= @options[:expires_in].to_i resp = perform(:touch, key, ttl) resp.nil? ? nil : true end |