Class: Dalli::Client
- Inherits:
-
Object
- Object
- Dalli::Client
- Defined in:
- lib/dalli/client.rb,
lib/dalli/cas/client.rb
Constant Summary collapse
- CACHE_NILS =
{cache_nils: true}.freeze
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.
-
#alive! ⇒ Object
Make sure memcache servers are alive, or raise an Dalli::RingError.
-
#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.
-
#cas!(key, ttl = nil, options = nil, &block) ⇒ Object
like #cas, but will yield to the block whether or not the value already exists.
-
#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
-
#delete_cas(key, cas = 0) ⇒ Object
Delete a key/value pair, verifying existing CAS.
-
#fetch(key, ttl = nil, options = nil) ⇒ Object
Fetch the value associated with the key.
- #flush(delay = 0) ⇒ Object (also: #flush_all)
-
#get(key, options = nil) ⇒ Object
Get the value associated with the key.
-
#get_cas(key) ⇒ Object
Get the value and CAS ID associated with the key.
-
#get_multi(*keys) ⇒ Object
Fetch multiple keys efficiently.
-
#get_multi_cas(*keys) ⇒ Object
Fetch multiple keys efficiently, including available metadata such as CAS.
-
#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.
-
#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.
-
#replace_cas(key, value, cas, ttl = nil, options = nil) ⇒ Object
Conditionally add a key/value pair, verifying existing CAS, 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
-
#set_cas(key, value, cas, ttl = nil, options = nil) ⇒ Object
Set the key-value pair, verifying existing CAS.
-
#stats(type = nil) ⇒ Object
Collect the stats for each server.
-
#touch(key, ttl = nil) ⇒ Object
Touch updates expiration time for a given key.
-
#version ⇒ Object
Version of the memcache servers.
-
#with {|_self| ... } ⇒ Object
Stub method so a bare Dalli client can pretend to be a connection pool.
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', '/var/run/memcached/socket'],
: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. Dalli also supports the ability to connect to Memcached on localhost through a UNIX socket. To use this functionality, use a full pathname (beginning with a slash character ‘/’) in place of the “host:port” pair in the server configuration.
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
-
:cache_nils - defaults to false, if true Dalli will not treat cached nil values as ‘not found’ for #fetch operations.
33 34 35 36 37 |
# File 'lib/dalli/client.rb', line 33 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 truthy if the operation succeeded.
136 137 138 |
# File 'lib/dalli/client.rb', line 136 def add(key, value, ttl=nil, =nil) perform(:add, key, value, ttl_or_default(ttl), ) end |
#alive! ⇒ Object
Make sure memcache servers are alive, or raise an Dalli::RingError
239 240 241 |
# File 'lib/dalli/client.rb', line 239 def alive! ring.server_for_key("") 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.
154 155 156 |
# File 'lib/dalli/client.rb', line 154 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.
114 115 116 |
# File 'lib/dalli/client.rb', line 114 def cas(key, ttl=nil, =nil, &block) cas_core(key, false, ttl, , &block) end |
#cas!(key, ttl = nil, options = nil, &block) ⇒ Object
like #cas, but will yield to the block whether or not the value already exists.
Returns:
-
false if the value was changed by someone else.
-
true if the value was successfully updated.
125 126 127 |
# File 'lib/dalli/client.rb', line 125 def cas!(key, ttl=nil, =nil, &block) cas_core(key, true, ttl, , &block) 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.
256 257 258 259 260 261 |
# File 'lib/dalli/client.rb', line 256 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.
202 203 204 205 |
# File 'lib/dalli/client.rb', line 202 def decr(key, amt=1, ttl=nil, default=nil) raise ArgumentError, "Positive values only: #{amt}" if amt < 0 perform(:decr, key, amt.to_i, ttl_or_default(ttl), default) end |
#delete(key) ⇒ Object
147 148 149 |
# File 'lib/dalli/client.rb', line 147 def delete(key) perform(:delete, key, 0) end |
#delete_cas(key, cas = 0) ⇒ Object
Delete a key/value pair, verifying existing CAS. Returns true if succeeded, and falsy otherwise.
54 55 56 |
# File 'lib/dalli/cas/client.rb', line 54 def delete_cas(key, cas=0) perform(:delete, key, cas) end |
#fetch(key, ttl = nil, options = nil) ⇒ Object
Fetch the value associated with the key. If a value is found, then it is returned.
If a value is not found and no block is given, then nil is returned.
If a value is not found (or if the found value is nil and :cache_nils is false) and a block is given, the block will be invoked and its return value written to the cache and returned.
90 91 92 93 94 95 96 97 98 99 100 101 |
# File 'lib/dalli/client.rb', line 90 def fetch(key, ttl=nil, =nil) = .nil? ? CACHE_NILS : .merge(CACHE_NILS) if @options[:cache_nils] val = get(key, ) not_found = @options[:cache_nils] ? val == Dalli::Server::NOT_FOUND : val.nil? if not_found && block_given? val = yield add(key, val, ttl_or_default(ttl), ) end val end |
#flush(delay = 0) ⇒ Object Also known as: flush_all
165 166 167 168 |
# File 'lib/dalli/client.rb', line 165 def flush(delay=0) time = -delay ring.servers.map { |s| s.request(:flush, time += delay) } end |
#get(key, options = nil) ⇒ Object
Get the value associated with the key. If a value is not found, then nil
is returned.
58 59 60 |
# File 'lib/dalli/client.rb', line 58 def get(key, =nil) perform(:get, key, ) end |
#get_cas(key) ⇒ Object
Get the value and CAS ID associated with the key. If a block is provided, value and CAS will be passed to the block.
9 10 11 12 13 14 15 16 17 |
# File 'lib/dalli/cas/client.rb', line 9 def get_cas(key) (value, cas) = perform(:cas, key) value = (!value || value == 'Not found') ? nil : value if block_given? yield value, cas else [value, cas] end end |
#get_multi(*keys) ⇒ Object
Fetch multiple keys efficiently. If a block is given, yields key/value pairs one at a time. Otherwise returns a hash of { ‘key’ => ‘value’, ‘key2’ => ‘value1’ }
66 67 68 69 70 71 72 73 74 75 76 77 78 |
# File 'lib/dalli/client.rb', line 66 def get_multi(*keys) check_keys = keys.flatten check_keys.compact! return {} if check_keys.empty? if block_given? get_multi_yielder(keys) {|k, data| yield k, data.first} else Hash.new.tap do |hash| get_multi_yielder(keys) {|k, data| hash[k] = data.first} end end end |
#get_multi_cas(*keys) ⇒ Object
Fetch multiple keys efficiently, including available metadata such as CAS. If a block is given, yields key/data pairs one a time. Data is an array:
- value, cas_id
-
If no block is given, returns a hash of
{ 'key' => [value, cas_id] }
25 26 27 28 29 30 31 32 33 |
# File 'lib/dalli/cas/client.rb', line 25 def get_multi_cas(*keys) if block_given? get_multi_yielder(keys) {|*args| yield(*args)} else Hash.new.tap do |hash| get_multi_yielder(keys) {|k, data| hash[k] = data} 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.
183 184 185 186 |
# File 'lib/dalli/client.rb', line 183 def incr(key, amt=1, ttl=nil, default=nil) raise ArgumentError, "Positive values only: #{amt}" if amt < 0 perform(:incr, key, amt.to_i, ttl_or_default(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.
48 49 50 51 52 53 |
# File 'lib/dalli/client.rb', line 48 def multi old, Thread.current[:dalli_multi] = Thread.current[:dalli_multi], true yield ensure Thread.current[:dalli_multi] = old 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.
161 162 163 |
# File 'lib/dalli/client.rb', line 161 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 truthy if the operation succeeded.
143 144 145 |
# File 'lib/dalli/client.rb', line 143 def replace(key, value, ttl=nil, =nil) perform(:replace, key, value, ttl_or_default(ttl), 0, ) end |
#replace_cas(key, value, cas, ttl = nil, options = nil) ⇒ Object
Conditionally add a key/value pair, verifying existing CAS, only if the key already exists on the server. Returns the new CAS value if the operation succeeded, or falsy otherwise.
47 48 49 50 |
# File 'lib/dalli/cas/client.rb', line 47 def replace_cas(key, value, cas, ttl=nil, =nil) ttl ||= @options[:expires_in].to_i perform(:replace, key, value, ttl, cas, ) end |
#reset_stats ⇒ Object
Reset stats for each server.
231 232 233 234 235 |
# File 'lib/dalli/client.rb', line 231 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
129 130 131 |
# File 'lib/dalli/client.rb', line 129 def set(key, value, ttl=nil, =nil) perform(:set, key, value, ttl_or_default(ttl), 0, ) end |
#set_cas(key, value, cas, ttl = nil, options = nil) ⇒ Object
Set the key-value pair, verifying existing CAS. Returns the resulting CAS value if succeeded, and falsy otherwise.
38 39 40 41 |
# File 'lib/dalli/cas/client.rb', line 38 def set_cas(key, value, cas, ttl=nil, =nil) ttl ||= @options[:expires_in].to_i perform(:set, key, value, ttl, cas, ) end |
#stats(type = nil) ⇒ Object
Collect the stats for each server. You can optionally pass a type including :items, :slabs or :settings to get specific stats Returns a hash like { ‘hostname:port’ => { ‘stat1’ => ‘value1’, … }, ‘hostname2:port’ => { … } }
220 221 222 223 224 225 226 227 |
# File 'lib/dalli/client.rb', line 220 def stats(type=nil) type = nil if ![nil, :items,:slabs,:settings].include? type values = {} ring.servers.each do |server| values["#{server.name}"] = 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.
211 212 213 214 |
# File 'lib/dalli/client.rb', line 211 def touch(key, ttl=nil) resp = perform(:touch, key, ttl_or_default(ttl)) resp.nil? ? nil : true end |
#version ⇒ Object
Version of the memcache servers.
245 246 247 248 249 250 251 |
# File 'lib/dalli/client.rb', line 245 def version values = {} ring.servers.each do |server| values["#{server.name}"] = server.alive? ? server.request(:version) : nil end values end |
#with {|_self| ... } ⇒ Object
Stub method so a bare Dalli client can pretend to be a connection pool.
265 266 267 |
# File 'lib/dalli/client.rb', line 265 def with yield self end |