memcache-client 1.0.3 → 1.1.0

data/History.txt

@@ -0,0 +1,12 @@
+= 1.1.0
+
+* Added some tests
+* Sped up non-multithreaded and multithreaded operation
+* More Ruby-memcache compatibility
+* More RDoc
+* Switched to Hoe
+
+= 1.0.0
+
+Birthday!
+

data/LICENSE.txt

@@ -0,0 +1,30 @@
+All original code copyright 2005 Bob Cottrell, The Robot Co-op.  All rights
+reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions
+are met:
+
+1. Redistributions of source code must retain the above copyright
+   notice, this list of conditions and the following disclaimer.
+2. Redistributions in binary form must reproduce the above copyright
+   notice, this list of conditions and the following disclaimer in the
+   documentation and/or other materials provided with the distribution.
+3. Neither the names of the authors nor the names of their contributors
+   may be used to endorse or promote products derived from this software
+   without specific prior written permission.
+4. Redistribution in Rails or any sub-projects of Rails is not allowed
+   until Rails runs without warnings with the ``-W2'' flag enabled.
+
+THIS SOFTWARE IS PROVIDED BY THE AUTHORS ``AS IS'' AND ANY EXPRESS
+OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
+WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHORS OR CONTRIBUTORS BE
+LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY,
+OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT
+OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR
+BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
+WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE
+OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
+EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+

data/Manifest.txt

@@ -1,5 +1,8 @@
+History.txt
+LICENSE.txt
 Manifest.txt
-README
+README.txt
 Rakefile
 lib/memcache.rb
 lib/memcache_util.rb
+test/test_memcache.rb

data/Rakefile

@@ -1,55 +1,18 @@
-require 'rubygems'
-require 'rake'
-require 'rake/testtask'
-require 'rake/rdoctask'
-require 'rake/gempackagetask'
-
-$VERBOSE = nil
-
-spec = Gem::Specification.new do |s|
-  s.name = 'memcache-client'
-  s.version = '1.0.3'
-  s.summary = 'A Ruby memcached client'
-  s.author = 'Robert Cottrell'
-  s.email = 'bob@robotcoop.com'
-
-  s.has_rdoc = true
-  s.files = File.read('Manifest.txt').split($/)
-  s.require_path = 'lib'
-end
-
-desc 'Run tests'
-task :default => [ :test ]
+# vim: syntax=Ruby
 
-Rake::TestTask.new('test') do |t|
-  t.libs << 'test'
-  t.pattern = 'test/test_*.rb'
-  t.verbose = true
-end
+require 'hoe'
 
-desc 'Update Manifest.txt'
-task :update_manifest do
-  sh "find . -type f | sed -e 's%./%%' | egrep -v 'svn|swp|~' | egrep -v '^(doc|pkg)/' | sort > Manifest.txt"
-end
+DEV_DOC_PATH = "Libraries/memcache-client"
 
-desc 'Generate RDoc'
-Rake::RDocTask.new :rdoc do |rd|
-  rd.rdoc_dir = 'doc'
-  rd.rdoc_files.add 'lib', 'README', 'LICENSE'
-  rd.main = 'README'
-  rd.options << '-d' if `which dot` =~ /\/dot/
-end
+SPEC = Hoe.new 'memcache-client', '1.1.0' do |p|
+  p.summary = 'A Ruby memcached client'
+  p.description = 'memcache-client is a pure-ruby client to Danga\'s memcached.'
+  p.author = 'Robert Cottrell'
+  p.email = 'eric@robotcoop.com'
+  p.url = "http://dev.robotcoop.com/#{DEV_DOC_PATH}"
 
-desc 'Build Gem'
-Rake::GemPackageTask.new spec do |pkg|
-  pkg.need_tar = true
+  p.rubyforge_name = 'rctools'
 end
 
-desc 'Clean up'
-task :clean => [ :clobber_rdoc, :clobber_package ]
-
-desc 'Clean up'
-task :clobber => [ :clean ]
-
-# vim: syntax=Ruby
+require '../tasks'
 

data/lib/memcache.rb

@@ -1,361 +1,445 @@
+$TESTING = defined? $TESTING
+
 require 'socket'
 require 'thread'
+require 'timeout'
+require 'rubygems'
 
+##
 # A Ruby client library for memcached.
 #
 # This is intended to provide access to basic memcached functionality.  It
 # does not attempt to be complete implementation of the entire API.
-#
-# In particular, the methods of this class are not thread safe.  The calling
-# application is responsible for implementing any necessary locking if a cache
-# object will be called from multiple threads.
+
 class MemCache
-    # Patterns for matching against server error replies.
-    GENERAL_ERROR = /^ERROR\r\n/
-    CLIENT_ERROR  = /^CLIENT_ERROR/
-    SERVER_ERROR  = /^SERVER_ERROR/
-
-    # Default options for the cache object.
-    DEFAULT_OPTIONS = {
-        :namespace => nil,
-        :readonly  => false
-    }
-
-    # Default memcached port.
-    DEFAULT_PORT = 11211
-
-    # Default memcached server weight.
-    DEFAULT_WEIGHT = 1
-
-    # The amount of time to wait for a response from a memcached server.  If a
-    # response is not completed within this time, the connection to the server
-    # will be closed and an error will be raised.
-    attr_accessor :request_timeout
-   
-    # Valid options are:
-    #
-    #     :namespace
-    #         If specified, all keys will have the given value prepended
-    #         before accessing the cache.  Defaults to nil.
-    #
-    #     :readonly
-    #         If this is set, any attempt to write to the cache will generate
-    #         an exception.  Defaults to false.
-    # 
-    def initialize(opts = {})
-        opts = DEFAULT_OPTIONS.merge(opts)   
-        @namespace = opts[:namespace]
-        @readonly  = opts[:readonly]
-        @mutex     = Mutex.new
-        @servers   = []
-        @buckets   = []
-    end
 
-    # Return a string representation of the cache object.
-    def inspect
-        sprintf("<MemCache: %s servers, %s buckets, ns: %p, ro: %p>",
-                @servers.nitems, @buckets.nitems, @namespace, @readonly)
+  ##
+  # Default options for the cache object.
+
+  DEFAULT_OPTIONS = {
+    :namespace   => nil,
+    :readonly    => false,
+    :multithread => false,
+  }
+
+  ##
+  # Default memcached port.
+
+  DEFAULT_PORT = 11211
+
+  ##
+  # Default memcached server weight.
+
+  DEFAULT_WEIGHT = 1
+
+  ##
+  # The amount of time to wait for a response from a memcached server.  If a
+  # response is not completed within this time, the connection to the server
+  # will be closed and an error will be raised.
+
+  attr_accessor :request_timeout
+
+  ##
+  # The namespace for this instance
+
+  attr_reader :namespace
+
+  ##
+  # The multithread setting for this instance
+
+  attr_reader :multithread
+
+  ##
+  # Accepts a list of +servers+ and a list of +opts+.  +servers+ may be
+  # omitted.  See +servers=+ for acceptable server list arguments.
+  # 
+  # Valid options for +opts+ are:
+  #
+  #   [:namespace]   Prepends this value to all keys added or retrieved.
+  #   [:readonly]    Raises an exeception on cache writes when true.
+  #   [:multithread] Wraps cache access in a Mutex for thread safety.
+
+  def initialize(*args)
+    servers = []
+    opts = {}
+
+    case args.length
+    when 0 then # NOP
+    when 1 then
+      arg = args.shift
+      case arg
+      when Hash   then opts = arg
+      when Array  then servers = arg
+      when String then servers = [arg]
+      else raise ArgumentError, 'first argument must be Array, Hash or String'
+      end
+    when 2 then
+      servers, opts = args
+    else
+      raise ArgumentError, "wrong number of arguments (#{args.length} for 2)"
     end
 
-    # Returns whether there is at least one active server for the object.
-    def active?
-        not @servers.empty?
+    opts = DEFAULT_OPTIONS.merge opts
+    @namespace   = opts[:namespace]
+    @readonly    = opts[:readonly]
+    @multithread = opts[:multithread]
+    @mutex       = Mutex.new if @multithread
+    self.servers = servers
+    @buckets     = []
+  end
+
+  ##
+  # Return a string representation of the cache object.
+
+  def inspect
+    sprintf("<MemCache: %s servers, %s buckets, ns: %p, ro: %p>",
+            @servers.length, @buckets.length, @namespace, @readonly)
+  end
+
+  ##
+  # Returns whether there is at least one active server for the object.
+
+  def active?
+    not @servers.empty?
+  end
+
+  ##
+  # Returns whether the cache was created read only.
+
+  def readonly?
+    @readonly
+  end
+
+  ##
+  # Set the servers that the requests will be distributed between.  Entries
+  # can be either strings of the form "hostname:port" or
+  # "hostname:port:weight" or MemCache::Server objects.
+
+  def servers=(servers)
+    # Create the server objects.
+    @servers = servers.collect do |server|
+      case server
+      when String
+        host, port, weight = server.split ':', 3
+        port ||= DEFAULT_PORT
+        weight ||= DEFAULT_WEIGHT
+        Server.new self, host, port, weight
+      when Server
+        if server.memcache.multithread != @multithread then
+          raise ArgumentError, "can't mix threaded and non-threaded servers"
+        end
+        server
+      else
+        raise TypeError, "Cannot convert %s to MemCache::Server" %
+        svr.class.name
+      end
     end
-    
-    # Returns whether the cache was created read only.
-    def readonly?
-        @readonly
+
+    # Create an array of server buckets for weight selection of servers.
+    @buckets = []
+    @servers.each do |server|
+      server.weight.times { @buckets.push(server) }
     end
+  end
+
+  ##
+  # Retrieves +key+ from memcache.
+
+  def get(key)
+    raise MemCacheError, 'No active servers' unless active?
+    cache_key = make_cache_key key
+    server = get_server_for_key cache_key
 
-    # Set the servers that the requests will be distributed between.  Entries
-    # can be either strings of the form "hostname:port" or
-    # "hostname:port:weight" or MemCache::Server objects.
-    def servers=(servers)
-        # Create the server objects.
-        @servers = servers.collect do |server|
-            case server
-            when String
-                host, port, weight = server.split(/:/, 3)
-                port ||= DEFAULT_PORT
-                weight ||= DEFAULT_WEIGHT
-                Server::new(host, port, weight)
-            when Server
-                server
+    raise MemCacheError, 'No connection to server' if server.socket.nil?
+
+    value = if @multithread then
+              threadsafe_cache_get server, cache_key
             else
-                raise TypeError, "Cannot convert %s to MemCache::Server" %
-                    svr.class.name
+              cache_get server, cache_key
             end
-        end
 
-        # Create an array of server buckets for weight selection of servers.
-        @buckets = []
-        @servers.each do |server|
-            server.weight.times { @buckets.push(server) }
-        end
+    return nil if value.nil?
+
+    # Return the unmarshaled value.
+    return Marshal.load(value)
+  rescue ArgumentError, TypeError, SystemCallError, IOError => err
+    server.close
+    new_err = MemCacheError.new err.message
+    new_err.set_backtrace err.backtrace
+    raise new_err
+  end
+
+  ##
+  # Add +key+ to the cache with value +value+ that expires in +expiry+
+  # seconds.
+
+  def set(key, value, expiry = 0)
+    raise MemCacheError, "No active servers" unless self.active?
+    raise MemCacheError, "Update of readonly cache" if @readonly
+    cache_key = make_cache_key(key)
+    server = get_server_for_key(cache_key)
+
+    sock = server.socket
+    raise MemCacheError, "No connection to server" if sock.nil?
+
+    marshaled_value = Marshal.dump value
+    command = "set #{cache_key} 0 #{expiry} #{marshaled_value.size}\r\n#{marshaled_value}\r\n"
+
+    begin
+      @mutex.synchronize do
+        sock.write command
+        sock.gets
+      end
+    rescue SystemCallError, IOError => err
+      server.close
+      raise MemCacheError, err.message
     end
+  end
+
+  ##
+  # Removes +key+ from the cache in +expiry+ seconds.
+
+  def delete(key, expiry = 0)
+    raise MemCacheError, "No active servers" unless active?
+    cache_key = make_cache_key key
+    server = get_server_for_key cache_key
+
+    sock = server.socket
+    raise MemCacheError, "No connection to server" if sock.nil?
+
+    begin
+      @mutex.synchronize do
+        sock.write "delete #{cache_key} #{expiry}\r\n"
+        sock.gets
+      end
+    rescue SystemCallError, IOError => err
+      server.close
+      raise MemCacheError, err.message
+    end
+  end
 
-    def get(key)
-        @mutex.synchronize do
-            raise MemCacheError, "No active servers" unless self.active?
-            cache_key = make_cache_key(key)
-            server = get_server_for_key(cache_key)
+  ##
+  # Reset the connection to all memcache servers.  This should be called if
+  # there is a problem with a cache lookup that might have left the connection
+  # in a corrupted state.
 
-            sock = server.socket
-            if sock.nil?
-                raise MemCacheError, "No connection to server"
-            end
+  def reset
+    @servers.each { |server| server.close }
+  end
 
-            value = nil
-            begin
-                sock.write "get #{cache_key}\r\n"
-                text = sock.gets # "VALUE <key> <flags> <bytes>\r\n"
-                return nil if text =~ /^END/ # HACK: no regex
-
-                v, cache_key, flags, bytes = text.split(/ /)
-                value = sock.read(bytes.to_i)
-                sock.read(2) # "\r\n"
-                sock.gets    # "END\r\n"
-            rescue SystemCallError, IOError => err
-                server.close
-                raise MemCacheError, err.message
-            end
+  ##
+  # Shortcut to get a value from the cache.
 
-            # Return the unmarshaled value.
-            begin
-                return Marshal.load(value)
-            rescue ArgumentError, TypeError => err
-                server.close
-                raise MemCacheError, err.message
-            end
-        end
-    end
+  alias [] get
 
-    # Add an entry to the cache.
-    def set(key, value, expiry = 0)
-        @mutex.synchronize do
-            raise MemCacheError, "No active servers" unless self.active?
-            raise MemCacheError, "Update of readonly cache" if @readonly
-            cache_key = make_cache_key(key)
-            server = get_server_for_key(cache_key)
-
-            sock = server.socket
-            if sock.nil?
-                raise MemCacheError, "No connection to server"
-            end
+  ##
+  # Shortcut to save a value in the cache.  This method does not set an
+  # expiration on the entry.  Use set to specify an explicit expiry.
 
-            marshaled_value = Marshal.dump(value)
-            command = "set #{cache_key} 0 #{expiry} #{marshaled_value.size}\r\n" + marshaled_value + "\r\n"
-            begin
-                sock.write command
-                sock.gets
-            rescue SystemCallError, IOError => err
-                server.close
-                raise MemCacheError, err.message
-            end
-        end
-    end
+  def []=(key, value)
+    set key, value
+  end
 
-    # Remove an entry from the cache.
-    def delete(key, expiry = 0)
-        @mutex.synchronize do
-            raise MemCacheError, "No active servers" unless self.active?
-            cache_key = make_cache_key(key)
-            server = get_server_for_key(cache_key)
+  protected unless $TESTING
 
-            sock = server.socket
-            if sock.nil?
-                raise MemCacheError, "No connection to server"
-            end
+  ##
+  # Create a key for the cache, incorporating the namespace qualifier if
+  # requested.
 
-            begin
-                sock.write "delete #{cache_key} #{expiry}\r\n"
-                sock.gets
-            rescue SystemCallError, IOError => err
-                server.close
-                raise MemCacheError, err.message
-            end
-        end
+  def make_cache_key(key)
+    if namespace.nil? then
+      key
+    else
+      "#{@namespace}:#{key}"
     end
+  end
 
-    # Reset the connection to all memcache servers.  This should be called if
-    # there is a problem with a cache lookup that might have left the
-    # connection in a corrupted state.
-    def reset
-        @mutex.synchronize do
-            @servers.each { |server| server.close }
-        end
-    end
-    
-    # Shortcut to get a value from the cache.
-    def [](key)
-        self.get(key)
-    end
+  ##
+  # Pick a server to handle the request based on a hash of the key.
 
-    # Shortcut to save a value in the cache.  This method does not set an
-    # expiration on the entry.  Use set to specify an explicit expiry.
-    def []=(key, value)
-        self.set(key, value)
-    end
+  def get_server_for_key(key)
+    raise MemCacheError, "No servers available" if @servers.empty?
+    return @servers.first if @servers.length == 1
 
-    # Create a key for the cache, incorporating the namespace qualifier if
-    # requested.
-    protected
-    def make_cache_key(key)
-        @namespace.nil? ? key.to_s : "#{@namespace}:#{key}"
+    # Hash the value of the key to select the bucket.
+    hkey = key.hash
+
+    # Fetch a server for the given key, retrying if that server is offline.
+    20.times do |try|
+      server = @buckets[(hkey + try) % @buckets.nitems]
+      return server if server.alive?
     end
 
-    # Pick a server to handle the request based on a hash of the key.
-    def get_server_for_key(key)
-        # Easy enough if there is only one server.
-        return @servers.first if @servers.length == 1
-
-        # Hash the value of the key to select the bucket.
-        hkey = key.hash
-        
-        # Fetch a server for the given key, retrying if that server is
-        # offline.
-        server = nil
-        20.times do |tries|
-            server = @buckets[(hkey + tries) % @buckets.nitems]
-            break if server.alive?
-        end
+    raise MemCacheError, "No servers available"
+  end
 
-        raise MemCacheError, "No servers available" unless server
-        server
-    end
+  ##
+  # Fetches the raw data for +cache_key+ from +server+.  Returns nil on cache
+  # miss.
 
-    
-    ###########################################################################
-    # S E R V E R   C L A S S
-    ###########################################################################
-
-    # This class represents a memcached server instance.
-    class Server
-        # The amount of time to wait to establish a connection with a
-        # memcached server.  If a connection cannot be established within
-        # this time limit, the server will be marked as down.
-        CONNECT_TIMEOUT = 0.25
-
-        # The amount of time to wait before attempting to re-establish a
-        # connection with a server that is marked dead.
-        RETRY_DELAY = 30.0
-
-        # The host the memcached server is running on.
-        attr_reader :host
-
-        # The port the memcached server is listening on.
-        attr_reader :port
-
-        # The weight given to the server.
-        attr_reader :weight
-
-        # The time of next retry if the connection is dead.
-        attr_reader :retry
-
-        # A text status string describing the state of the server.
-        attr_reader :status
-        
-        # Create a new MemCache::Server object for the memcached instance
-        # listening on the given host and port, weighted by the given weight.
-        def initialize(host, port = DEFAULT_PORT, weight = DEFAULT_WEIGHT)
-            if host.nil? || host.empty?
-                raise ArgumentError, "No host specified"
-            elsif port.nil? || port.to_i.zero?
-                raise ArgumentError, "No port specified"
-            end
+  def cache_get(server, cache_key)
+    socket = server.socket
+    socket.write "get #{cache_key}\r\n"
+    text = socket.gets # "VALUE <key> <flags> <bytes>\r\n"
+    return nil if text == "END\r\n"
 
-            @host   = host
-            @port   = port.to_i
-            @weight = weight.to_i
+    text =~ /(\d+)\r/
+    value = socket.read $1.to_i
+    socket.read 2 # "\r\n"
+    socket.gets   # "END\r\n"
+    return value
+  end
 
-            @sock   = nil
-            @retry  = nil
-            @status = "NOT CONNECTED"
-        end
+  def threadsafe_cache_get(socket, cache_key) # :nodoc:
+    @mutex.lock
+    cache_get socket, cache_key
+  ensure
+    @mutex.unlock
+  end
 
-        # Return a string representation of the server object.
-        def inspect
-            sprintf("<MemCache::Server: %s:%d [%d] (%s)>",
-                    @host, @port, @weight, @status)
-        end
+  ##
+  # This class represents a memcached server instance.
 
-        # Check whether the server connection is alive.  This will cause the
-        # socket to attempt to connect if it isn't already connected and or if
-        # the server was previously marked as down and the retry time has
-        # been exceeded.
-        def alive?
-            !self.socket.nil?
-        end
+  class Server
 
-        # Try to connect to the memcached server targeted by this object.
-        # Returns the connected socket object on success or nil on failure.
-        def socket
-            # Attempt to connect if not already connected.
-            unless @sock || (!@sock.nil? && @sock.closed?)
-                # If the host was dead, don't retry for a while.
-                if @retry && (@retry > Time::now)
-                    @sock = nil
-                else
-                    begin
-                        @sock = timeout(CONNECT_TIMEOUT) {
-                            TCPSocket::new(@host, @port)
-                        }
-                        @retry  = nil
-                        @status = "CONNECTED"
-                    rescue SystemCallError, IOError, Timeout::Error => err
-                        self.mark_dead(err.message)
-                    end
-                end
-            end
-            @sock
-        end
+    ##
+    # The amount of time to wait to establish a connection with a memcached
+    # server.  If a connection cannot be established within this time limit,
+    # the server will be marked as down.
 
-        # Close the connection to the memcached server targeted by this
-        # object.  The server is not considered dead.
-        def close
-            @sock.close if @sock &&!@sock.closed?
-            @sock   = nil
-            @retry  = nil
-            @status = "NOT CONNECTED"
-        end
+    CONNECT_TIMEOUT = 0.25
 
-        # Mark the server as dead and close its socket.
-        def mark_dead(reason = "Unknown error")
-            @sock.close if @sock && !@sock.closed?
-            @sock   = nil
-            @retry  = Time::now + RETRY_DELAY
-            
-            @status = sprintf("DEAD: %s, will retry at %s", reason, @retry)
-        end
-    end
-    
-    
-    ###########################################################################
-    # E X C E P T I O N   C L A S S E S
-    ###########################################################################
-
-    # Base MemCache exception class.
-    class MemCacheError < ::Exception
+    ##
+    # The amount of time to wait before attempting to re-establish a
+    # connection with a server that is marked dead.
+
+    RETRY_DELAY = 30.0
+
+    ##
+    # The host the memcached server is running on.
+
+    attr_reader :host
+
+    ##
+    # The port the memcached server is listening on.
+
+    attr_reader :port
+
+    ##
+    # The weight given to the server.
+
+    attr_reader :weight
+
+    ##
+    # The time of next retry if the connection is dead.
+
+    attr_reader :retry
+
+    ##
+    # A text status string describing the state of the server.
+
+    attr_reader :status
+
+    ##
+    # Create a new MemCache::Server object for the memcached instance
+    # listening on the given host and port, weighted by the given weight.
+
+    def initialize(memcache, host, port = DEFAULT_PORT, weight = DEFAULT_WEIGHT)
+      raise ArgumentError, "No host specified" if host.nil? or host.empty?
+      raise ArgumentError, "No port specified" if port.nil? or port.to_i.zero?
+
+      @memcache = memcache
+      @host   = host
+      @port   = port.to_i
+      @weight = weight.to_i
+
+      @multithread = @memcache.multithread
+
+      @sock   = nil
+      @retry  = nil
+      @status = 'NOT CONNECTED'
     end
 
-    # MemCache internal error class.  Instances of this class mean that there
-    # is some internal error either in the memcache client library or the
-    # memcached server it is talking to.
-    class InternalError < MemCacheError
+    ##
+    # Return a string representation of the server object.
+
+    def inspect
+      sprintf("<MemCache::Server: %s:%d [%d] (%s)>",
+              @host, @port, @weight, @status)
     end
 
-    # MemCache client error class.  Instances of this class mean that a
-    # "CLIENT_ERROR" response was seen in the dialog with a memcached server.
-    class ClientError < InternalError
+    ##
+    # Check whether the server connection is alive.  This will cause the
+    # socket to attempt to connect if it isn't already connected and or if
+    # the server was previously marked as down and the retry time has
+    # been exceeded.
+
+    def alive?
+      !self.socket.nil?
     end
 
-    # MemCache server error class.  Instances of this class mean that a
-    # "SERVER_ERROR" response was seen in the dialog with a memcached server.
-    class ServerError < InternalError
-        attr_reader :server
-        
-        def initalize(server)
-            @server = server
+    ##
+    # Try to connect to the memcached server targeted by this object.
+    # 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
+
+      # If the host was dead, don't retry for a while.
+      return if @retry and @retry > Time.now
+
+      # Attempt to connect if not already connected.
+      begin
+        @sock = timeout CONNECT_TIMEOUT do
+          TCPSocket.new @host, @port
         end
+        @retry  = nil
+        @status = 'CONNECTED'
+      rescue SystemCallError, IOError, Timeout::Error => err
+        mark_dead err.message
+      end
+
+      return @sock
+    ensure
+      @mutex.unlock if @multithread
     end
+
+    ##
+    # Close the connection to the memcached server targeted by this
+    # 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
+
+    private
+
+    ##
+    # Mark the server as dead and close its socket.
+
+    def mark_dead(reason = "Unknown error")
+      @sock.close if @sock && !@sock.closed?
+      @sock   = nil
+      @retry  = Time.now + RETRY_DELAY
+
+      @status = sprintf "DEAD: %s, will retry at %s", reason, @retry
+    end
+
+  end
+
+  ##
+  # Base MemCache exception class.
+
+  class MemCacheError < RuntimeError; end
+
 end
+

data/lib/memcache_util.rb

@@ -8,50 +8,53 @@ module Cache
     # 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+.
 
-    def self.get(key)
-        start_time = Time.now.to_f
+    def self.get(key, expiry = 0)
+        start_time = Time.now
         result = CACHE.get key
-        end_time = Time.now.to_f
-        ActiveRecord::Base.logger.debug(
-            sprintf("MemCache Get (%0.6f)  %s",
-                    end_time - start_time, key))
+        end_time = Time.now
+        ActiveRecord::Base.logger.debug('MemCache Get (%0.6f)  %s' %
+                                          [end_time - start_time, key])
         return result
     rescue MemCache::MemCacheError => err
-        # MemCache error is a cache miss.
-        ActiveRecord::Base.logger.debug("MemCache Error: #{err.message}")
-        return nil
+        ActiveRecord::Base.logger.debug "MemCache Error: #{err.message}"
+        if block_given? then
+            value = yield
+            put key, value, expiry
+            return value
+        else
+            return nil
+        end
     end
 
     ##
     # Places +value+ in the cache at +key+, with an optional +expiry+ time in
-    # seconds. (?)
+    # seconds.
 
     def self.put(key, value, expiry = 0)
-        start_time = Time.now.to_f
+        start_time = Time.now
         CACHE.set key, value, expiry
-        end_time = Time.now.to_f
-        ActiveRecord::Base.logger.debug(
-            sprintf("MemCache Set (%0.6f)  %s",
-                    end_time - start_time, key))
+        end_time = Time.now
+        ActiveRecord::Base.logger.debug('MemCache Set (%0.6f)  %s' %
+                                          [end_time - start_time, key])
     rescue MemCache::MemCacheError => err
-        # Ignore put failure.
-        ActiveRecord::Base.logger.debug("MemCache Error: #{err.message}")
+        ActiveRecord::Base.logger.debug "MemCache Error: #{err.message}"
     end
 
     ##
     # Deletes +key+ from the cache in +delay+ seconds. (?)
 
     def self.delete(key, delay = nil)
-        start_time = Time.now.to_f
+        start_time = Time.now
         CACHE.delete key, delay
-        end_time = Time.now.to_f
-        ActiveRecord::Base.logger.debug(
-            sprintf("MemCache Delete (%0.6f)  %s",
-                    end_time - start_time, key))
+        end_time = Time.now
+        ActiveRecord::Base.logger.debug('MemCache Delete (%0.6f)  %s' %
+                                          [end_time - start_time, key])
     rescue MemCache::MemCacheError => err
-        # Ignore delete failure.
-        ActiveRecord::Base.logger.debug("MemCache Error: #{err.message}")
+        ActiveRecord::Base.logger.debug "MemCache Error: #{err.message}"
     end
 
     ##
@@ -59,7 +62,7 @@ module Cache
 
     def self.reset
         CACHE.reset
-        ActiveRecord::Base.logger.debug("MemCache Reset")
+        ActiveRecord::Base.logger.debug 'MemCache Connections Reset'
     end
     
 end

data/test/test_memcache.rb

@@ -0,0 +1,221 @@
+require 'stringio'
+require 'test/unit'
+
+$TESTING = true
+
+require 'memcache'
+
+class MemCache
+
+  attr_reader :servers
+  attr_writer :namespace
+
+end
+
+class FakeSocket
+
+  attr_reader :written, :data
+
+  def initialize
+    @written = StringIO.new
+    @data = StringIO.new
+  end
+
+  def write(data)
+    @written.write data
+  end
+
+  def gets
+    @data.gets
+  end
+
+  def read(arg)
+    @data.read arg
+  end
+
+end
+
+class FakeServer
+
+  attr_reader :socket
+
+  def initialize(socket = nil)
+    @socket = socket || FakeSocket.new
+  end
+
+  def close
+  end
+
+end
+
+class TestMemCache < Test::Unit::TestCase
+
+  def setup
+    @cache = MemCache.new 'localhost:1', :namespace => 'my_namespace'
+  end
+
+  def test_cache_get
+    server = util_setup_server
+
+    assert_equal "\004\b\"\0170123456789",
+                 @cache.cache_get(server, 'my_namespace:key')
+
+    assert_equal "get my_namespace:key\r\n",
+                 server.socket.written.string
+  end
+
+  def test_cache_get_miss
+    socket = FakeSocket.new
+    socket.data.write "END\r\n"
+    socket.data.rewind
+    server = FakeServer.new socket
+
+    assert_equal nil, @cache.cache_get(server, 'my_namespace:key')
+
+    assert_equal "get my_namespace:key\r\n",
+                 socket.written.string
+  end
+
+  def test_initialize
+    cache = MemCache.new :namespace => 'my_namespace', :readonly => true
+
+    assert_equal 'my_namespace', cache.namespace
+    assert_equal true, cache.readonly?
+    assert_equal true, cache.servers.empty?
+  end
+
+  def test_initialize_compatible
+    cache = MemCache.new ['localhost:11211', 'localhost:11212'],
+            :namespace => 'my_namespace', :readonly => true
+
+    assert_equal 'my_namespace', cache.namespace
+    assert_equal true, cache.readonly?
+    assert_equal false, cache.servers.empty?
+  end
+
+  def test_initialize_compatible_no_hash
+    cache = MemCache.new ['localhost:11211', 'localhost:11212']
+
+    assert_equal nil, cache.namespace
+    assert_equal false, cache.readonly?
+    assert_equal false, cache.servers.empty?
+  end
+
+  def test_initialize_compatible_one_server
+    cache = MemCache.new 'localhost:11211'
+
+    assert_equal nil, cache.namespace
+    assert_equal false, cache.readonly?
+    assert_equal false, cache.servers.empty?
+  end
+
+  def test_initialize_compatible_bad_arg
+    e = assert_raise ArgumentError do
+      cache = MemCache.new Object.new
+    end
+
+    assert_equal 'first argument must be Array, Hash or String', e.message
+  end
+
+  def test_initialize_too_many_args
+    assert_raises ArgumentError do
+      MemCache.new 1, 2, 3
+    end
+  end
+
+  def test_get
+    util_setup_server
+
+    value = @cache.get 'key'
+
+    assert_equal "get my_namespace:key\r\n",
+                 @cache.servers.first.socket.written.string
+
+    assert_equal '0123456789', value
+  end
+
+  def test_get_cache_get_IOError
+    socket = Object.new
+    def socket.write(arg) raise IOError, 'some io error'; end
+    server = FakeServer.new socket
+
+    @cache.servers = []
+    @cache.servers << server
+
+    e = assert_raise MemCache::MemCacheError do
+      @cache.get 'my_namespace:key'
+    end
+
+    assert_equal 'some io error', e.message
+  end
+
+  def test_get_cache_get_SystemCallError
+    socket = Object.new
+    def socket.write(arg) raise SystemCallError, 'some syscall error'; end
+    server = FakeServer.new socket
+
+    @cache.servers = []
+    @cache.servers << server
+
+    e = assert_raise MemCache::MemCacheError do
+      @cache.get 'my_namespace:key'
+    end
+
+    assert_equal 'unknown error - some syscall error', e.message
+  end
+
+  def test_get_no_connection
+    @cache.servers = 'localhost:1'
+    e = assert_raise MemCache::MemCacheError do
+      @cache.get 'key'
+    end
+
+    assert_equal 'No connection to server', e.message
+  end
+
+  def test_get_no_servers
+    @cache.servers = []
+    e = assert_raise MemCache::MemCacheError do
+      @cache.get 'key'
+    end
+
+    assert_equal 'No active servers', e.message
+  end
+
+  def test_get_server_for_key
+    server = @cache.get_server_for_key 'key'
+    assert_equal 'localhost', server.host
+    assert_equal 1, server.port
+  end
+
+  def test_get_server_for_key_no_servers
+    @cache.servers = []
+
+    e = assert_raise MemCache::MemCacheError do
+      @cache.get_server_for_key 'key'
+    end
+
+    assert_equal 'No servers available', e.message
+  end
+
+  def test_make_cache_key
+    assert_equal 'my_namespace:key', @cache.make_cache_key('key')
+    @cache.namespace = nil
+    assert_equal 'key', @cache.make_cache_key('key')
+  end
+
+  def util_setup_server
+    server = FakeServer.new
+    server.socket.data.write "VALUE my_namepsace:key 0 14\r\n"
+    server.socket.data.write "\004\b\"\0170123456789\r\n"
+    server.socket.data.write "END\r\n"
+    server.socket.data.rewind
+
+    @cache.servers = []
+    @cache.servers << server
+
+    return server
+  end
+
+end
+

metadata

@@ -1,17 +1,18 @@
 --- !ruby/object:Gem::Specification 
-rubygems_version: 0.8.11.6
+rubygems_version: 0.8.99
 specification_version: 1
 name: memcache-client
 version: !ruby/object:Gem::Version 
-  version: 1.0.3
-date: 2006-01-17 00:00:00 -08:00
+  version: 1.1.0
+date: 2006-09-29 00:00:00 -07:00
 summary: A Ruby memcached client
 require_paths: 
 - lib
-email: bob@robotcoop.com
-homepage: 
-rubyforge_project: 
-description: 
+- test
+email: eric@robotcoop.com
+homepage: http://dev.robotcoop.com/Libraries/memcache-client
+rubyforge_project: rctools
+description: memcache-client is a pure-ruby client to Danga's memcached.
 autorequire: 
 default_executable: 
 bindir: bin
@@ -25,14 +26,18 @@ required_ruby_version: !ruby/object:Gem::Version::Requirement
 platform: ruby
 signing_key: 
 cert_chain: 
+post_install_message: 
 authors: 
 - Robert Cottrell
 files: 
+- History.txt
+- LICENSE.txt
 - Manifest.txt
-- README
+- README.txt
 - Rakefile
 - lib/memcache.rb
 - lib/memcache_util.rb
+- test/test_memcache.rb
 test_files: []
 
 rdoc_options: []
@@ -45,5 +50,13 @@ extensions: []
 
 requirements: []
 
-dependencies: []
-
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: hoe
+  version_requirement: 
+  version_requirements: !ruby/object:Gem::Version::Requirement 
+    requirements: 
+    - - ">"
+      - !ruby/object:Gem::Version 
+        version: 0.0.0
+    version: