memcached 0.5 → 0.6

data/lib/memcached/memcached.rb

@@ -1,4 +1,7 @@
 
+=begin rdoc
+The Memcached client class.
+=end
 class Memcached
 
   FLAGS = 0x0
@@ -6,19 +9,38 @@ class Memcached
   DEFAULTS = {
     :hash => :default,
     :distribution => :consistent,
+    :no_block => false,
     :buffer_requests => false,
     :support_cas => false,
     :tcp_nodelay => false,
-    :no_block => false
+    :namespace => nil
   }
   
-  IGNORED = 0
+  IGNORED = 0 #:nodoc:
   
-  attr_reader :namespace
-  attr_reader :options
+  attr_reader :options # Return the options Hash used to configure this instance.
+
+###### Configuration
+
+=begin rdoc      
+Create a new Memcached instance. Accepts a single server string such as '127.0.0.1:11211', or an array of such strings, as well an an optional configuration hash.
+
+Hostname lookups are not currently supported; you need to use the IP address.
+
+Valid option parameters are:
+
+<tt>:namespace</tt>:: A namespace string to prepend to every key.
+<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>:ketama</tt>, and <tt>:md5</tt>. <tt>:default</tt> is the fastest.
+<tt>:distribution</tt>:: The type of distribution function to use. Possible values are <tt>:modula</tt> and <tt>:consistent</tt>. Note that this is decoupled from the choice of hash function.
+<tt>:support_cas</tt>:: Flag CAS support in the client. Accepts <tt>true</tt> or <tt>false</tt>. Note that your server must also support CAS or you will trigger <b>Memcached::ProtocolError</b> exceptions.
+<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.
+<tt>:no_block</tt>:: Whether to use non-blocking, asynchronous IO for writes. Accepts <tt>true</tt> or <tt>false</tt>.
+<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.
+
+Please note that when non-blocking IO 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.
+
+=end
 
-  ### Configuration
-  
   def initialize(servers, opts = {})
     @struct = Libmemcached::MemcachedSt.new
     Libmemcached.memcached_create(@struct)
@@ -37,34 +59,49 @@ class Memcached
       )
     end  
     
-    # Namespace
-    @namespace = opts[:namespace]
-    raise ArgumentError, "Invalid namespace" if namespace.to_s =~ / /
-
     # Behaviors
     @options = DEFAULTS.merge(opts)
     options.each do |option, value|
       set_behavior(option, value) unless option == :namespace
     end
+    
+    # Make sure :buffer_requests uses :no_block
+    # XXX Not enforcing this for now.
+    # if options[:buffer_requests] and not options[:no_block]
+    #   raise ArgumentError, "Invalid options; :buffer_requests does not work well without :no_block."
+    # end
+
+    # Namespace
+    raise ArgumentError, "Invalid namespace" if options[:namespace].to_s =~ / /
+    @namespace = options[:namespace]
   end
 
+=begin rdoc
+Return the array of server strings used to configure this instance.
+=end
   def servers
     server_structs.map do |server|
       "#{server.hostname}:#{server.port}"
     end
   end
-  
+
+  # Safely copy this instance. Returns a Memcached instance. 
+  #
+  # <tt>clone</tt> is useful for threading, since each thread must have its own unshared Memcached object. 
   def clone
     # XXX Could be more efficient if we used Libmemcached.memcached_clone(@struct)
     self.class.new(servers, options)
   end
   
-  alias :dup :clone
+  #:stopdoc:
+  alias :dup :clone #:nodoc:
+  #:startdoc:
 
-  ### Configuration helpers
+### Configuration helpers
 
   private
     
+  # Return an array of raw <tt>memcached_host_st</tt> structs for this instance.
   def server_structs
     array = []
     @struct.hosts.count.times do |i|
@@ -73,12 +110,18 @@ class Memcached
     array
   end    
     
-  ### Operations
+###### Operations
   
   public
   
-  # Setters
-  
+### Setters
+    
+  # Set a key/value pair. Accepts a String <tt>key</tt> and an arbitrary Ruby object. Overwrites any existing value on the server.
+  #
+  # Accepts an optional <tt>timeout</tt> value to specify the maximum lifetime of the key on the server. <tt>timeout</tt> can be either an integer number of seconds, or a Time elapsed time object. (There is no guarantee that the key will persist as long as the <tt>timeout</tt>, but it will not persist longer.)
+  #
+  # 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. 
+  # 
   def set(key, value, timeout=0, marshal=true)
     value = marshal ? Marshal.dump(value) : value.to_s
     check_return_code(
@@ -86,35 +129,48 @@ class Memcached
     )
   end
 
+  # 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>.
   def add(key, value, timeout=0, marshal=true)
     value = marshal ? Marshal.dump(value) : value.to_s
     check_return_code(
       Libmemcached.memcached_add(@struct, ns(key), value, timeout, FLAGS)
     )
   end
-  
+
+  # Increment a key's value. Accepts a String <tt>key</tt>. Raises <b>Memcached::NotFound</b> if the key does not exist. 
+  #
+  # Also accepts an optional <tt>offset</tt> paramater, which defaults to 1. <tt>offset</tt> must be an integer.
+  #
+  # 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>.
   def increment(key, offset=1)
     ret, value = Libmemcached.memcached_increment(@struct, ns(key), offset)
     check_return_code(ret)
     value
   end
-  
+
+  # Decrement a key's value. The parameters and exception behavior are the same as <tt>increment</tt>.
   def decrement(key, offset=1)
     ret, value = Libmemcached.memcached_decrement(@struct, ns(key), offset)
     check_return_code(ret)
     value
   end
   
+  #:stopdoc:  
   alias :incr :increment
   alias :decr :decrement
-  
+  #:startdoc:
+
+  # 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>.
   def replace(key, value, timeout=0, marshal=true)
     value = marshal ? Marshal.dump(value) : value.to_s
     check_return_code(
       Libmemcached.memcached_replace(@struct, ns(key), value, timeout, FLAGS)
     )
   end
-  
+
+  # 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. 
+  #
+  # 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>.
   def append(key, value)
     # Requires memcached 1.2.4
     check_return_code(
@@ -122,6 +178,7 @@ class Memcached
     )
   end
   
+  # Prepends a string to a key's value. The parameters and exception behavior are the same as <tt>append</tt>.
   def prepend(key, value)
     # Requires memcached 1.2.4
     check_return_code(
@@ -129,37 +186,52 @@ class Memcached
     )
   end
   
-  def cas
+  # Not yet implemented.
+  #
+  # 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.
+  #
+  # Also accepts an optional <tt>timeout</tt> value.
+  #
+  # 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.
+  def cas(*args)
     # Requires memcached HEAD
     raise NotImplemented
-    raise "CAS not enabled" unless options[:support_cas]
+    raise ClientError, "CAS not enabled for this Memcached instance" unless options[:support_cas]
   end
 
-  # Deleters
+### Deleters
 
-  def delete(key, timeout=0)
+  # 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.
+  def delete(key)
     check_return_code(
-      Libmemcached.memcached_delete(@struct, ns(key), timeout)
+      Libmemcached.memcached_delete(@struct, ns(key), IGNORED)
     )  
   end
   
-  # Getters
+### Getters  
   
+  # Gets a key's value from the server. Accepts a String <tt>key</tt> or array of String <tt>keys</tt>.
+  #
+  # 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.
+  #
+  # If you pass a single 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 an array of values will be returned. Missing values in the array will be represented as instances of <b>Memcached::NotFound</b>. This behavior may change in the future.
+  #
   def get(key, marshal=true)
+    # XXX Could be faster if it didn't have to branch on the key type
     if key.is_a? Array
       # Multi get
       # XXX Waiting on the real implementation
       key.map do |this_key|
         begin
           get(this_key, marshal)
-        rescue NotFound
-          # XXX Not sure how this behavior should be defined
+        rescue NotFound => e
+          e
         end
       end
     else
       # Single get
-      # XXX Server doesn't validate. Possibly a performance problem.
-      raise ClientError, "Invalid key" if !key.is_a? String or key =~ /\s/ 
+      # XXX Server doesn't validate keys. Regex is possibly a performance problem.
+      raise ClientError, "Invalid key" if key =~ /\s/ 
         
       value, flags, ret = Libmemcached.memcached_get_ruby_string(@struct, ns(key))
       check_return_code(ret)
@@ -168,8 +240,9 @@ class Memcached
     end
   end    
   
-  # Information methods
+  ### Information methods
   
+  # 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.
   def stats
     stats = Hash.new([])
     
@@ -206,13 +279,16 @@ class Memcached
   
   private
 
-  def ns(key)
+  # Return a namespaced key for this Memcached instance. Accepts a String <tt>key</tt> value.
+  def ns(key) #:doc:
     "#{@namespace}#{key}"
   end
     
-  def check_return_code(ret)
-    return if ret == 0
-    raise @@exceptions[ret]
+  # Checks the return code from Libmemcached against the exception list. Raises the corresponding exception if the return code is not Memcached::Success or Memcached::ActionQueued. Accepts an integer return code.
+  def check_return_code(ret) #:doc:
+    # XXX 0.14 already returns 0 for an ActionQueued result
+    return if ret == 0 or ret == 31
+    raise EXCEPTIONS[ret], ""
   end  
     
 end

data/memcached.gemspec

@@ -1,27 +1,27 @@
 
-# Gem::Specification for Memcached-0.5
+# Gem::Specification for Memcached-0.6
 # Originally generated by Echoe
 
 Gem::Specification.new do |s|
   s.name = %q{memcached}
-  s.version = "0.5"
+  s.version = "0.6"
 
   s.specification_version = 2 if s.respond_to? :specification_version=
 
   s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
   s.authors = ["Evan Weaver"]
-  s.date = %q{2008-01-20}
+  s.date = %q{2008-01-21}
   s.description = %q{An interface to the libmemcached C client.}
   s.email = %q{}
   s.extensions = ["ext/extconf.rb"]
-  s.files = ["CHANGELOG", "ext/extconf.rb", "ext/libmemcached.h", "ext/libmemcached.i", "ext/libmemcached_wrap.c", "lib/memcached/behaviors.rb", "lib/memcached/exceptions.rb", "lib/memcached/integer.rb", "lib/memcached/memcached.rb", "lib/memcached.rb", "LICENSE", "Manifest", "README", "test/benchmark/benchmark_test.rb", "test/setup.rb", "test/teardown.rb", "test/test_helper.rb", "test/unit/binding_test.rb", "test/unit/memcached_test.rb", "memcached.gemspec"]
+  s.files = ["CHANGELOG", "ext/extconf.rb", "ext/libmemcached.i", "ext/libmemcached_wrap.c", "lib/memcached/behaviors.rb", "lib/memcached/exceptions.rb", "lib/memcached/integer.rb", "lib/memcached/memcached.rb", "lib/memcached.rb", "LICENSE", "Manifest", "README", "test/benchmark/benchmark.rb", "test/benchmark/benchmark_set_get.rb", "test/benchmark/profile.rb", "test/setup.rb", "test/teardown.rb", "test/test_helper.rb", "test/unit/binding_test.rb", "test/unit/memcached_test.rb", "TODO", "memcached.gemspec"]
   s.has_rdoc = true
   s.homepage = %q{http://blog.evanweaver.com/files/doc/fauna/memcached/}
   s.require_paths = ["lib", "ext"]
   s.rubyforge_project = %q{fauna}
   s.rubygems_version = %q{1.0.1}
   s.summary = %q{An interface to the libmemcached C client.}
-  s.test_files = ["test/benchmark/benchmark_test.rb", "test/test_helper.rb", "test/unit/binding_test.rb", "test/unit/memcached_test.rb"]
+  s.test_files = ["test/test_helper.rb", "test/unit/binding_test.rb", "test/unit/memcached_test.rb"]
 end
 
 
@@ -35,4 +35,17 @@ end
 #   p.summary = "An interface to the libmemcached C client."
 #   p.url = "http://blog.evanweaver.com/files/doc/fauna/memcached/"
 #   p.docs_host = "blog.evanweaver.com:~/www/bax/public/files/doc/"
+#   p.rdoc_pattern = /README|TODO|LICENSE|CHANGELOG|exceptions|behaviors|memcached.rb/
+# end
+# 
+# task :exceptions do
+#   $LOAD_PATH << "lib"
+#   require 'memcached'
+#   Memcached.constants.sort.each do |const_name|
+#     const = Memcached.send(:const_get, const_name)
+#     next if const == Memcached::Success or const == Memcached::Stored
+#     if const.is_a? Class and const < Memcached::Error
+#       puts "* Memcached::#{const_name}"
+#     end
+#   end
 # end

data/test/benchmark/benchmark.rb

@@ -0,0 +1,259 @@
+
+HERE = File.dirname(__FILE__)
+$LOAD_PATH << "#{HERE}/../../lib/"
+
+require 'memcached'
+require 'benchmark'
+require 'rubygems'
+require 'memcache'
+
+# We'll use a simple @value to try to avoid spending time in Marshal, 
+# which is a constant penalty that both clients have to pay
+@value = []
+@marshalled = Marshal.dump(@value)
+
+@opts = [
+  ['127.0.0.1:43042', '127.0.0.1:43043'], 
+  {
+    :buffer_requests => false,
+    :no_block => false,
+    :namespace => "benchmark_namespace"
+  }
+]
+@key1 = "Short" 
+@key2 = "Sym1-2-3::45"*8
+@key3 = "Long"*40
+@key4 = "Medium"*8
+
+def restart_servers
+  system("ruby #{HERE}/../setup.rb")
+  sleep(1)
+end
+
+
+Benchmark.bm(31) do |x|
+  restart_servers
+
+  n = 1000  
+  
+  @m = Memcached.new(
+    @opts[0], 
+    @opts[1].merge(:no_block => true, :buffer_requests => true)
+  )
+  x.report("set:plain:noblock:memcached") do
+    n.times do
+      @m.set @key1, @marshalled, 0, false
+      @m.set @key2, @marshalled, 0, false
+      @m.set @key3, @marshalled, 0, false
+      @m.set @key1, @marshalled, 0, false
+      @m.set @key2, @marshalled, 0, false
+      @m.set @key3, @marshalled, 0, false
+    end
+  end
+  @m = Memcached.new(*@opts)
+  x.report("set:plain:memcached") do
+    n.times do
+      @m.set @key1, @marshalled, 0, false
+      @m.set @key2, @marshalled, 0, false
+      @m.set @key3, @marshalled, 0, false
+      @m.set @key1, @marshalled, 0, false
+      @m.set @key2, @marshalled, 0, false
+      @m.set @key3, @marshalled, 0, false
+    end
+  end
+  @m = MemCache.new(*@opts)
+  x.report("set:plain:memcache-client") do
+    n.times do
+      @m.set @key1, @marshalled, 0, true
+      @m.set @key2, @marshalled, 0, true
+      @m.set @key3, @marshalled, 0, true
+      @m.set @key1, @marshalled, 0, true
+      @m.set @key2, @marshalled, 0, true
+      @m.set @key3, @marshalled, 0, true
+    end
+  end
+  
+  restart_servers 
+
+  @m = Memcached.new(
+    @opts[0], 
+    @opts[1].merge(:no_block => true, :buffer_requests => true)
+  )
+  x.report("set:ruby:noblock:memcached") do
+    n.times do
+      @m.set @key1, @value
+      @m.set @key2, @value
+      @m.set @key3, @value
+      @m.set @key1, @value
+      @m.set @key2, @value
+      @m.set @key3, @value
+    end
+  end
+  @m = Memcached.new(*@opts)
+  x.report("set:ruby:memcached") do
+    n.times do
+      @m.set @key1, @value
+      @m.set @key2, @value
+      @m.set @key3, @value
+      @m.set @key1, @value
+      @m.set @key2, @value
+      @m.set @key3, @value
+    end
+  end
+  @m = MemCache.new(*@opts)
+  x.report("set:ruby:memcache-client") do
+    n.times do
+      @m.set @key1, @value
+      @m.set @key2, @value
+      @m.set @key3, @value
+      @m.set @key1, @value
+      @m.set @key2, @value
+      @m.set @key3, @value
+    end
+  end
+
+  @m = Memcached.new(*@opts)
+  x.report("get:plain:memcached") do
+    n.times do
+      @m.get @key1, false
+      @m.get @key2, false
+      @m.get @key3, false
+      @m.get @key1, false
+      @m.get @key2, false
+      @m.get @key3, false
+    end
+  end
+  @m = MemCache.new(*@opts)
+  x.report("get:plain:memcache-client") do
+    n.times do
+      @m.get @key1, true
+      @m.get @key2, true
+      @m.get @key3, true
+      @m.get @key1, true
+      @m.get @key2, true
+      @m.get @key3, true
+    end
+  end
+
+  @m = Memcached.new(*@opts)
+  x.report("get:ruby:memcached") do
+    n.times do
+      @m.get @key1
+      @m.get @key2
+      @m.get @key3
+      @m.get @key1
+      @m.get @key2
+      @m.get @key3
+    end
+  end
+  @m = MemCache.new(*@opts)
+  x.report("get:ruby:memcache-client") do
+    n.times do
+      @m.get @key1
+      @m.get @key2
+      @m.get @key3
+      @m.get @key1
+      @m.get @key2
+      @m.get @key3
+    end
+  end
+
+  restart_servers
+
+  @m = Memcached.new(*@opts)
+  x.report("missing:ruby:memcached") do
+    n.times do
+      begin @m.delete @key1; rescue Memcached::NotFound; end
+      begin @m.get @key1; rescue Memcached::NotFound; end
+      begin @m.delete @key2; rescue Memcached::NotFound; end
+      begin @m.get @key2; rescue Memcached::NotFound; end
+      begin @m.delete @key3; rescue Memcached::NotFound; end
+      begin @m.get @key3; rescue Memcached::NotFound; end
+    end
+  end
+  @m = MemCache.new(*@opts)
+  x.report("missing:ruby:memcache-client") do
+    n.times do
+      begin @m.delete @key1; rescue; end
+      begin @m.get @key1; rescue; end
+      begin @m.delete @key2; rescue; end
+      begin @m.get @key2; rescue; end
+      begin @m.delete @key3; rescue; end
+      begin @m.get @key3; rescue; end
+    end
+  end
+
+  restart_servers
+  
+  @m = Memcached.new(
+    @opts[0], 
+    @opts[1].merge(:no_block => true, :buffer_requests => true)
+  )
+  x.report("mixed:ruby:noblock:memcached") do
+    n.times do
+      @m.set @key1, @value
+      @m.set @key2, @value
+      @m.set @key3, @value
+      @m.get @key1
+      @m.get @key2
+      @m.get @key3
+      @m.set @key1, @value
+      @m.get @key1
+      @m.set @key2, @value
+      @m.get @key2
+      @m.set @key3, @value
+      @m.get @key3
+    end
+  end  
+  @m = Memcached.new(*@opts)
+  x.report("mixed:ruby:memcached") do
+    n.times do
+      @m.set @key1, @value
+      @m.set @key2, @value
+      @m.set @key3, @value
+      @m.get @key1
+      @m.get @key2
+      @m.get @key3
+      @m.set @key1, @value
+      @m.get @key1
+      @m.set @key2, @value
+      @m.get @key2
+      @m.set @key3, @value
+      @m.get @key3
+    end
+  end
+  @m = MemCache.new(*@opts)
+  x.report("mixed:ruby:memcache-client") do
+    n.times do
+      @m.set @key1, @value
+      @m.set @key2, @value
+      @m.set @key3, @value
+      @m.get @key1
+      @m.get @key2
+      @m.get @key3
+      @m.set @key1, @value
+      @m.get @key1
+      @m.set @key2, @value
+      @m.get @key2
+      @m.set @key3, @value
+      @m.get @key3
+    end
+  end
+
+  restart_servers
+    
+  n = 10000
+  Memcached::HASH_VALUES.each do |mode,|
+    @m = Memcached.new(@opts[0], @opts[1].merge(:hash => mode))
+    x.report("hash:#{mode}:memcached") do
+      n.times do
+        @m.set @key1, @marshalled, 0, false
+        @m.get @key1, false
+        @m.set @key2, @marshalled, 0, false
+        @m.get @key2, false
+        @m.set @key3, @marshalled, 0, false
+        @m.get @key3, false
+      end
+    end
+  end
+end