Class: Dalli::Client

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

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'],
                :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, options={})
  @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.



110
111
112
113
# File 'lib/dalli/client.rb', line 110

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

#alive!Object

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



218
219
220
# File 'lib/dalli/client.rb', line 218

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.



130
131
132
# File 'lib/dalli/client.rb', line 130

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

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



92
93
94
95
96
97
98
99
100
# File 'lib/dalli/client.rb', line 92

def cas(key, ttl=nil, options=nil)
  ttl ||= @options[:expires_in].to_i
  (value, cas) = perform(:cas, key)
  value = (!value || value == 'Not found') ? nil : value
  if value
    newvalue = yield(value)
    perform(:set, key, newvalue, ttl, cas, options)
  end
end

#closeObject Also known as: reset

Close our connection to each server. If you perform another operation after this, the connections will be re-established.



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

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)


179
180
181
182
183
# File 'lib/dalli/client.rb', line 179

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



123
124
125
# File 'lib/dalli/client.rb', line 123

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.



53
54
55
# File 'lib/dalli/cas/client.rb', line 53

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

#fetch(key, ttl = nil, options = nil) ⇒ Object



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

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

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



141
142
143
144
# File 'lib/dalli/client.rb', line 141

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.



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

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



8
9
10
11
12
13
14
15
16
# File 'lib/dalli/cas/client.rb', line 8

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



60
61
62
63
64
65
66
67
68
69
# File 'lib/dalli/client.rb', line 60

def get_multi(*keys)
  return {} if keys.flatten.compact.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] }


24
25
26
27
28
29
30
31
32
# File 'lib/dalli/cas/client.rb', line 24

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.

Raises:

  • (ArgumentError)


159
160
161
162
163
# File 'lib/dalli/client.rb', line 159

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

#multiObject

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.



43
44
45
46
47
48
# File 'lib/dalli/client.rb', line 43

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.



137
138
139
# File 'lib/dalli/client.rb', line 137

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.



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

def replace(key, value, ttl=nil, options=nil)
  ttl ||= @options[:expires_in].to_i
  perform(:replace, key, value, 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.



46
47
48
49
# File 'lib/dalli/cas/client.rb', line 46

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_statsObject

Reset stats for each server.



210
211
212
213
214
# File 'lib/dalli/client.rb', line 210

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



102
103
104
105
# File 'lib/dalli/client.rb', line 102

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



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

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' => { … } }



199
200
201
202
203
204
205
206
# File 'lib/dalli/client.rb', line 199

def stats(type=nil)
  type = nil if ![nil, :items,:slabs,:settings].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.



189
190
191
192
193
# File 'lib/dalli/client.rb', line 189

def touch(key, ttl=nil)
  ttl ||= @options[:expires_in].to_i
  resp = perform(:touch, key, ttl)
  resp.nil? ? nil : true
end

#versionObject

Version of the memcache servers.



224
225
226
227
228
229
230
# File 'lib/dalli/client.rb', line 224

def version
  values = {}
  ring.servers.each do |server|
    values["#{server.hostname}:#{server.port}"] = 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



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

def with
  yield self
end