Class: Dalli::Client
- Inherits:
-
Object
- Object
- Dalli::Client
- Defined in:
- lib/dalli/client.rb,
lib/dalli/compatibility.rb
Defined Under Namespace
Modules: MemcacheClientCompatibility
Class Method Summary collapse
-
.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.
- .compatibility_mode=(compatibility_mode) ⇒ Object
Instance Method Summary collapse
-
#add(key, value, ttl = nil, options = nil) ⇒ Object
Conditionally add a key/value pair, if the key does not already exist on the server.
-
#append(key, value) ⇒ Object
Append value to the value already stored on the server for ‘key’.
-
#cas(key, ttl = nil, options = nil, &block) ⇒ Object
compare and swap values using optimistic locking.
-
#close ⇒ Object
(also: #reset)
Close our connection to each server.
-
#decr(key, amt = 1, ttl = nil, default = nil) ⇒ Object
Decr subtracts the given amount from the counter on the memcached server.
- #delete(key) ⇒ Object
- #fetch(key, ttl = nil, options = nil) ⇒ Object
- #flush(delay = 0) ⇒ Object (also: #flush_all)
- #get(key, options = nil) ⇒ Object
-
#get_multi(*keys) ⇒ Object
Fetch multiple keys efficiently.
-
#incr(key, amt = 1, ttl = nil, default = nil) ⇒ Object
Incr adds the given amount to the counter on the memcached server.
-
#initialize(servers = nil, options = {}) ⇒ Client
constructor
Dalli::Client is the main class which developers will use to interact with the memcached server.
-
#multi ⇒ Object
Turn on quiet aka noreply support.
-
#prepend(key, value) ⇒ Object
Prepend value to the value already stored on the server for ‘key’.
-
#replace(key, value, ttl = nil, options = nil) ⇒ Object
Conditionally add a key/value pair, only if the key already exists on the server.
- #set(key, value, ttl = nil, options = nil) ⇒ Object
-
#stats ⇒ Object
Collect the stats for each server.
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.
-
: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.
32 33 34 35 36 37 |
# File 'lib/dalli/client.rb', line 32 def initialize(servers=nil, ={}) @servers = env_servers || servers || 'localhost:11211' @options = { :expires_in => 0 }.merge() 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.
42 43 44 |
# File 'lib/dalli/client.rb', line 42 def self.compatibility_mode @compatibility_mode ||= false end |
.compatibility_mode=(compatibility_mode) ⇒ Object
46 47 48 49 |
# File 'lib/dalli/client.rb', line 46 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.
145 146 147 148 |
# File 'lib/dalli/client.rb', line 145 def add(key, value, ttl=nil, =nil) ttl ||= @options[:expires_in] perform(:add, key, value, ttl, ) 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.
165 166 167 |
# File 'lib/dalli/client.rb', line 165 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.
126 127 128 129 130 131 132 133 134 |
# File 'lib/dalli/client.rb', line 126 def cas(key, ttl=nil, =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, ) 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.
230 231 232 233 234 235 |
# File 'lib/dalli/client.rb', line 230 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.
210 211 212 213 214 |
# File 'lib/dalli/client.rb', line 210 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
158 159 160 |
# File 'lib/dalli/client.rb', line 158 def delete(key) perform(:delete, key) end |
#fetch(key, ttl = nil, options = nil) ⇒ Object
105 106 107 108 109 110 111 112 113 |
# File 'lib/dalli/client.rb', line 105 def fetch(key, ttl=nil, =nil) ttl ||= @options[:expires_in] val = get(key, ) if val.nil? && block_given? val = yield add(key, val, ttl, ) end val end |
#flush(delay = 0) ⇒ Object Also known as: flush_all
176 177 178 179 |
# File 'lib/dalli/client.rb', line 176 def flush(delay=0) time = -delay ring.servers.map { |s| s.request(:flush, time += delay) } end |
#get(key, options = nil) ⇒ Object
67 68 69 70 |
# File 'lib/dalli/client.rb', line 67 def get(key, =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’ }
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 |
# File 'lib/dalli/client.rb', line 75 def get_multi(*keys) return {} if keys.empty? = nil = 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. } 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. } 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.
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.
194 195 196 197 198 |
# File 'lib/dalli/client.rb', line 194 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.
60 61 62 63 64 65 |
# File 'lib/dalli/client.rb', line 60 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.
172 173 174 |
# File 'lib/dalli/client.rb', line 172 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.
153 154 155 156 |
# File 'lib/dalli/client.rb', line 153 def replace(key, value, ttl=nil, =nil) ttl ||= @options[:expires_in] perform(:replace, key, value, ttl, ) end |
#set(key, value, ttl = nil, options = nil) ⇒ Object
136 137 138 139 140 |
# File 'lib/dalli/client.rb', line 136 def set(key, value, ttl=nil, =nil) raise "Invalid API usage, please require 'dalli/memcache-client' for compatibility, see Upgrade.md" if == true ttl ||= @options[:expires_in] perform(:set, key, value, ttl, 0, ) end |
#stats ⇒ Object
Collect the stats for each server. Returns a hash like { ‘hostname:port’ => { ‘stat1’ => ‘value1’, … }, ‘hostname2:port’ => { … } }
219 220 221 222 223 224 225 |
# File 'lib/dalli/client.rb', line 219 def stats values = {} ring.servers.each do |server| values["#{server.hostname}:#{server.port}"] = server.alive? ? server.request(:stats) : nil end values end |