Class: Dalli::Client

Inherits:
Object
  • Object
show all
Defined in:
lib/dalli/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 true if the operation succeeded.



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

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



225
226
227
 
# File 'lib/dalli/client.rb', line 225

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.



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

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



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

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) 


274
275
276
277
278
 
# File 'lib/dalli/client.rb', line 274

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 



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

def delete(key)
  perform(:delete, key)
end

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



166
167
168
169
170
171
172
173
174
 
# File 'lib/dalli/client.rb', line 166

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 



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

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, options=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
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
 
# File 'lib/dalli/client.rb', line 69

def get_multi(*keys)
  perform do
    return {} if keys.empty?
    options = nil
    options = keys.pop if keys.last.is_a?(Hash) || keys.last.nil?
    ring.lock do
      begin
        mapped_keys = keys.flatten.map {|a| validate_key(a.to_s)}
        groups = mapped_keys.flatten.group_by do |key|
          begin
            ring.server_for_key(key)
          rescue Dalli::RingError
            Dalli.logger.debug { "unable to get key #{key}" }
            nil
          end
        end
        if unfound_keys = groups.delete(nil)
          Dalli.logger.debug { "unable to get keys for #{unfound_keys.length} keys because no matching server was found" }
        end

        groups.each do |server, keys_for_server|
          begin
            # TODO: do this with the perform chokepoint?
            # But given the fact that fetching the response doesn't take place
            # in that slot it's misleading anyway. Need to move all of this method
            # into perform to be meaningful
            server.request(:send_multiget, keys_for_server)
          rescue DalliError, NetworkError => e
            Dalli.logger.debug { e.inspect }
            Dalli.logger.debug { "unable to get keys for server #{server.hostname}:#{server.port}" }
          end
        end

        servers = groups.keys
        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.options[: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|
              Dalli.logger.debug { "memcached at #{server.name} did not response within timeout" }
              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
      end
    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) 


254
255
256
257
258
 
# File 'lib/dalli/client.rb', line 254

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.



232
233
234
 
# File 'lib/dalli/client.rb', line 232

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.



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

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

#reset_stats ⇒ Object

Reset stats for each server.



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

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 



197
198
199
200
 
# File 'lib/dalli/client.rb', line 197

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



294
295
296
297
298
299
300
301
 
# File 'lib/dalli/client.rb', line 294

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.



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

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