Class: Dalli::Client

Inherits:
Object
  • Object
show all
Defined in:
lib/dalli/client.rb

Constant Summary collapse

CACHE_NILS = 
{cache_nils: true}.freeze

Instance Method Summary collapse

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.

  • :digest_class - defaults to Digest::MD5, allows you to pass in an object that responds to the hexdigest method, useful for injecting a FIPS compliant hash object.

  • :protocol_implementation - defaults to Dalli::Protocol::Binary which uses the binary protocol. Allows you to pass an alternative implementation using another protocol.



35
36
37
38
39
40
 
# File 'lib/dalli/client.rb', line 35

def initialize(servers = nil, options = {})
  validate_servers_arg(servers)
  @servers = normalize_servers(servers || ENV["MEMCACHE_SERVERS"] || "127.0.0.1:11211")
  @options = normalize_options(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.



139
140
141
 
# File 'lib/dalli/client.rb', line 139

def add(key, value, ttl = nil, options = nil)
  perform(:add, key, value, ttl_or_default(ttl), options)
end

#alive! ⇒ Object

Make sure memcache servers are alive, or raise an Dalli::RingError



250
251
252
 
# File 'lib/dalli/client.rb', line 250

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.



157
158
159
 
# File 'lib/dalli/client.rb', line 157

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.



117
118
119
 
# File 'lib/dalli/client.rb', line 117

def cas(key, ttl = nil, options = nil, &block)
  cas_core(key, false, ttl, options, &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.



128
129
130
 
# File 'lib/dalli/client.rb', line 128

def cas!(key, ttl = nil, options = nil, &block)
  cas_core(key, true, ttl, options, &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.



319
320
321
322
323
324
 
# File 'lib/dalli/client.rb', line 319

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.

Raises:

  • (ArgumentError) 


205
206
207
208
 
# File 'lib/dalli/client.rb', line 205

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 



150
151
152
 
# File 'lib/dalli/client.rb', line 150

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.



312
313
314
 
# File 'lib/dalli/client.rb', line 312

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.



93
94
95
96
97
98
99
100
101
102
103
104
 
# File 'lib/dalli/client.rb', line 93

def fetch(key, ttl = nil, options = nil)
  options = options.nil? ? CACHE_NILS : options.merge(CACHE_NILS) if @options[:cache_nils]
  val = get(key, options)
  not_found = @options[:cache_nils] ?
    val == Dalli::Protocol::NOT_FOUND :
    val.nil?
  if not_found && block_given?
    val = yield
    add(key, val, ttl_or_default(ttl), options)
  end
  val
end

#flush(delay = 0) ⇒ Object Also known as: flush_all 



168
169
170
171
 
# File 'lib/dalli/client.rb', line 168

def flush(delay = 0)
  time = -delay
  ring.servers.map { |s| s.request(:flush, time += delay) }
end

#gat(key, ttl = nil) ⇒ Object

Gat (get and touch) fetch an item and simultaneously update its expiration time.

If a value is not found, then nil is returned.



223
224
225
 
# File 'lib/dalli/client.rb', line 223

def gat(key, ttl = nil)
  perform(:gat, key, ttl_or_default(ttl))
end

#get(key, options = nil) ⇒ Object

Get the value associated with the key. If a value is not found, then nil is returned.



61
62
63
 
# File 'lib/dalli/client.rb', line 61

def get(key, options = nil)
  perform(:get, key, options)
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.



267
268
269
270
271
272
273
274
275
 
# File 'lib/dalli/client.rb', line 267

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’ }



69
70
71
72
73
74
75
76
77
78
79
80
81
 
# File 'lib/dalli/client.rb', line 69

def get_multi(*keys)
  keys.flatten!
  keys.compact!

  return {} if keys.empty?
  if block_given?
    get_multi_yielder(keys) { |k, data| yield k, data.first }
  else
    {}.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] }



283
284
285
286
287
288
289
290
291
 
# File 'lib/dalli/client.rb', line 283

def get_multi_cas(*keys)
  if block_given?
    get_multi_yielder(keys) { |*args| yield(*args) }
  else
    {}.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.

Raises:

  • (ArgumentError) 


186
187
188
189
 
# File 'lib/dalli/client.rb', line 186

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.



51
52
53
54
55
56
 
# File 'lib/dalli/client.rb', line 51

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.



164
165
166
 
# File 'lib/dalli/client.rb', line 164

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.



146
147
148
 
# File 'lib/dalli/client.rb', line 146

def replace(key, value, ttl = nil, options = nil)
  perform(:replace, key, value, ttl_or_default(ttl), 0, options)
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.



305
306
307
308
 
# File 'lib/dalli/client.rb', line 305

def replace_cas(key, value, cas, ttl = nil, options = nil)
  ttl ||= @options[:expires_in].to_i
  perform(:replace, key, value, ttl, cas, options)
end

#reset_stats ⇒ Object

Reset stats for each server.



242
243
244
245
246
 
# File 'lib/dalli/client.rb', line 242

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 



132
133
134
 
# File 'lib/dalli/client.rb', line 132

def set(key, value, ttl = nil, options = nil)
  perform(:set, key, value, ttl_or_default(ttl), 0, options)
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.



296
297
298
299
 
# File 'lib/dalli/client.rb', line 296

def set_cas(key, value, cas, ttl = nil, options = nil)
  ttl ||= @options[:expires_in].to_i
  perform(:set, key, value, ttl, cas, options)
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’ => { … } }



231
232
233
234
235
236
237
238
 
# File 'lib/dalli/client.rb', line 231

def stats(type = nil)
  type = nil unless [nil, :items, :slabs, :settings].include? type
  values = {}
  ring.servers.each do |server|
    values[server.name.to_s] = 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.



214
215
216
217
 
# File 'lib/dalli/client.rb', line 214

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.



256
257
258
259
260
261
262
 
# File 'lib/dalli/client.rb', line 256

def version
  values = {}
  ring.servers.each do |server|
    values[server.name.to_s] = server.alive? ? server.request(:version) : nil
  end
  values
end