memcache-auth 0.2

Sign up to get free protection for your applications and to get access to all the features.
data/lib/memcached.rb ADDED
@@ -0,0 +1,32 @@
1
+
2
+ =begin rdoc
3
+ The generated SWIG module for accessing libmemcached's C API.
4
+
5
+ Includes the full set of libmemcached static methods (as defined in <tt>$INCLUDE_PATH/libmemcached/memcached.h</tt>), and classes for the available structs:
6
+
7
+ * <b>Rlibmemcached::MemcachedResultSt</b>
8
+ * <b>Rlibmemcached::MemcachedServerSt</b>
9
+ * <b>Rlibmemcached::MemcachedSt</b>
10
+ * <b>Rlibmemcached::MemcachedStatSt</b>
11
+ * <b>Rlibmemcached::MemcachedStringSt</b>
12
+
13
+ A number of SWIG typemaps and C helper methods are also defined in <tt>ext/libmemcached.i</tt>.
14
+
15
+ =end
16
+ module Rlibmemcached
17
+ end
18
+
19
+ require 'rlibmemcached'
20
+
21
+ class Memcached
22
+ Lib = Rlibmemcached
23
+ raise "libmemcached 0.35 required; you somehow linked to #{Lib.memcached_lib_version}." unless "0.35" == Lib.memcached_lib_version
24
+ VERSION = File.read("#{File.dirname(__FILE__)}/../CHANGELOG")[/v([\d\.]+)\./, 1]
25
+ end
26
+
27
+ require 'memcached/integer'
28
+ require 'memcached/exceptions'
29
+ require 'memcached/behaviors'
30
+ require 'memcached/auth'
31
+ require 'memcached/memcached'
32
+ require 'memcached/rails'
@@ -0,0 +1,17 @@
1
+ class Memcached
2
+ def destroy_credentials
3
+ if options[:credentials] != nil
4
+ check_return_code(Lib.memcached_destroy_sasl_auth_data(@struct))
5
+ end
6
+ end
7
+
8
+ def set_credentials
9
+ # If credentials aren't provided, try to get them from the environment
10
+ print options[:credentials]
11
+ if options[:credentials] != nil
12
+ username, password = options[:credentials]
13
+ check_return_code(Lib.memcached_set_sasl_auth_data(@struct, username, password))
14
+ end
15
+ end
16
+ end
17
+
@@ -0,0 +1,78 @@
1
+
2
+ class Memcached
3
+
4
+ #:stopdoc:
5
+
6
+ def self.load_constants(prefix, hash = {})
7
+ Lib.constants.grep(/^#{prefix}/).each do |const_name|
8
+ hash[const_name[prefix.length..-1].downcase.to_sym] = Lib.const_get(const_name)
9
+ end
10
+ hash
11
+ end
12
+
13
+ BEHAVIORS = load_constants("MEMCACHED_BEHAVIOR_")
14
+
15
+ BEHAVIOR_VALUES = {
16
+ false => 0,
17
+ true => 1
18
+ }
19
+
20
+ HASH_VALUES = {}
21
+ BEHAVIOR_VALUES.merge!(load_constants("MEMCACHED_HASH_", HASH_VALUES))
22
+
23
+ DISTRIBUTION_VALUES = {}
24
+ BEHAVIOR_VALUES.merge!(load_constants("MEMCACHED_DISTRIBUTION_", DISTRIBUTION_VALUES))
25
+
26
+ DIRECT_VALUE_BEHAVIORS = [:retry_timeout, :connect_timeout, :rcv_timeout, :socket_recv_size, :poll_timeout, :socket_send_size, :server_failure_limit]
27
+
28
+ CONVERSION_FACTORS = {
29
+ :rcv_timeout => 1_000_000,
30
+ :poll_timeout => 1_000,
31
+ :connect_timeout => 1_000
32
+ }
33
+
34
+ #:startdoc:
35
+
36
+ private
37
+
38
+ # Set a behavior option for this Memcached instance. Accepts a Symbol <tt>behavior</tt> and either <tt>true</tt>, <tt>false</tt>, or a Symbol for <tt>value</tt>. Arguments are validated and converted into integers for the struct setter method.
39
+ def set_behavior(behavior, value) #:doc:
40
+ raise ArgumentError, "No behavior #{behavior.inspect}" unless b_id = BEHAVIORS[behavior]
41
+
42
+ # Scoped validations; annoying
43
+ msg = "Invalid behavior value #{value.inspect} for #{behavior.inspect}"
44
+ case behavior
45
+ when :hash then raise(ArgumentError, msg) unless HASH_VALUES[value]
46
+ when :distribution then raise(ArgumentError, msg) unless DISTRIBUTION_VALUES[value]
47
+ when *DIRECT_VALUE_BEHAVIORS then raise(ArgumentError, msg) unless value.is_a?(Numeric) and value >= 0
48
+ else
49
+ raise(ArgumentError, msg) unless BEHAVIOR_VALUES[value]
50
+ end
51
+
52
+ lib_value = BEHAVIOR_VALUES[value] || (value * (CONVERSION_FACTORS[behavior] || 1)).to_i
53
+ #STDERR.puts "Setting #{behavior}:#{b_id} => #{value} (#{lib_value})"
54
+ Lib.memcached_behavior_set(@struct, b_id, lib_value)
55
+ #STDERR.puts " -> set to #{get_behavior(behavior).inspect}"
56
+ end
57
+
58
+ # Get a behavior value for this Memcached instance. Accepts a Symbol.
59
+ def get_behavior(behavior)
60
+ raise ArgumentError, "No behavior #{behavior.inspect}" unless b_id = BEHAVIORS[behavior]
61
+ value = Lib.memcached_behavior_get(@struct, b_id)
62
+
63
+ if BEHAVIOR_VALUES.invert.has_key?(value)
64
+ # False, nil are valid values so we can not rely on direct lookups
65
+ case behavior
66
+ # Scoped values; still annoying
67
+ when :hash then HASH_VALUES.invert[value]
68
+ when :distribution then DISTRIBUTION_VALUES.invert[value]
69
+ when *DIRECT_VALUE_BEHAVIORS then value
70
+ else
71
+ BEHAVIOR_VALUES.invert[value]
72
+ end
73
+ else
74
+ value
75
+ end
76
+ end
77
+
78
+ end
@@ -0,0 +1,84 @@
1
+
2
+ class Memcached
3
+
4
+ =begin rdoc
5
+
6
+ Superclass for all Memcached runtime exceptions.
7
+
8
+ Subclasses correspond one-to-one with server response strings or libmemcached errors. For example, raising <b>Memcached::NotFound</b> means that the server returned <tt>"NOT_FOUND\r\n"</tt>.
9
+
10
+ == Subclasses
11
+
12
+ * Memcached::ABadKeyWasProvidedOrCharactersOutOfRange
13
+ * Memcached::AKeyLengthOfZeroWasProvided
14
+ * Memcached::ATimeoutOccurred
15
+ * Memcached::ActionNotSupported
16
+ * Memcached::ActionQueued
17
+ * Memcached::ClientError
18
+ * Memcached::ConnectionBindFailure
19
+ * Memcached::ConnectionDataDoesNotExist
20
+ * Memcached::ConnectionDataExists
21
+ * Memcached::ConnectionFailure
22
+ * Memcached::ConnectionSocketCreateFailure
23
+ * Memcached::CouldNotOpenUnixSocket
24
+ * Memcached::EncounteredAnUnknownStatKey
25
+ * Memcached::Failure
26
+ * Memcached::FetchWasNotCompleted
27
+ * Memcached::HostnameLookupFailure
28
+ * Memcached::ItemValue
29
+ * Memcached::MemoryAllocationFailure
30
+ * Memcached::NoServersDefined
31
+ * Memcached::NotFound
32
+ * Memcached::NotStored
33
+ * Memcached::PartialRead
34
+ * Memcached::ProtocolError
35
+ * Memcached::ReadFailure
36
+ * Memcached::ServerDelete
37
+ * Memcached::ServerEnd
38
+ * Memcached::ServerError
39
+ * Memcached::ServerIsMarkedDead
40
+ * Memcached::ServerValue
41
+ * Memcached::SomeErrorsWereReported
42
+ * Memcached::StatValue
43
+ * Memcached::SystemError
44
+ * Memcached::TheHostTransportProtocolDoesNotMatchThatOfTheClient
45
+ * Memcached::UnknownReadFailure
46
+ * Memcached::WriteFailure
47
+
48
+ =end
49
+ class Error < RuntimeError
50
+ attr_accessor :no_backtrace
51
+
52
+ def set_backtrace(*args)
53
+ @no_backtrace ? [] : super
54
+ end
55
+
56
+ def backtrace(*args)
57
+ @no_backtrace ? [] : super
58
+ end
59
+ end
60
+
61
+ #:stopdoc:
62
+
63
+ class << self
64
+ private
65
+ def camelize(string)
66
+ string.downcase.gsub('/', ' or ').split(' ').map {|s| s.capitalize}.join
67
+ end
68
+ end
69
+
70
+ ERRNO_HASH = Hash[*Errno.constants.map{ |c| [Errno.const_get(c)::Errno, Errno.const_get(c).new.message] }.flatten]
71
+
72
+ EXCEPTIONS = []
73
+ EMPTY_STRUCT = Rlibmemcached::MemcachedSt.new
74
+ Rlibmemcached.memcached_create(EMPTY_STRUCT)
75
+
76
+ # Generate exception classes
77
+ Rlibmemcached::MEMCACHED_MAXIMUM_RETURN.times do |index|
78
+ description = Rlibmemcached.memcached_strerror(EMPTY_STRUCT, index).gsub("!", "")
79
+ exception_class = eval("class #{camelize(description)} < Error; self; end")
80
+ EXCEPTIONS << exception_class
81
+ end
82
+
83
+ #:startdoc:
84
+ end
@@ -0,0 +1,6 @@
1
+
2
+ class Integer
3
+ def tv_sec
4
+ self
5
+ end
6
+ end
@@ -0,0 +1,523 @@
1
+
2
+ =begin rdoc
3
+ The Memcached client class.
4
+ =end
5
+ class Memcached
6
+
7
+ FLAGS = 0x0
8
+
9
+ DEFAULTS = {
10
+ :hash => :fnv1_32,
11
+ :no_block => false,
12
+ :distribution => :consistent_ketama,
13
+ :ketama_weighted => true,
14
+ :buffer_requests => false,
15
+ :cache_lookups => true,
16
+ :support_cas => false,
17
+ :tcp_nodelay => false,
18
+ :show_backtraces => false,
19
+ :retry_timeout => 30,
20
+ :timeout => 0.25,
21
+ :rcv_timeout => nil,
22
+ :poll_timeout => nil,
23
+ :connect_timeout => 2,
24
+ :prefix_key => nil,
25
+ :hash_with_prefix_key => true,
26
+ :default_ttl => 604800,
27
+ :default_weight => 8,
28
+ :sort_hosts => false,
29
+ :auto_eject_hosts => true,
30
+ :server_failure_limit => 2,
31
+ :verify_key => true,
32
+ :use_udp => false,
33
+ :binary_protocol => false,
34
+ :credentials => nil
35
+ }
36
+
37
+ #:stopdoc:
38
+ IGNORED = 0
39
+ #:startdoc:
40
+
41
+ attr_reader :options # Return the options Hash used to configure this instance.
42
+
43
+ ###### Configuration
44
+
45
+ =begin rdoc
46
+ Create a new Memcached instance. Accepts string or array of server strings, as well an an optional configuration hash.
47
+
48
+ Memcached.new('localhost', ...) # A single server
49
+ Memcached.new(['web001:11212', 'web002:11212'], ...) # Two servers with custom ports
50
+ Memcached.new(['web001:11211:2', 'web002:11211:8'], ...) # Two servers with default ports and explicit weights
51
+
52
+ Weights only affect Ketama hashing. If you use Ketama hashing and don't specify a weight, the client will poll each server's stats and use its size as the weight.
53
+
54
+ Valid option parameters are:
55
+
56
+ <tt>:prefix_key</tt>:: A string to prepend to every key, for namespacing. Max length is 127.
57
+ <tt>:hash</tt>:: The name of a hash function to use. Possible values are: <tt>:crc</tt>, <tt>:default</tt>, <tt>:fnv1_32</tt>, <tt>:fnv1_64</tt>, <tt>:fnv1a_32</tt>, <tt>:fnv1a_64</tt>, <tt>:hsieh</tt>, <tt>:md5</tt>, and <tt>:murmur</tt>. <tt>:fnv1_32</tt> is fast and well known, and is the default. Use <tt>:md5</tt> for compatibility with other ketama clients.
58
+ <tt>:distribution</tt>:: Either <tt>:modula</tt>, <tt>:consistent_ketama</tt>, <tt>:consistent_wheel</tt>, or <tt>:ketama</tt>. Defaults to <tt>:ketama</tt>.
59
+ <tt>:server_failure_limit</tt>:: How many consecutive failures to allow before marking a host as dead. Has no effect unless <tt>:retry_timeout</tt> is also set.
60
+ <tt>:retry_timeout</tt>:: How long to wait until retrying a dead server. Has no effect unless <tt>:server_failure_limit</tt> is non-zero. Defaults to <tt>30</tt>.
61
+ <tt>:auto_eject_hosts</tt>:: Whether to temporarily eject dead hosts from the pool. Defaults to <tt>true</tt>. Note that in the event of an ejection, <tt>:auto_eject_hosts</tt> will remap the entire pool unless <tt>:distribution</tt> is set to <tt>:consistent</tt>.
62
+ <tt>:cache_lookups</tt>:: Whether to cache hostname lookups for the life of the instance. Defaults to <tt>true</tt>.
63
+ <tt>:support_cas</tt>:: Flag CAS support in the client. Accepts <tt>true</tt> or <tt>false</tt>. Defaults to <tt>false</tt> because it imposes a slight performance penalty. Note that your server must also support CAS or you will trigger <b>Memcached::ProtocolError</b> exceptions.
64
+ <tt>:tcp_nodelay</tt>:: Turns on the no-delay feature for connecting sockets. Accepts <tt>true</tt> or <tt>false</tt>. Performance may or may not change, depending on your system.
65
+ <tt>:no_block</tt>:: Whether to use pipelining for writes. Accepts <tt>true</tt> or <tt>false</tt>.
66
+ <tt>:buffer_requests</tt>:: Whether to use an internal write buffer. Accepts <tt>true</tt> or <tt>false</tt>. Calling <tt>get</tt> or closing the connection will force the buffer to flush. Note that <tt>:buffer_requests</tt> might not work well without <tt>:no_block</tt> also enabled.
67
+ <tt>:show_backtraces</tt>:: Whether <b>Memcached::NotFound</b> and <b>Memcached::NotStored</b> exceptions should include backtraces. Generating backtraces is slow, so this is off by default. Turn it on to ease debugging.
68
+ <tt>:connect_timeout</tt>:: How long to wait for a connection to a server. Defaults to 2 seconds. Set to <tt>0</tt> if you want to wait forever.
69
+ <tt>:timeout</tt>:: How long to wait for a response from the server. Defaults to 0.25 seconds. Set to <tt>0</tt> if you want to wait forever.
70
+ <tt>:default_ttl</tt>:: The <tt>ttl</tt> to use on set if no <tt>ttl</tt> is specified, in seconds. Defaults to one week. Set to <tt>0</tt> if you want things to never expire.
71
+ <tt>:default_weight</tt>:: The weight to use if <tt>:ketama_weighted</tt> is <tt>true</tt>, but no weight is specified for a server.
72
+ <tt>:hash_with_prefix_key</tt>:: Whether to include the prefix when calculating which server a key falls on. Defaults to <tt>true</tt>.
73
+ <tt>:use_udp</tt>:: Use the UDP protocol to reduce connection overhead. Defaults to false.
74
+ <tt>:binary_protocol</tt>:: Use the binary protocol to reduce query processing overhead. Defaults to false.
75
+ <tt>:sort_hosts</tt>:: Whether to force the server list to stay sorted. This defeats consistent hashing and is rarely useful.
76
+ <tt>:verify_key</tt>:: Validate keys before accepting them. Never disable this.
77
+
78
+ Please note that when pipelining is enabled, setter and deleter methods do not raise on errors. For example, if you try to set an invalid key with <tt>:no_block => true</tt>, it will appear to succeed. The actual setting of the key occurs after libmemcached has returned control to your program, so there is no way to backtrack and raise the exception.
79
+
80
+ =end
81
+
82
+ # Track structs so we can free them
83
+ @@structs = {}
84
+
85
+ def initialize(servers = "localhost:11211", opts = {})
86
+ @struct = Lib::MemcachedSt.new
87
+ Lib.memcached_create(@struct)
88
+ @@structs[object_id] = @struct
89
+
90
+ # Merge option defaults and discard meaningless keys
91
+ @options = DEFAULTS.merge(opts)
92
+ @options.delete_if { |k,v| not DEFAULTS.keys.include? k }
93
+ @default_ttl = options[:default_ttl]
94
+
95
+ if options[:credentials] == nil && ENV.key?("MEMCACHE_USERNAME") && ENV.key?("MEMCACHE_PASSWORD")
96
+ options[:credentials] = [ENV["MEMCACHE_USERNAME"], ENV["MEMCACHE_PASSWORD"]]
97
+ end
98
+
99
+ options[:binary_protocol] = true if options[:credentials] != nil
100
+
101
+ # Force :buffer_requests to use :no_block
102
+ # XXX Deleting the :no_block key should also work, but libmemcached doesn't seem to set it
103
+ # consistently
104
+ options[:no_block] = true if options[:buffer_requests]
105
+
106
+ # Disallow weights without ketama
107
+ options.delete(:ketama_weighted) if options[:distribution] != :consistent_ketama
108
+
109
+ # Legacy accessor
110
+ options[:prefix_key] = options.delete(:namespace) if options[:namespace]
111
+
112
+ # Disallow :sort_hosts with consistent hashing
113
+ if options[:sort_hosts] and options[:distribution] == :consistent
114
+ raise ArgumentError, ":sort_hosts defeats :consistent hashing"
115
+ end
116
+
117
+ # Read timeouts
118
+ options[:rcv_timeout] ||= options[:timeout] || 0
119
+ options[:poll_timeout] ||= options[:timeout] || 0
120
+
121
+ # Set the behaviors on the struct
122
+ set_behaviors
123
+ set_callbacks
124
+ set_credentials
125
+
126
+ # Freeze the hash
127
+ options.freeze
128
+
129
+ # Set the servers on the struct
130
+ set_servers(servers)
131
+
132
+ # Not found exceptions
133
+ unless options[:show_backtraces]
134
+ @not_found = NotFound.new
135
+ @not_found.no_backtrace = true
136
+ @not_stored = NotStored.new
137
+ @not_stored.no_backtrace = true
138
+ end
139
+
140
+ ObjectSpace.define_finalizer(self, self.class.method(:finalize).to_proc)
141
+
142
+ end
143
+
144
+ def Memcached.finalize(id)
145
+ # Don't leak clients!
146
+ struct = @@structs[id]
147
+ @@structs.delete(id)
148
+ # Don't leak authentication data either. This will silently fail if it's not set.
149
+ Lib.memcached_destroy_sasl_auth_data(struct)
150
+ Lib.memcached_free(struct)
151
+ end
152
+
153
+ # Set the server list.
154
+ # FIXME Does not necessarily free any existing server structs.
155
+ def set_servers(servers)
156
+ Array(servers).each_with_index do |server, index|
157
+ # Socket
158
+ if server.is_a?(String) and File.socket?(server)
159
+ args = [@struct, server, options[:default_weight].to_i]
160
+ check_return_code(Lib.memcached_server_add_unix_socket_with_weight(*args))
161
+ # Network
162
+ elsif server.is_a?(String) and server =~ /^[\w\d\.-]+(:\d{1,5}){0,2}$/
163
+ host, port, weight = server.split(":")
164
+ args = [@struct, host, port.to_i, (weight || options[:default_weight]).to_i]
165
+ if options[:use_udp] #
166
+ check_return_code(Lib.memcached_server_add_udp_with_weight(*args))
167
+ else
168
+ check_return_code(Lib.memcached_server_add_with_weight(*args))
169
+ end
170
+ else
171
+ raise ArgumentError, "Servers must be either in the format 'host:port[:weight]' (e.g., 'localhost:11211' or 'localhost:11211:10') for a network server, or a valid path to a Unix domain socket (e.g., /var/run/memcached)."
172
+ end
173
+ end
174
+ # For inspect
175
+ @servers = send(:servers)
176
+ end
177
+
178
+ # Return the array of server strings used to configure this instance.
179
+ def servers
180
+ server_structs.map do |server|
181
+ inspect_server(server)
182
+ end
183
+ end
184
+
185
+ # Safely copy this instance. Returns a Memcached instance.
186
+ #
187
+ # <tt>clone</tt> is useful for threading, since each thread must have its own unshared Memcached
188
+ # object.
189
+ #
190
+ def clone
191
+ # FIXME Memory leak
192
+ # memcached = super
193
+ # struct = Lib.memcached_clone(nil, @struct)
194
+ # memcached.instance_variable_set('@struct', struct)
195
+ # memcached
196
+ self.class.new(servers, options)
197
+ end
198
+
199
+ # Reset the state of the libmemcached struct. This is useful for changing the server list at runtime.
200
+ def reset(current_servers = nil)
201
+ current_servers ||= servers
202
+ destroy_credentials
203
+ Lib.memcached_free(@struct)
204
+ @struct = Lib::MemcachedSt.new
205
+ Lib.memcached_create(@struct)
206
+ set_behaviors
207
+ set_callbacks
208
+ set_credentials
209
+ set_servers(current_servers)
210
+ end
211
+
212
+ # Disconnect from all currently connected servers
213
+ def quit
214
+ Lib.memcached_quit(@struct)
215
+ self
216
+ end
217
+
218
+ #:stopdoc:
219
+ alias :dup :clone #:nodoc:
220
+ #:startdoc:
221
+
222
+ ### Configuration helpers
223
+
224
+ private
225
+
226
+ # Return an array of raw <tt>memcached_host_st</tt> structs for this instance.
227
+ def server_structs
228
+ array = []
229
+ if @struct.hosts
230
+ @struct.hosts.count.times do |i|
231
+ array << Lib.memcached_select_server_at(@struct, i)
232
+ end
233
+ end
234
+ array
235
+ end
236
+
237
+ ###### Operations
238
+
239
+ public
240
+
241
+ ### Setters
242
+
243
+ # Set a key/value pair. Accepts a String <tt>key</tt> and an arbitrary Ruby object. Overwrites any existing value on the server.
244
+ #
245
+ # Accepts an optional <tt>ttl</tt> value to specify the maximum lifetime of the key on the server. <tt>ttl</tt> can be either an integer number of seconds, or a Time elapsed time object. <tt>0</tt> means no ttl. Note that there is no guarantee that the key will persist as long as the <tt>ttl</tt>, but it will not persist longer.
246
+ #
247
+ # Also accepts a <tt>marshal</tt> value, which defaults to <tt>true</tt>. Set <tt>marshal</tt> to <tt>false</tt> if you want the <tt>value</tt> to be set directly.
248
+ #
249
+ def set(key, value, ttl=@default_ttl, marshal=true, flags=FLAGS)
250
+ value = marshal ? Marshal.dump(value) : value.to_s
251
+ check_return_code(
252
+ Lib.memcached_set(@struct, key, value, ttl, flags),
253
+ key
254
+ )
255
+ rescue ClientError
256
+ # FIXME Memcached 1.2.8 occasionally rejects valid sets
257
+ tried = 1 and retry unless defined?(tried)
258
+ raise
259
+ end
260
+
261
+ # Add a key/value pair. Raises <b>Memcached::NotStored</b> if the key already exists on the server. The parameters are the same as <tt>set</tt>.
262
+ def add(key, value, ttl=@default_ttl, marshal=true, flags=FLAGS)
263
+ value = marshal ? Marshal.dump(value) : value.to_s
264
+ check_return_code(
265
+ Lib.memcached_add(@struct, key, value, ttl, flags),
266
+ key
267
+ )
268
+ end
269
+
270
+ # Increment a key's value. Accepts a String <tt>key</tt>. Raises <b>Memcached::NotFound</b> if the key does not exist.
271
+ #
272
+ # Also accepts an optional <tt>offset</tt> paramater, which defaults to 1. <tt>offset</tt> must be an integer.
273
+ #
274
+ # Note that the key must be initialized to an unmarshalled integer first, via <tt>set</tt>, <tt>add</tt>, or <tt>replace</tt> with <tt>marshal</tt> set to <tt>false</tt>.
275
+ def increment(key, offset=1)
276
+ ret, value = Lib.memcached_increment(@struct, key, offset)
277
+ check_return_code(ret, key)
278
+ value
279
+ end
280
+
281
+ # Decrement a key's value. The parameters and exception behavior are the same as <tt>increment</tt>.
282
+ def decrement(key, offset=1)
283
+ ret, value = Lib.memcached_decrement(@struct, key, offset)
284
+ check_return_code(ret, key)
285
+ value
286
+ end
287
+
288
+ #:stopdoc:
289
+ alias :incr :increment
290
+ alias :decr :decrement
291
+ #:startdoc:
292
+
293
+ # Replace a key/value pair. Raises <b>Memcached::NotFound</b> if the key does not exist on the server. The parameters are the same as <tt>set</tt>.
294
+ def replace(key, value, ttl=@default_ttl, marshal=true, flags=FLAGS)
295
+ value = marshal ? Marshal.dump(value) : value.to_s
296
+ check_return_code(
297
+ Lib.memcached_replace(@struct, key, value, ttl, flags),
298
+ key
299
+ )
300
+ end
301
+
302
+ # Appends a string to a key's value. Accepts a String <tt>key</tt> and a String <tt>value</tt>. Raises <b>Memcached::NotFound</b> if the key does not exist on the server.
303
+ #
304
+ # Note that the key must be initialized to an unmarshalled string first, via <tt>set</tt>, <tt>add</tt>, or <tt>replace</tt> with <tt>marshal</tt> set to <tt>false</tt>.
305
+ def append(key, value)
306
+ # Requires memcached 1.2.4
307
+ check_return_code(
308
+ Lib.memcached_append(@struct, key, value.to_s, IGNORED, IGNORED),
309
+ key
310
+ )
311
+ end
312
+
313
+ # Prepends a string to a key's value. The parameters and exception behavior are the same as <tt>append</tt>.
314
+ def prepend(key, value)
315
+ # Requires memcached 1.2.4
316
+ check_return_code(
317
+ Lib.memcached_prepend(@struct, key, value.to_s, IGNORED, IGNORED),
318
+ key
319
+ )
320
+ end
321
+
322
+ # Reads a key's value from the server and yields it to a block. Replaces the key's value with the result of the block as long as the key hasn't been updated in the meantime, otherwise raises <b>Memcached::NotStored</b>. Accepts a String <tt>key</tt> and a block.
323
+ #
324
+ # Also accepts an optional <tt>ttl</tt> value.
325
+ #
326
+ # CAS stands for "compare and swap", and avoids the need for manual key mutexing. CAS support must be enabled in Memcached.new or a <b>Memcached::ClientError</b> will be raised. Note that CAS may be buggy in memcached itself.
327
+ #
328
+ def cas(key, ttl=@default_ttl, marshal=true, flags=FLAGS)
329
+ raise ClientError, "CAS not enabled for this Memcached instance" unless options[:support_cas]
330
+
331
+ value, flags, ret = Lib.memcached_get_rvalue(@struct, key)
332
+ check_return_code(ret, key)
333
+ cas = @struct.result.cas
334
+
335
+ value = Marshal.load(value) if marshal
336
+ value = yield value
337
+ value = Marshal.dump(value) if marshal
338
+
339
+ check_return_code(Lib.memcached_cas(@struct, key, value, ttl, flags, cas), key)
340
+ end
341
+
342
+ alias :compare_and_swap :cas
343
+
344
+ ### Deleters
345
+
346
+ # Deletes a key/value pair from the server. Accepts a String <tt>key</tt>. Raises <b>Memcached::NotFound</b> if the key does not exist.
347
+ def delete(key)
348
+ check_return_code(
349
+ Lib.memcached_delete(@struct, key, IGNORED),
350
+ key
351
+ )
352
+ end
353
+
354
+ # Flushes all key/value pairs from all the servers.
355
+ def flush
356
+ check_return_code(
357
+ Lib.memcached_flush(@struct, IGNORED)
358
+ )
359
+ end
360
+
361
+ ### Getters
362
+
363
+ # Gets a key's value from the server. Accepts a String <tt>key</tt> or array of String <tt>keys</tt>.
364
+ #
365
+ # Also accepts a <tt>marshal</tt> value, which defaults to <tt>true</tt>. Set <tt>marshal</tt> to <tt>false</tt> if you want the <tt>value</tt> to be returned directly as a String. Otherwise it will be assumed to be a marshalled Ruby object and unmarshalled.
366
+ #
367
+ # If you pass a String key, and the key does not exist on the server, <b>Memcached::NotFound</b> will be raised. If you pass an array of keys, memcached's <tt>multiget</tt> mode will be used, and a hash of key/value pairs will be returned. The hash will contain only the keys that were found.
368
+ #
369
+ # The multiget behavior is subject to change in the future; however, for multiple lookups, it is much faster than normal mode.
370
+ #
371
+ # Note that when you rescue Memcached::NotFound exceptions, you should use a the block rescue syntax instead of the inline syntax. Block rescues are very fast, but inline rescues are very slow.
372
+ #
373
+ def get(keys, marshal=true)
374
+ if keys.is_a? Array
375
+ # Multi get
376
+ ret = Lib.memcached_mget(@struct, keys);
377
+ check_return_code(ret, keys)
378
+
379
+ hash = {}
380
+ keys.each do
381
+ value, key, flags, ret = Lib.memcached_fetch_rvalue(@struct)
382
+ break if ret == Lib::MEMCACHED_END
383
+ check_return_code(ret, key)
384
+ # Assign the value
385
+ hash[key] = (marshal ? Marshal.load(value) : value)
386
+ end
387
+ hash
388
+ else
389
+ # Single get
390
+ value, flags, ret = Lib.memcached_get_rvalue(@struct, keys)
391
+ check_return_code(ret, keys)
392
+ marshal ? Marshal.load(value) : value
393
+ end
394
+ end
395
+
396
+ ### Information methods
397
+
398
+ # Return the server used by a particular key.
399
+ def server_by_key(key)
400
+ ret = Lib.memcached_server_by_key(@struct, key)
401
+ if ret.is_a?(Array)
402
+ string = inspect_server(ret.first)
403
+ Rlibmemcached.memcached_server_free(ret.first)
404
+ string
405
+ end
406
+ end
407
+
408
+ # Return a Hash of statistics responses from the set of servers. Each value is an array with one entry for each server, in the same order the servers were defined.
409
+ def stats
410
+ stats = Hash.new([])
411
+
412
+ stat_struct, ret = Lib.memcached_stat(@struct, "")
413
+ check_return_code(ret)
414
+
415
+ keys, ret = Lib.memcached_stat_get_keys(@struct, stat_struct)
416
+ check_return_code(ret)
417
+
418
+ keys.each do |key|
419
+ server_structs.size.times do |index|
420
+
421
+ value, ret = Lib.memcached_stat_get_rvalue(
422
+ @struct,
423
+ Lib.memcached_select_stat_at(@struct, stat_struct, index),
424
+ key)
425
+ check_return_code(ret, key)
426
+
427
+ value = case value
428
+ when /^\d+\.\d+$/ then value.to_f
429
+ when /^\d+$/ then value.to_i
430
+ else value
431
+ end
432
+
433
+ stats[key.to_sym] += [value]
434
+ end
435
+ end
436
+
437
+ Lib.memcached_stat_free(@struct, stat_struct)
438
+ stats
439
+ rescue Memcached::SomeErrorsWereReported => _
440
+ e = _.class.new("Error getting stats")
441
+ e.set_backtrace(_.backtrace)
442
+ raise e
443
+ end
444
+
445
+ ### Operations helpers
446
+
447
+ private
448
+
449
+ # Checks the return code from Rlibmemcached against the exception list. Raises the corresponding exception if the return code is not Memcached::Success or Memcached::ActionQueued. Accepts an integer return code and an optional key, for exception messages.
450
+ def check_return_code(ret, key = nil) #:doc:
451
+ if ret == 0 # Memcached::Success
452
+ elsif ret == Lib::MEMCACHED_BUFFERED # Memcached::ActionQueued
453
+ elsif ret == Lib::MEMCACHED_NOTFOUND and @not_found
454
+ raise @not_found
455
+ elsif ret == Lib::MEMCACHED_NOTSTORED and @not_stored
456
+ raise @not_stored
457
+ else
458
+ message = "Key #{inspect_keys(key, (detect_failure if ret == Lib::MEMCACHED_SERVER_MARKED_DEAD)).inspect}"
459
+ if key.is_a?(String)
460
+ if ret == Lib::MEMCACHED_ERRNO
461
+ server = Lib.memcached_server_by_key(@struct, key)
462
+ errno = server.first.cached_errno
463
+ message = "Errno #{errno}: #{ERRNO_HASH[errno].inspect}. #{message}"
464
+ elsif ret == Lib::MEMCACHED_SERVER_ERROR
465
+ server = Lib.memcached_server_by_key(@struct, key)
466
+ message = "\"#{server.first.cached_server_error}\". #{message}."
467
+ end
468
+ end
469
+ raise EXCEPTIONS[ret], message
470
+ end
471
+ end
472
+
473
+ # Turn an array of keys into a hash of keys to servers.
474
+ def inspect_keys(keys, server = nil)
475
+ Hash[*Array(keys).map do |key|
476
+ [key, server || server_by_key(key)]
477
+ end.flatten]
478
+ end
479
+
480
+ # Find which server failed most recently.
481
+ # FIXME Is this still necessary with cached_errno?
482
+ def detect_failure
483
+ time = Time.now
484
+ server = server_structs.detect do |server|
485
+ server.next_retry > time
486
+ end
487
+ inspect_server(server) if server
488
+ end
489
+
490
+ # Set the behaviors on the struct from the current options.
491
+ def set_behaviors
492
+ BEHAVIORS.keys.each do |behavior|
493
+ set_behavior(behavior, options[behavior]) if options.key?(behavior)
494
+ end
495
+ # BUG Hash must be last due to the weird Libmemcached multi-behaviors
496
+ set_behavior(:hash, options[:hash])
497
+ end
498
+
499
+ # Set the callbacks on the struct from the current options.
500
+ def set_callbacks
501
+ # Only support prefix_key for now
502
+ if options[:prefix_key]
503
+ unless options[:prefix_key].size < Lib::MEMCACHED_PREFIX_KEY_MAX_SIZE
504
+ raise ArgumentError, "Max prefix_key size is #{Lib::MEMCACHED_PREFIX_KEY_MAX_SIZE - 1}"
505
+ end
506
+ Lib.memcached_callback_set(@struct, Lib::MEMCACHED_CALLBACK_PREFIX_KEY, options[:prefix_key])
507
+ end
508
+ end
509
+
510
+ def is_unix_socket?(server)
511
+ server.type == Lib::MEMCACHED_CONNECTION_UNIX_SOCKET
512
+ end
513
+
514
+ # Stringify an opaque server struct
515
+ def inspect_server(server)
516
+ strings = [server.hostname]
517
+ if !is_unix_socket?(server)
518
+ strings << ":#{server.port}"
519
+ strings << ":#{server.weight}" if options[:ketama_weighted]
520
+ end
521
+ strings.join
522
+ end
523
+ end