memcache-client 1.6.3 → 1.6.5

data/History.txt

@@ -1,3 +1,26 @@
+= 1.6.5 (2009-02-27)
+
+* Change memcache-client to multithreaded by default.  The mutex does not add significant
+  overhead and it is far too easy, now that Sinatra, Rails and Merb are all thread-safe, to
+  use memcache-client in a thread-unsafe manner.  Remove some unnecessary mutexing and add
+  a test to verify heavily multithreaded usage does not act unexpectedly.
+
+* Add optional support for the SystemTimer gem when running on Ruby 1.8.x.  This gem is
+  highly recommended - it ensures timeouts actually work and halves the overhead of using
+  timeouts.  Using this gem, Ruby 1.8.x is actually faster in my performance tests
+  than Ruby 1.9.x.  Just "gem install SystemTimer" and it should be picked up automatically.
+
+= 1.6.4 (2009-02-19)
+
+* Remove native code altogether.  The speedup was only 10% on Ruby 1.8.6 and did not work
+  on Ruby 1.9.1.
+
+* Removed memcache_util.rb from the distribution.  If you are using it, please copy the code
+  into your own project.  The file will live in the github repository for a few more months
+  for this purposes. http://github.com/mperham/memcache-client/raw/7a276089aa3c914e47e3960f9740ac7377204970/lib/memcache_util.rb
+
+* Roll continuum.rb into memcache.rb.  The project is again a single Ruby file, with no dependencies.
+
 = 1.6.3 (2009-02-14)
 
 * Remove gem native extension in preference to RubyInline.  This allows the gem to install

data/README.rdoc

@@ -16,22 +16,24 @@ Just install the gem:
 
 With one server:
 
-  CACHE = MemCache.new 'localhost:11211', :namespace => 'my_namespace'
+  CACHE = MemCache.new 'localhost:11211'
 
 Or with multiple servers:
 
-  CACHE = MemCache.new %w[one.example.com:11211 two.example.com:11211],
-                       :namespace => 'my_namespace'
+  CACHE = MemCache.new %w[one.example.com:11211 two.example.com:11211]
+
+
+== Tuning memcache-client
+
+The MemCache.new method takes a number of options which can be useful at times.  Please
+read the source comments there for an overview.
 
-See MemCache.new for details.  Please note memcache-client is not thread-safe
-by default.  You should create a separate instance for each thread in your
-process.
 
 == Using memcache-client with Rails
 
-There's no need to use memcache-client in a Rails application.  Rails 2.1+ includes
-a basic caching library which can be used with memcached.  See ActiveSupport::Cache::Store
-for more details.
+Rails 2.1+ includes memcache-client out of the box.  See ActiveSupport::Cache::MemCacheStore
+and the Rails.cache method for more details.
+
 
 == Questions?
 

data/Rakefile

@@ -11,6 +11,15 @@ task :install => [:gem] do
 	sh "sudo gem install memcache-client-*.gem"
 end
 
+task :clean do
+	sh "rm -f memcache-client-*.gem"
+end
+
+task :publish => [:clean, :gem, :install] do
+	require 'lib/memcache'
+	sh "rubyforge add_release seattlerb memcache-client #{MemCache::VERSION} memcache-client-#{MemCache::VERSION}.gem"
+end
+
 Rake::RDocTask.new do |rd|
 	rd.main = "README.rdoc"
 	rd.rdoc_files.include("README.rdoc", "lib/**/*.rb")
@@ -23,4 +32,4 @@ task :default => :test
 
 task :rcov do
   `rcov -Ilib test/*.rb`
-end
+end

data/lib/memcache.rb

@@ -2,11 +2,27 @@ $TESTING = defined?($TESTING) && $TESTING
 
 require 'socket'
 require 'thread'
-require 'timeout'
 require 'zlib'
 require 'digest/sha1'
 
-require 'continuum'
+begin
+  # Try to use the SystemTimer gem instead of Ruby's timeout library
+  # when running on something that looks like Ruby 1.8.x.  See:
+  #   http://ph7spot.com/articles/system_timer
+  # We don't want to bother trying to load SystemTimer on jruby and
+  # ruby 1.9+.
+  if !defined?(RUBY_ENGINE)
+    require 'system_timer'
+    MemCacheTimer = SystemTimer
+  else
+    require 'timeout'
+    MemCacheTimer = Timeout
+  end
+rescue LoadError => e
+  puts "[memcache-client] Could not load SystemTimer gem, falling back to Ruby's slower/unsafe timeout library: #{e.message}"
+  require 'timeout'
+  MemCacheTimer = Timeout
+end
 
 ##
 # A Ruby client library for memcached.
@@ -17,7 +33,7 @@ class MemCache
   ##
   # The version of MemCache you are using.
 
-  VERSION = '1.6.2'
+  VERSION = '1.6.5'
 
   ##
   # Default options for the cache object.
@@ -25,7 +41,7 @@ class MemCache
   DEFAULT_OPTIONS = {
     :namespace   => nil,
     :readonly    => false,
-    :multithread => false,
+    :multithread => true,
     :failover    => true,
     :timeout     => 0.5,
     :logger      => nil,
@@ -57,7 +73,7 @@ class MemCache
   attr_reader :servers
 
   ##
-  # Socket timeout limit with this client, defaults to 0.25 sec.
+  # Socket timeout limit with this client, defaults to 0.5 sec.
   # Set to nil to disable timeouts.
 
   attr_reader :timeout
@@ -81,12 +97,14 @@ class MemCache
   #
   #   [:namespace]   Prepends this value to all keys added or retrieved.
   #   [:readonly]    Raises an exception on cache writes when true.
-  #   [:multithread] Wraps cache access in a Mutex for thread safety.
+  #   [:multithread] Wraps cache access in a Mutex for thread safety. Defaults to true.
   #   [:failover]    Should the client try to failover to another server if the
   #                  first server is down?  Defaults to true.
-  #   [:timeout]     Time to use as the socket read timeout.  Defaults to 0.25 sec,
-  #                  set to nil to disable timeouts (this is a major performance penalty in Ruby 1.8).
+  #   [:timeout]     Time to use as the socket read timeout.  Defaults to 0.5 sec,
+  #                  set to nil to disable timeouts (this is a major performance penalty in Ruby 1.8,
+  #                  "gem install SystemTimer' to remove most of the penalty).
   #   [:logger]      Logger to use for info/debug output, defaults to nil
+  #
   # Other options are ignored.
 
   def initialize(*args)
@@ -120,6 +138,8 @@ class MemCache
 
     logger.info { "memcache-client #{VERSION} #{Array(servers).inspect}" } if logger
 
+    Thread.current[:memcache_client] = self.object_id if !@multithread
+
     self.servers = servers
   end
 
@@ -160,9 +180,6 @@ class MemCache
         weight ||= DEFAULT_WEIGHT
         Server.new self, host, port, weight
       else
-        if server.multithread != @multithread then
-          raise ArgumentError, "can't mix threaded and non-threaded servers"
-        end
         server
       end
     end
@@ -220,6 +237,8 @@ class MemCache
   #   cache["a"] = 1
   #   cache["b"] = 2
   #   cache.get_multi "a", "b" # => { "a" => 1, "b" => 2 }
+  #
+  # Note that get_multi assumes the values are marshalled.
 
   def get_multi(*keys)
     raise MemCacheError, 'No active servers' unless active?
@@ -353,7 +372,6 @@ class MemCache
     raise MemCacheError, "Update of readonly cache" if @readonly
 
     begin
-      @mutex.lock if @multithread
       @servers.each do |server|
         with_socket_management(server) do |socket|
           socket.write "flush_all\r\n"
@@ -364,8 +382,6 @@ class MemCache
       end
     rescue IndexError => err
       handle_error nil, err
-    ensure
-      @mutex.unlock if @multithread
     end
   end
 
@@ -606,6 +622,8 @@ class MemCache
   # failures (but does still apply to unexpectedly lost connections etc.).
 
   def with_socket_management(server, &block)
+    check_multithread_status!
+
     @mutex.lock if @multithread
     retried = false
 
@@ -619,7 +637,7 @@ class MemCache
 
       block.call(socket)
 
-    rescue SocketError => err
+    rescue SocketError, Timeout::Error => err
       logger.warn { "Socket failure: #{err.message}" } if logger
       server.mark_dead(err)
       handle_error(server, err)
@@ -697,6 +715,18 @@ class MemCache
     ((total_servers * Continuum::POINTS_PER_SERVER * server.weight) / Float(total_weight)).floor
   end
 
+  def check_multithread_status!
+    return if @multithread
+
+    if Thread.current[:memcache_client] != self.object_id
+      raise MemCacheError, <<-EOM
+        You are accessing this memcache-client instance from multiple threads but have not enabled multithread support.
+        Normally:  MemCache.new(['localhost:11211'], :multithread => true)
+        In Rails:  config.cache_store = [:mem_cache_store, 'localhost:11211', { :multithread => true }]
+      EOM
+    end
+  end
+
   ##
   # This class represents a memcached server instance.
 
@@ -740,7 +770,6 @@ class MemCache
 
     attr_reader :status
 
-    attr_reader :multithread
     attr_reader :logger
 
     ##
@@ -755,9 +784,6 @@ class MemCache
       @port   = port.to_i
       @weight = weight.to_i
 
-      @multithread = memcache.multithread
-      @mutex = Mutex.new
-
       @sock   = nil
       @retry  = nil
       @status = 'NOT CONNECTED'
@@ -787,7 +813,6 @@ class MemCache
     # Returns the connected socket object on success or nil on failure.
 
     def socket
-      @mutex.lock if @multithread
       return @sock if @sock and not @sock.closed?
 
       @sock = nil
@@ -810,8 +835,6 @@ class MemCache
       end
 
       return @sock
-    ensure
-      @mutex.unlock if @multithread
     end
 
     ##
@@ -819,13 +842,10 @@ class MemCache
     # object.  The server is not considered dead.
 
     def close
-      @mutex.lock if @multithread
       @sock.close if @sock && !@sock.closed?
       @sock   = nil
       @retry  = nil
       @status = "NOT CONNECTED"
-    ensure
-      @mutex.unlock if @multithread
     end
 
     ##
@@ -854,26 +874,26 @@ end
 class TCPTimeoutSocket
   
   def initialize(host, port, timeout)
-    Timeout::timeout(MemCache::Server::CONNECT_TIMEOUT, SocketError) do
+    MemCacheTimer.timeout(MemCache::Server::CONNECT_TIMEOUT) do
       @sock = TCPSocket.new(host, port)
       @len = timeout
     end
   end
   
   def write(*args)
-    Timeout::timeout(@len, SocketError) do
+    MemCacheTimer.timeout(@len) do
       @sock.write(*args)
     end
   end
   
   def gets(*args)
-    Timeout::timeout(@len, SocketError) do
+    MemCacheTimer.timeout(@len) do
       @sock.gets(*args)
     end
   end
   
   def read(*args)
-    Timeout::timeout(@len, SocketError) do
+    MemCacheTimer.timeout(@len) do
       @sock.read(*args)
     end
   end
@@ -894,3 +914,42 @@ class TCPTimeoutSocket
     @sock.close
   end
 end
+
+module Continuum
+  POINTS_PER_SERVER = 160 # this is the default in libmemcached
+
+  # Find the closest index in Continuum with value <= the given value
+  def self.binary_search(ary, value, &block)
+    upper = ary.size - 1
+    lower = 0
+    idx = 0
+
+    while(lower <= upper) do
+      idx = (lower + upper) / 2
+      comp = ary[idx].value <=> value
+
+      if comp == 0
+        return idx
+      elsif comp > 0
+        upper = idx - 1
+      else
+        lower = idx + 1
+      end
+    end
+    return upper
+  end
+
+  class Entry
+    attr_reader :value
+    attr_reader :server
+
+    def initialize(val, srv)
+      @value = val
+      @server = srv
+    end
+
+    def inspect
+      "<#{value}, #{server.host}:#{server.port}>"
+    end
+  end
+end

data/test/test_mem_cache.rb

@@ -10,9 +10,10 @@ rescue LoadError => e
   puts "Some tests require flexmock, please run `gem install flexmock`"
 end
 
+Thread.abort_on_exception = true
 $TESTING = true
 
-require File.dirname(__FILE__) + '/../lib/memcache'
+require File.dirname(__FILE__) + '/../lib/memcache' if not defined?(MemCache)
 
 class MemCache
 
@@ -79,7 +80,7 @@ end
 
 class FakeServer
 
-  attr_reader :host, :port, :socket, :weight, :multithread, :status
+  attr_accessor :host, :port, :socket, :weight, :multithread, :status
 
   def initialize(socket = nil)
     @closed = false
@@ -87,7 +88,7 @@ class FakeServer
     @port = 11211
     @socket = socket || FakeSocket.new
     @weight = 1
-    @multithread = false
+    @multithread = true
     @status = "CONNECTED"
   end
 
@@ -117,9 +118,9 @@ class TestMemCache < Test::Unit::TestCase
 
   def test_performance
     requirement(memcached_running?, 'A real memcached server must be running for performance testing') do
-      host = Socket.gethostname
 
-      cache = MemCache.new(['localhost:11211',"#{host}:11211"])
+      cache = MemCache.new(['localhost:11211',"127.0.0.1:11211"])
+      cache.flush_all
       cache.add('a', 1, 120)
       with = xprofile 'get' do
         1000.times do
@@ -129,7 +130,7 @@ class TestMemCache < Test::Unit::TestCase
       puts ''
       puts "1000 gets with socket timeout: #{with} sec"
 
-      cache = MemCache.new(['localhost:11211',"#{host}:11211"], :timeout => nil)
+      cache = MemCache.new(['localhost:11211',"127.0.0.1:11211"], :timeout => nil)
       cache.add('a', 1, 120)
       without = xprofile 'get' do
         1000.times do
@@ -333,6 +334,34 @@ class TestMemCache < Test::Unit::TestCase
     assert !server.alive?
   end
 
+  def test_multithread_error
+    server = FakeServer.new
+    server.multithread = false
+    
+    @cache = MemCache.new(['localhost:1'], :multithread => false)
+
+    server.socket.data.write "bogus response\r\nbogus response\r\n"
+    server.socket.data.rewind
+
+    @cache.servers = []
+    @cache.servers << server
+
+    assert_nothing_raised do
+      @cache.set 'a', 1
+    end
+
+    passed = true
+    Thread.new do
+      begin
+        @cache.set 'b', 2
+        passed = false
+      rescue MemCache::MemCacheError => me
+        passed = me.message =~ /multiple threads/
+      end
+    end
+    assert passed
+  end
+
   def test_initialize
     cache = MemCache.new :namespace => 'my_namespace', :readonly => true
 
@@ -946,5 +975,37 @@ class TestMemCache < Test::Unit::TestCase
     return server
   end
 
+  def test_crazy_multithreaded_access
+    requirement(memcached_running?, 'A real memcached server must be running for performance testing') do
+
+      cache = MemCache.new(['localhost:11211', '127.0.0.1:11211'])
+      cache.flush_all
+      workers = []
+
+      # Have a bunch of threads perform a bunch of operations at the same time.
+      # Verify the result of each operation to ensure the request and response
+      # are not intermingled between threads.
+      10.times do
+        workers << Thread.new do
+          100.times do
+            cache.set('a', 9)
+            cache.set('b', 11)
+            cache.add('c', 10, 0, true)
+            assert_equal "NOT_STORED\r\n", cache.add('a', 11)
+            assert_equal({ 'a' => 9, 'b' => 11 }, cache.get_multi(['a', 'b']))
+            inc = cache.incr('c', 10)
+            assert_equal 0, inc % 5
+            assert inc > 14
+            assert cache.decr('c', 5) > 14
+            assert_equal 11, cache.get('b')
+          end
+        end
+      end
+
+      workers.each { |w| w.join }
+      cache.flush_all
+    end
+  end
+
 end
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification 
 name: memcache-client
 version: !ruby/object:Gem::Version 
-  version: 1.6.3
+  version: 1.6.5
 platform: ruby
 authors: 
 - Eric Hodel
@@ -11,20 +11,10 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2009-02-14 00:00:00 -06:00
+date: 2009-02-27 00:00:00 -06:00
 default_executable: 
-dependencies: 
-- !ruby/object:Gem::Dependency 
-  name: 
-  - RubyInline
-  type: :runtime
-  version_requirement: 
-  version_requirements: !ruby/object:Gem::Requirement 
-    requirements: 
-    - - ">="
-      - !ruby/object:Gem::Version 
-        version: "0"
-    version: 
+dependencies: []
+
 description: A Ruby library for accessing memcached.
 email: mperham@gmail.com
 executables: []
@@ -38,9 +28,7 @@ files:
 - LICENSE.txt
 - History.txt
 - Rakefile
-- lib/continuum.rb
 - lib/memcache.rb
-- lib/memcache_util.rb
 has_rdoc: false
 homepage: http://github.com/mperham/memcache-client
 post_install_message: 

data/lib/continuum.rb

@@ -1,77 +0,0 @@
-module Continuum
-  POINTS_PER_SERVER = 160 # this is the default in libmemcached
-
-  class << self
-
-    begin
-      require 'inline'
-      inline do |builder|
-        builder.c <<-EOM
-        int binary_search(VALUE ary, unsigned int r) {
-            int upper = RARRAY_LEN(ary) - 1;
-            int lower = 0;
-            int idx = 0;
-            ID value = rb_intern("value");
-
-            while (lower <= upper) {
-                idx = (lower + upper) / 2;
-
-                VALUE continuumValue = rb_funcall(RARRAY_PTR(ary)[idx], value, 0);
-                unsigned int l = NUM2UINT(continuumValue);
-                if (l == r) {
-                    return idx;
-                }
-                else if (l > r) {
-                    upper = idx - 1;
-                }
-                else {
-                    lower = idx + 1;
-                }
-            }
-            return upper;
-        }
-        EOM
-      end
-    rescue Exception => e
-      puts "Unable to generate native code, falling back to Ruby: #{e.message}"
-
-      # slow but pure ruby version
-      # Find the closest index in Continuum with value <= the given value
-      def binary_search(ary, value, &block)
-        upper = ary.size - 1
-        lower = 0
-        idx = 0
-
-        while(lower <= upper) do
-          idx = (lower + upper) / 2
-          comp = ary[idx].value <=> value
-
-          if comp == 0
-            return idx
-          elsif comp > 0
-            upper = idx - 1
-          else
-            lower = idx + 1
-          end
-        end
-        return upper
-      end
-
-    end
-  end
-
-
-  class Entry
-    attr_reader :value
-    attr_reader :server
-
-    def initialize(val, srv)
-      @value = val
-      @server = srv
-    end
-
-    def inspect
-      "<#{value}, #{server.host}:#{server.port}>"
-    end
-  end
-end

data/lib/memcache_util.rb

@@ -1,102 +0,0 @@
-##
-# A utility wrapper around the MemCache client to simplify cache access.  All
-# methods silently ignore MemCache errors.
-
-module Cache
-  
-  ##
-  # Try to return a logger object that does not rely
-  # on ActiveRecord for logging.
-  def self.logger
-    @logger ||= if defined? Rails.logger # Rails 2.1 +
-      Rails.logger
-    elsif defined? RAILS_DEFAULT_LOGGER # Rails 1.2.2 +
-      RAILS_DEFAULT_LOGGER
-    else
-      ActiveRecord::Base.logger # ... very old Rails.
-    end
-  end
-  ##
-  # Returns the object at +key+ from the cache if successful, or nil if either
-  # the object is not in the cache or if there was an error attermpting to
-  # access the cache.
-  #
-  # If there is a cache miss and a block is given the result of the block will
-  # be stored in the cache with optional +expiry+, using the +add+ method rather
-  # than +set+.
-
-  def self.get(key, expiry = 0)
-    start_time = Time.now
-    value = CACHE.get key
-    elapsed = Time.now - start_time
-    logger.debug('MemCache Get (%0.6f)  %s' % [elapsed, key])
-    if value.nil? and block_given? then
-      value = yield
-      add key, value, expiry
-    end
-    value
-  rescue MemCache::MemCacheError => err
-    logger.debug "MemCache Error: #{err.message}"
-    if block_given? then
-      value = yield
-      put key, value, expiry
-    end
-    value
-  end
-
-  ##
-  # Sets +value+ in the cache at +key+, with an optional +expiry+ time in
-  # seconds.
-
-  def self.put(key, value, expiry = 0)
-    start_time = Time.now
-    CACHE.set key, value, expiry
-    elapsed = Time.now - start_time
-    logger.debug('MemCache Set (%0.6f)  %s' % [elapsed, key])
-    value
-  rescue MemCache::MemCacheError => err
-    ActiveRecord::Base.logger.debug "MemCache Error: #{err.message}"
-    nil
-  end
-
-  ##
-  # Sets +value+ in the cache at +key+, with an optional +expiry+ time in
-  # seconds.  If +key+ already exists in cache, returns nil.
-
-  def self.add(key, value, expiry = 0)
-    start_time = Time.now
-    response = CACHE.add key, value, expiry
-    elapsed = Time.now - start_time
-    logger.debug('MemCache Add (%0.6f)  %s' % [elapsed, key])
-    (response == "STORED\r\n") ? value : nil
-  rescue MemCache::MemCacheError => err
-    ActiveRecord::Base.logger.debug "MemCache Error: #{err.message}"
-    nil
-  end
-
-  ##
-  # Deletes +key+ from the cache in +delay+ seconds.
-
-  def self.delete(key, delay = nil)
-    start_time = Time.now
-    CACHE.delete key, delay
-    elapsed = Time.now - start_time
-    logger.debug('MemCache Delete (%0.6f)  %s' %
-                                    [elapsed, key])
-    nil
-  rescue MemCache::MemCacheError => err
-    logger.debug "MemCache Error: #{err.message}"
-    nil
-  end
-
-  ##
-  # Resets all connections to MemCache servers.
-
-  def self.reset
-    CACHE.reset
-    logger.debug 'MemCache Connections Reset'
-    nil
-  end
-
-end
-