Class: Dalli::Client

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

Overview

Dalli::Client is the main class which developers will use to interact with Memcached.

Constant Summary collapse

ALLOWED_STAT_KEYS = 
%i[items slabs settings].freeze
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'],
                  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 - if true Dalli will compress values larger than compression_min_size bytes before sending them

    to memcached.  Default: true.

  • :compression_min_size - the minimum size (in bytes) for which Dalli will compress values sent to Memcached.

    Defaults to 4K.

  • :serializer - defaults to Marshal

  • :compressor - defaults to Dalli::Compressor, a Zlib-based implementation

  • :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 - one of either :binary or :meta, defaulting to :binary. This sets the protocol that Dalli uses

    to communicate with memcached.



49
50
51
52
53
54
 
# File 'lib/dalli/client.rb', line 49

def initialize(servers = nil, options = {})
  @normalized_servers = ::Dalli::ServersArgNormalizer.normalize_servers(servers)
  @options = normalize_options(options)
  @key_manager = ::Dalli::KeyManager.new(@options)
  @ring = nil
end

Instance Method Details

#add(key, value, ttl = nil, req_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.



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

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

#alive! ⇒ Object

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



342
343
344
 
# File 'lib/dalli/client.rb', line 342

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.



246
247
248
 
# File 'lib/dalli/client.rb', line 246

def append(key, value)
  perform(:append, key, value.to_s)
end

#cache_nils ⇒ Object 



361
362
363
 
# File 'lib/dalli/client.rb', line 361

def cache_nils
  @options[:cache_nils]
end

#cas(key, ttl = nil, req_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.



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

def cas(key, ttl = nil, req_options = nil, &block)
  cas_core(key, false, ttl, req_options, &block)
end

#cas!(key, ttl = nil, req_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.



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

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



349
350
351
352
 
# File 'lib/dalli/client.rb', line 349

def close
  @ring&.close
  @ring = nil
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.

If the value already exists, it must have been set with raw: true



292
293
294
295
296
 
# File 'lib/dalli/client.rb', line 292

def decr(key, amt = 1, ttl = nil, default = nil)
  check_positive!(amt)

  perform(:decr, key, amt.to_i, ttl_or_default(ttl), default)
end

#delete(key) ⇒ Object 



239
240
241
 
# File 'lib/dalli/client.rb', line 239

def delete(key)
  delete_cas(key, 0)
end

#delete_cas(key, cas = 0) ⇒ Object

Delete a key/value pair, verifying existing CAS. Returns true if succeeded, and falsy otherwise.



235
236
237
 
# File 'lib/dalli/client.rb', line 235

def delete_cas(key, cas = 0)
  perform(:delete, key, cas)
end

#fetch(key, ttl = nil, req_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.



137
138
139
140
141
142
143
144
145
 
# File 'lib/dalli/client.rb', line 137

def fetch(key, ttl = nil, req_options = nil)
  req_options = req_options.nil? ? CACHE_NILS : req_options.merge(CACHE_NILS) if cache_nils
  val = get(key, req_options)
  return val unless block_given? && not_found?(val)

  new_val = yield
  add(key, new_val, ttl_or_default(ttl), req_options)
  new_val
end

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

Flush the memcached server, at ‘delay’ seconds in the future. Delay defaults to zero seconds, which means an immediate flush.



302
303
304
 
# File 'lib/dalli/client.rb', line 302

def flush(delay = 0)
  ring.servers.map { |s| s.request(:flush, 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.



71
72
73
 
# File 'lib/dalli/client.rb', line 71

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

#get(key, req_options = nil) ⇒ Object

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



63
64
65
 
# File 'lib/dalli/client.rb', line 63

def get(key, req_options = nil)
  perform(:get, key, req_options)
end

#get_cas(key) {|value, cas| ... } ⇒ 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.

Yields:



87
88
89
90
91
92
 
# File 'lib/dalli/client.rb', line 87

def get_cas(key)
  (value, cas) = perform(:cas, key)
  return [value, cas] unless block_given?

  yield value, cas
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’ }



98
99
100
101
102
103
104
105
106
107
108
109
110
111
 
# File 'lib/dalli/client.rb', line 98

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

  return {} if keys.empty?

  if block_given?
    pipelined_getter.process(keys) { |k, data| yield k, data.first }
  else
    {}.tap do |hash|
      pipelined_getter.process(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] }



119
120
121
122
123
124
125
126
127
 
# File 'lib/dalli/client.rb', line 119

def get_multi_cas(*keys)
  if block_given?
    pipelined_getter.process(keys) { |*args| yield(*args) }
  else
    {}.tap do |hash|
      pipelined_getter.process(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.

If the value already exists, it must have been set with raw: true



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

def incr(key, amt = 1, ttl = nil, default = nil)
  check_positive!(amt)

  perform(:incr, key, amt.to_i, ttl_or_default(ttl), default)
end

#not_found?(val) ⇒ Boolean

Returns:

  • (Boolean) 


357
358
359
 
# File 'lib/dalli/client.rb', line 357

def not_found?(val)
  cache_nils ? val == ::Dalli::NOT_FOUND : val.nil?
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.



253
254
255
 
# File 'lib/dalli/client.rb', line 253

def prepend(key, value)
  perform(:prepend, key, value.to_s)
end

#quiet ⇒ Object Also known as: multi

Turn on quiet aka noreply support for a number of memcached operations.

All relevant operations within this block will be effectively pipelined as Dalli will use ‘quiet’ versions. The invoked methods will all return nil, rather than their usual response. Method latency will be substantially lower, as the caller will not be blocking on responses.

Currently supports storage (set, add, replace, append, prepend), arithmetic (incr, decr), flush and delete operations. Use of unsupported operations inside a block will raise an error.

Any error replies will be discarded at the end of the block, and Dalli client methods invoked inside the block will not have return values



190
191
192
193
194
195
196
197
 
# File 'lib/dalli/client.rb', line 190

def quiet
  old = Thread.current[::Dalli::QUIET]
  Thread.current[::Dalli::QUIET] = true
  yield
ensure
  @ring&.pipeline_consume_and_ignore_responses
  Thread.current[::Dalli::QUIET] = old
end

#replace(key, value, ttl = nil, req_options = nil) ⇒ Object

Conditionally add a key/value pair, only if the key already exists on the server. Returns truthy if the operation succeeded.



221
222
223
 
# File 'lib/dalli/client.rb', line 221

def replace(key, value, ttl = nil, req_options = nil)
  replace_cas(key, value, 0, ttl, req_options)
end

#replace_cas(key, value, cas, ttl = nil, req_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.



229
230
231
 
# File 'lib/dalli/client.rb', line 229

def replace_cas(key, value, cas, ttl = nil, req_options = nil)
  perform(:replace, key, value, ttl_or_default(ttl), cas, req_options)
end

#reset_stats ⇒ Object

Reset stats for each server.



324
325
326
327
328
 
# File 'lib/dalli/client.rb', line 324

def reset_stats
  ring.servers.map do |server|
    server.alive? ? server.request(:reset_stats) : nil
  end
end

#set(key, value, ttl = nil, req_options = nil) ⇒ Object 



200
201
202
 
# File 'lib/dalli/client.rb', line 200

def set(key, value, ttl = nil, req_options = nil)
  set_cas(key, value, 0, ttl, req_options)
end

#set_cas(key, value, cas, ttl = nil, req_options = nil) ⇒ Object

Set the key-value pair, verifying existing CAS. Returns the resulting CAS value if succeeded, and falsy otherwise.



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

def set_cas(key, value, cas, ttl = nil, req_options = nil)
  perform(:set, key, value, ttl_or_default(ttl), cas, req_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’ => { … } }



313
314
315
316
317
318
319
320
 
# File 'lib/dalli/client.rb', line 313

def stats(type = nil)
  type = nil unless ALLOWED_STAT_KEYS.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.



79
80
81
82
 
# File 'lib/dalli/client.rb', line 79

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.



332
333
334
335
336
337
338
 
# File 'lib/dalli/client.rb', line 332

def version
  values = {}
  ring.servers.each do |server|
    values[server.name.to_s] = 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.

Yields:

  • (_self)

Yield Parameters:

  • _self (Dalli::Client) —

    the object that the method was called on



366
367
368
 
# File 'lib/dalli/client.rb', line 366

def with
  yield self
end