memcached 0.6 → 0.7

data/lib/memcached.rb

@@ -1,23 +1,24 @@
 
-require 'libmemcached'
+require 'rlibmemcached'
 require 'memcached/integer'
 require 'memcached/exceptions'
 require 'memcached/behaviors'
 require 'memcached/memcached'
+require 'memcached/rails'
 
 =begin rdoc
 The generated SWIG module for accessing libmemcached's C API.
 
 Includes the full set of libmemcached static methods (as defined in <tt>$INCLUDE_PATH/libmemcached/memcached.h</tt>), and classes for the available structs:
 
-* Libmemcached::MemcachedResultSt
-* Libmemcached::MemcachedServerSt
-* Libmemcached::MemcachedSt
-* Libmemcached::MemcachedStatSt
-* Libmemcached::MemcachedStringSt
+* <b>Rlibmemcached::MemcachedResultSt</b>
+* <b>Rlibmemcached::MemcachedServerSt</b>
+* <b>Rlibmemcached::MemcachedSt</b>
+* <b>Rlibmemcached::MemcachedStatSt</b>
+* <b>Rlibmemcached::MemcachedStringSt</b>
 
 A number of SWIG typemaps and C helper methods are also defined in <tt>ext/libmemcached.i</tt>.
 
 =end
-module Libmemcached
+module Rlibmemcached
 end

data/lib/memcached/behaviors.rb

@@ -4,8 +4,8 @@ class Memcached
 #:stopdoc:
 
   def self.load_constants(prefix, hash = {}, offset = 0)
-    Libmemcached.constants.grep(/^#{prefix}/).each do |const_name|
-      hash[const_name[prefix.length..-1].downcase.to_sym] = Libmemcached.const_get(const_name) + offset
+    Rlibmemcached.constants.grep(/^#{prefix}/).each do |const_name|
+      hash[const_name[prefix.length..-1].downcase.to_sym] = Rlibmemcached.const_get(const_name) + offset
     end
     hash
   end
@@ -42,8 +42,8 @@ class Memcached
     # STDERR.puts "Setting #{behavior}:#{b_id} => #{value}:#{v_id}"
     
     unless value == false
-      # XXX Setting false still turns on the behavior; maybe a Libmemcached bug
-      Libmemcached.memcached_behavior_set(@struct, b_id, v_id)
+      # XXX Setting false still turns on the behavior; maybe a Rlibmemcached bug
+      Rlibmemcached.memcached_behavior_set(@struct, b_id, v_id)
     end
     
   end  

data/lib/memcached/exceptions.rb

@@ -44,6 +44,9 @@ Subclasses correspond one-to-one with server response strings or libmemcached er
   class Error < RuntimeError
   end
   
+  class SynchronizationError < RuntimeError
+  end
+  
   # Raised if a method depends on functionality not yet completed in libmemcached. 
   class NotImplemented < NoMethodError
   end
@@ -58,12 +61,12 @@ Subclasses correspond one-to-one with server response strings or libmemcached er
   end
   
   EXCEPTIONS = []
-  EMPTY_STRUCT = Libmemcached::MemcachedSt.new
-  Libmemcached.memcached_create(EMPTY_STRUCT)
+  EMPTY_STRUCT = Rlibmemcached::MemcachedSt.new
+  Rlibmemcached.memcached_create(EMPTY_STRUCT)
   
   # Generate exception classes
-  Libmemcached::MEMCACHED_MAXIMUM_RETURN.times do |index|
-    description = Libmemcached.memcached_strerror(EMPTY_STRUCT, index)
+  Rlibmemcached::MEMCACHED_MAXIMUM_RETURN.times do |index|
+    description = Rlibmemcached.memcached_strerror(EMPTY_STRUCT, index)
     exception_class = eval("class #{camelize(description)} < Error; self; end")
     EXCEPTIONS << exception_class
   end

data/lib/memcached/memcached.rb

@@ -16,7 +16,11 @@ class Memcached
     :namespace => nil
   }
   
-  IGNORED = 0 #:nodoc:
+#:stopdoc:
+  IGNORED = 0
+  
+  NOTFOUND_INSTANCE = NotFound.new
+#:startdoc:
   
   attr_reader :options # Return the options Hash used to configure this instance.
 
@@ -42,8 +46,8 @@ Please note that when non-blocking IO is enabled, setter and deleter methods do
 =end
 
   def initialize(servers, opts = {})
-    @struct = Libmemcached::MemcachedSt.new
-    Libmemcached.memcached_create(@struct)
+    @struct = Rlibmemcached::MemcachedSt.new
+    Rlibmemcached.memcached_create(@struct)
 
     # Servers
     Array(servers).each_with_index do |server, index|
@@ -51,12 +55,7 @@ Please note that when non-blocking IO is enabled, setter and deleter methods do
         raise ArgumentError, "Servers must be in the format ip:port (e.g., '127.0.0.1:11211')" 
       end
       host, port = server.split(":")
-      Libmemcached.memcached_server_add(@struct, host, port.to_i)
-
-      # XXX To be removed once Krow fixes the write_ptr bug
-      Libmemcached.memcached_repair_server_st(@struct, 
-        Libmemcached.memcached_select_server_at(@struct, index)
-      )
+      Rlibmemcached.memcached_server_add(@struct, host, port.to_i)
     end  
     
     # Behaviors
@@ -73,12 +72,11 @@ Please note that when non-blocking IO is enabled, setter and deleter methods do
 
     # Namespace
     raise ArgumentError, "Invalid namespace" if options[:namespace].to_s =~ / /
-    @namespace = options[:namespace]
+    @namespace = options[:namespace].to_s
+    @namespace_size = @namespace.size
   end
 
-=begin rdoc
-Return the array of server strings used to configure this instance.
-=end
+  # Return the array of server strings used to configure this instance.
   def servers
     server_structs.map do |server|
       "#{server.hostname}:#{server.port}"
@@ -87,12 +85,34 @@ Return the array of server strings used to configure this instance.
 
   # 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. 
+  # <tt>clone</tt> is useful for threading, since each thread must have its own unshared Memcached 
+  # object. However, you must call destroy before each thread returns or you will leak significant memory.
+  #
   def clone
-    # XXX Could be more efficient if we used Libmemcached.memcached_clone(@struct)
-    self.class.new(servers, options)
+    memcached = super
+    memcached.instance_variable_set('@struct', Rlibmemcached.memcached_clone(nil, @struct))
+    memcached
   end
   
+  # Destroy this instance. Frees memory associated with the C implementation.
+  #
+  # Accepts an optional parameter <tt>disable_methods</tt>. When <tt>false</tt>, destroy
+  # runs much faster, but your instance will segfault if you try to call any other methods on it
+  # after destroy. Defaults to <tt>true</tt>, which safely overwrites all instance methods.
+  def destroy(disable_methods = true)
+    Rlibmemcached.memcached_free(@struct)
+    @struct = nil
+    if disable_methods
+      class << self
+        Memcached.instance_methods.each do |method_name|
+          define_method method_name do |*args|
+            raise Memcached::ClientError, "Instance has been explicitly destroyed"
+          end
+        end
+      end
+    end
+  end  
+  
   #:stopdoc:
   alias :dup :clone #:nodoc:
   #:startdoc:
@@ -105,7 +125,7 @@ Return the array of server strings used to configure this instance.
   def server_structs
     array = []
     @struct.hosts.count.times do |i|
-      array << Libmemcached.memcached_select_server_at(@struct, i)
+      array << Rlibmemcached.memcached_select_server_at(@struct, i)
     end
     array
   end    
@@ -118,14 +138,14 @@ Return the array of server strings used to configure this instance.
     
   # 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.)
+  # 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. <tt>0</tt> means no timeout. Note that 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(
-      Libmemcached.memcached_set(@struct, ns(key), value, timeout, FLAGS)
+      Rlibmemcached.memcached_set(@struct, ns(key), value, timeout, FLAGS)
     )
   end
 
@@ -133,7 +153,7 @@ Return the array of server strings used to configure this instance.
   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)
+      Rlibmemcached.memcached_add(@struct, ns(key), value, timeout, FLAGS)
     )
   end
 
@@ -143,14 +163,14 @@ Return the array of server strings used to configure this instance.
   #
   # 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)
+    ret, value = Rlibmemcached.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)
+    ret, value = Rlibmemcached.memcached_decrement(@struct, ns(key), offset)
     check_return_code(ret)
     value
   end
@@ -164,7 +184,7 @@ Return the array of server strings used to configure this instance.
   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)
+      Rlibmemcached.memcached_replace(@struct, ns(key), value, timeout, FLAGS)
     )
   end
 
@@ -174,7 +194,7 @@ Return the array of server strings used to configure this instance.
   def append(key, value)
     # Requires memcached 1.2.4
     check_return_code(
-      Libmemcached.memcached_append(@struct, ns(key), value.to_s, IGNORED, FLAGS)
+      Rlibmemcached.memcached_append(@struct, ns(key), value.to_s, IGNORED, FLAGS)
     )
   end
   
@@ -182,7 +202,7 @@ Return the array of server strings used to configure this instance.
   def prepend(key, value)
     # Requires memcached 1.2.4
     check_return_code(
-      Libmemcached.memcached_prepend(@struct, ns(key), value.to_s, IGNORED, FLAGS)
+      Rlibmemcached.memcached_prepend(@struct, ns(key), value.to_s, IGNORED, FLAGS)
     )
   end
   
@@ -204,7 +224,7 @@ Return the array of server strings used to configure this instance.
   # 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), IGNORED)
+      Rlibmemcached.memcached_delete(@struct, ns(key), IGNORED)
     )  
   end
   
@@ -214,30 +234,36 @@ Return the array of server strings used to configure this instance.
   #
   # 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.
+  # 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.
+  #
+  # The multiget behavior is subject to change in the future; however, for multiple lookups, it is much faster than normal mode.
   #
-  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
+  # 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.
+  #
+  def get(keys, marshal=true)
+    if keys.is_a? Array
       # Multi get
-      # XXX Waiting on the real implementation
-      key.map do |this_key|
-        begin
-          get(this_key, marshal)
-        rescue NotFound => e
-          e
-        end
+      keys.map! { |key| ns(key) }
+      hash = {}
+      
+      Rlibmemcached.memcached_mget(@struct, keys);
+      
+      keys.size.times do 
+        value, key, flags, ret = Rlibmemcached.memcached_fetch_rvalue(@struct)
+        break if ret == Rlibmemcached::MEMCACHED_END
+        check_return_code(ret)
+        value = Marshal.load(value) if marshal
+        # Assign the value, removing the namespace, if present
+        hash[key[@namespace_size..-1]] = value
       end
+      hash
     else
       # Single get
-      # 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))
+      value, flags, ret = Rlibmemcached.memcached_get_rvalue(@struct, ns(keys))
       check_return_code(ret)
       value = Marshal.load(value) if marshal
       value
-    end
+    end    
   end    
   
   ### Information methods
@@ -246,18 +272,18 @@ Return the array of server strings used to configure this instance.
   def stats
     stats = Hash.new([])
     
-    stat_struct, ret = Libmemcached.memcached_stat(@struct, "")
+    stat_struct, ret = Rlibmemcached.memcached_stat(@struct, "")
     check_return_code(ret)
     
-    keys, ret = Libmemcached.memcached_stat_get_keys(@struct, stat_struct)
+    keys, ret = Rlibmemcached.memcached_stat_get_keys(@struct, stat_struct)
     check_return_code(ret)
     
     keys.each do |key|
        server_structs.size.times do |index|
 
-         value, ret = Libmemcached.memcached_stat_get_value(
+         value, ret = Rlibmemcached.memcached_stat_get_rvalue(
            @struct, 
-           Libmemcached.memcached_select_stat_at(@struct, stat_struct, index),
+           Rlibmemcached.memcached_select_stat_at(@struct, stat_struct, index),
            key)
          check_return_code(ret)
 
@@ -271,7 +297,7 @@ Return the array of server strings used to configure this instance.
        end
     end
     
-    Libmemcached.memcached_stat_free(@struct, stat_struct)
+    Rlibmemcached.memcached_stat_free(@struct, stat_struct)
     stats
   end  
   
@@ -281,14 +307,21 @@ Return the array of server strings used to configure this instance.
 
   # Return a namespaced key for this Memcached instance. Accepts a String <tt>key</tt> value.
   def ns(key) #:doc:
+    # raise ClientError, "Invalid key" if key =~ /\s/ # XXX Slow
     "#{@namespace}#{key}"
   end
     
-  # 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.
+  # 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.
   def check_return_code(ret) #:doc:
-    # XXX 0.14 already returns 0 for an ActionQueued result
+    # 0.14 returns 0 for an ActionQueued result but 0.15 does not.
     return if ret == 0 or ret == 31
     raise EXCEPTIONS[ret], ""
+  rescue UnknownReadFailure
+    # libmemcached got out of sync; rebuild the struct
+    new_struct = Rlibmemcached.memcached_clone(nil, @struct)
+    Rlibmemcached.memcached_free(@struct)
+    @struct = new_struct
+    raise SynchronizationError, "Rebuilding @struct"
   end  
     
 end

data/lib/memcached/rails.rb

@@ -0,0 +1,55 @@
+
+class Memcached
+
+  alias :get_multi :get #:nodoc:
+
+  # A legacy compatibility wrapper for the Memcached class. It has basic compatibility with the <b>memcache-client</b> API.
+  class Rails < ::Memcached
+    
+    DEFAULTS = {}
+         
+    # See Memcached#new for details.
+    def initialize(servers, opts = {})
+      super(servers, DEFAULTS.merge(opts))      
+    end
+    
+    # Wraps Memcached#get so that it doesn't raise. This has the side-effect of preventing you from 
+    # storing <tt>nil</tt> values.
+    def get(key, raw = false)
+      super(key, !raw)
+    rescue NotFound
+    end
+    
+    # Wraps Memcached#get with multiple arguments.
+    def get_multi(*keys)
+      super(keys)
+    end
+    
+    # Wraps Memcached#set.
+    def set(key, value, ttl = 0, raw = false)
+      super(key, value, ttl, !raw)
+    end
+    
+    # Wraps Memcached#delete so that it doesn't raise. 
+    def delete(key)
+      super(key)
+    rescue NotFound
+    end
+    
+    # Namespace accessor.
+    def namespace
+      @namespace
+    end
+
+    # Alias for get.
+    def [](key)
+      get key
+    end        
+
+    # Alias for Memcached#set.
+    def []=(key, value)
+      set key, value
+    end
+    
+  end
+end

data/memcached.gemspec

@@ -1,27 +1,27 @@
 
-# Gem::Specification for Memcached-0.6
+# Gem::Specification for Memcached-0.7
 # Originally generated by Echoe
 
 Gem::Specification.new do |s|
   s.name = %q{memcached}
-  s.version = "0.6"
+  s.version = "0.7"
 
   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-21}
+  s.date = %q{2008-02-05}
   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.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.files = ["BENCHMARKS", "CHANGELOG", "COMPATIBILITY", "ext/extconf.rb", "ext/rlibmemcached.i", "ext/rlibmemcached_wrap.c", "lib/memcached/behaviors.rb", "lib/memcached/exceptions.rb", "lib/memcached/integer.rb", "lib/memcached/memcached.rb", "lib/memcached/rails.rb", "lib/memcached.rb", "LICENSE", "Manifest", "README", "test/profile/benchmark.rb", "test/profile/profile.rb", "test/profile/valgrind.rb", "test/setup.rb", "test/teardown.rb", "test/test_helper.rb", "test/unit/binding_test.rb", "test/unit/memcached_test.rb", "test/unit/rails_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/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", "test/unit/rails_test.rb"]
 end
 
 
@@ -35,7 +35,7 @@ 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/
+#   p.rdoc_pattern = /README|TODO|LICENSE|CHANGELOG|BENCH|COMPAT|exceptions|behaviors|rails.rb|memcached.rb/
 # end
 # 
 # task :exceptions do
@@ -49,3 +49,11 @@ end
 #     end
 #   end
 # end
+# 
+# task :valgrind do
+#   exec("valgrind  --tool=memcheck --leak-check=yes --show-reachable=no --num-callers=15 --track-fds=yes ruby #{File.dirname(__FILE__)}/test/profile/valgrind.rb")
+# end
+# 
+# task :profile do
+#  exec("ruby #{File.dirname(__FILE__)}/test/profile/profile.rb")
+# end