Class: Dalli::Client

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

Defined Under Namespace

Modules: MemcacheClientCompatibility

Class Method Summary collapse

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 default to ‘localhost:11211’. Note that the MEMCACHE_SERVERS environment variable will override the servers parameter for use in managed environments like Heroku.

You can also provide a Unix socket as an argument, for example:

Dalli::Client.new("/tmp/memcached.sock")

Initial testing shows that Unix sockets are about twice as fast as TCP sockets but Unix sockets only work on localhost.

Options:

  • :failover - if a server is down, look for and store values on another server in the ring. Default: true.

  • :nonascii - allow the use of nonascii key names. Default: false.

  • :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

  • :compression - defaults to false, if true Dalli will compress values larger than 100 bytes before sending them to memcached.

  • :async - assume its running inside the EM reactor. Requires em-synchrony to be installed. Default: false.



33
34
35
36
37
38
 
# File 'lib/dalli/client.rb', line 33

def initialize(servers=nil, options={})
  @servers = env_servers || servers || 'localhost:11211'
  @options = { :expires_in => 0 }.merge(options)
  self.extend(Dalli::Client::MemcacheClientCompatibility) if Dalli::Client.compatibility_mode
  @ring = nil
end

Class Method Details

.compatibility_mode ⇒ Object

Turn on compatibility mode, which mixes in methods in memcache_client_compatibility.rb This value is set to true in memcache-client.rb.



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

def self.compatibility_mode
  @compatibility_mode ||= false
end

.compatibility_mode=(compatibility_mode) ⇒ Object 



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

def self.compatibility_mode=(compatibility_mode)
  require 'dalli/compatibility'
  @compatibility_mode = compatibility_mode
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.



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

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



166
167
168
 
# File 'lib/dalli/client.rb', line 166

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.



127
128
129
130
131
132
133
134
135
 
# File 'lib/dalli/client.rb', line 127

def cas(key, ttl=nil, options=nil, &block)
  ttl ||= @options[:expires_in]
  (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.



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

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 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) 


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

def decr(key, amt=1, ttl=nil, default=nil)
  raise ArgumentError, "Positive values only: #{amt}" if amt < 0
  ttl ||= @options[:expires_in]
  perform(:decr, key, amt, ttl, default)
end

#delete(key) ⇒ Object 



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

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

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



106
107
108
109
110
111
112
113
114
 
# File 'lib/dalli/client.rb', line 106

def fetch(key, ttl=nil, options=nil)
  ttl ||= @options[:expires_in]
  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 



177
178
179
180
 
# File 'lib/dalli/client.rb', line 177

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

#get(key, options = nil) ⇒ Object 



68
69
70
71
 
# File 'lib/dalli/client.rb', line 68

def get(key, options=nil)
  resp = perform(:get, key)
  (!resp || resp == 'Not found') ? nil : resp
end

#get_multi(*keys) ⇒ Object

Fetch multiple keys efficiently. Returns a hash of { ‘key’ => ‘value’, ‘key2’ => ‘value1’ }



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
 
# File 'lib/dalli/client.rb', line 76

def get_multi(*keys)
  return {} if keys.empty?
  options = nil
  options = keys.pop if keys.last.is_a?(Hash) || keys.last.nil?
  ring.lock do
    keys.flatten.each do |key|
      begin
        perform(:getkq, key)
      rescue DalliError, NetworkError => e
        Dalli.logger.debug { e.message }
        Dalli.logger.debug { "unable to get key #{key}" }
      end
    end

    values = {}
    ring.servers.each do |server|
      next unless server.alive?
      begin
        server.request(:noop).each_pair do |key, value|
          values[key_without_namespace(key)] = value
        end
      rescue DalliError, NetworkError => e
        Dalli.logger.debug { e.message }
        Dalli.logger.debug { "results from this server will be missing" }
      end
    end
    values
  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 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) 


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

def incr(key, amt=1, ttl=nil, default=nil)
  raise ArgumentError, "Positive values only: #{amt}" if amt < 0
  ttl ||= @options[:expires_in]
  perform(:incr, key, amt, 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.



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

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.



173
174
175
 
# File 'lib/dalli/client.rb', line 173

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.



154
155
156
157
 
# File 'lib/dalli/client.rb', line 154

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

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



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

def set(key, value, ttl=nil, options=nil)
  raise "Invalid API usage, please require 'dalli/memcache-client' for compatibility, see Upgrade.md" if options == true
  ttl ||= @options[:expires_in]
  perform(:set, key, value, ttl, 0, options)
end

#stats ⇒ Object

Collect the stats for each server. Returns a hash like { ‘hostname:port’ => { ‘stat1’ => ‘value1’, … }, ‘hostname2:port’ => { … } }



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

def stats
  values = {}
  ring.servers.each do |server|
    values["#{server.hostname}:#{server.port}"] = server.alive? ? server.request(:stats) : nil
  end
  values
end