memcache-client 1.0.3

data/Manifest.txt

@@ -0,0 +1,5 @@
+Manifest.txt
+README
+Rakefile
+lib/memcache.rb
+lib/memcache_util.rb

data/README

@@ -0,0 +1,44 @@
+= memcache-client
+
+Rubyforge Project:
+
+http://rubyforge.org/projects/rctools/
+
+== About
+
+memcache-client is a fast memcached client.
+
+== Installing memcache-client
+
+Just install the gem
+
+  $ sudo gem install memcache-client
+
+== Using memcache-client
+
+  CACHE = MemCache.new :c_threshold => 10_000,
+                       :compression => true,
+                       :debug => false,
+                       :namespace => 'my_namespace',
+                       :readonly => false,
+                       :urlencode => false
+  CACHE.servers = 'localhost:11211'
+
+You can specify multiple servers by sending an Array of servers to #servers=.
+
+=== Using memcache-client with Rails
+
+Rails will automatically load the memcache-client gem, but you may wish to
+uninstall Ruby-memcache, I don't know which one it will pick by default.
+
+Add your environment-specific caches to config/environment/*.  If you run both
+development and production on the same machine be sure to use different
+namespaces.  Be careful when running tests under memcache, you may get strange
+results, it will be less of a headache to simply use a readonly memcache when
+testing.
+
+memcache-client also comes with a wrapper called Cache in memcache_util.rb for
+use with Rails.  To use it be sure to assign your memcache connection to
+CACHE.  Cache returns nil on all memcache errors so you don't have to rescue
+yourself.  It has #get, #put and #delete module functions.
+

data/Rakefile

@@ -0,0 +1,55 @@
+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 ]
+
+Rake::TestTask.new('test') do |t|
+  t.libs << 'test'
+  t.pattern = 'test/test_*.rb'
+  t.verbose = true
+end
+
+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
+
+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
+
+desc 'Build Gem'
+Rake::GemPackageTask.new spec do |pkg|
+  pkg.need_tar = true
+end
+
+desc 'Clean up'
+task :clean => [ :clobber_rdoc, :clobber_package ]
+
+desc 'Clean up'
+task :clobber => [ :clean ]
+
+# vim: syntax=Ruby
+

data/lib/memcache.rb

@@ -0,0 +1,361 @@
+require 'socket'
+require 'thread'
+
+# 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)
+    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(host, port, weight)
+            when Server
+                server
+            else
+                raise TypeError, "Cannot convert %s to MemCache::Server" %
+                    svr.class.name
+            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
+    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)
+
+            sock = server.socket
+            if sock.nil?
+                raise MemCacheError, "No connection to server"
+            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
+
+            # Return the unmarshaled value.
+            begin
+                return Marshal.load(value)
+            rescue ArgumentError, TypeError => err
+                server.close
+                raise MemCacheError, err.message
+            end
+        end
+    end
+
+    # 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
+
+            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
+
+    # 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)
+
+            sock = server.socket
+            if sock.nil?
+                raise MemCacheError, "No connection to server"
+            end
+
+            begin
+                sock.write "delete #{cache_key} #{expiry}\r\n"
+                sock.gets
+            rescue SystemCallError, IOError => err
+                server.close
+                raise MemCacheError, err.message
+            end
+        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
+
+    # 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
+
+    # 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}"
+    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" unless server
+        server
+    end
+
+    
+    ###########################################################################
+    # 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
+
+            @host   = host
+            @port   = port.to_i
+            @weight = weight.to_i
+
+            @sock   = nil
+            @retry  = nil
+            @status = "NOT CONNECTED"
+        end
+
+        # Return a string representation of the server object.
+        def inspect
+            sprintf("<MemCache::Server: %s:%d [%d] (%s)>",
+                    @host, @port, @weight, @status)
+        end
+
+        # 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
+
+        # 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
+
+        # 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
+
+        # 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
+    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
+    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
+    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
+        end
+    end
+end

data/lib/memcache_util.rb

@@ -0,0 +1,68 @@
+##
+# A utility wrapper around the MemCache client to simplify cache access.  All
+# methods silently ignore MemCache errors.
+
+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.
+
+    def self.get(key)
+        start_time = Time.now.to_f
+        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))
+        return result
+    rescue MemCache::MemCacheError => err
+        # MemCache error is a cache miss.
+        ActiveRecord::Base.logger.debug("MemCache Error: #{err.message}")
+        return nil
+    end
+
+    ##
+    # Places +value+ in the cache at +key+, with an optional +expiry+ time in
+    # seconds. (?)
+
+    def self.put(key, value, expiry = 0)
+        start_time = Time.now.to_f
+        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))
+    rescue MemCache::MemCacheError => err
+        # Ignore put failure.
+        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
+        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))
+    rescue MemCache::MemCacheError => err
+        # Ignore delete failure.
+        ActiveRecord::Base.logger.debug("MemCache Error: #{err.message}")
+    end
+
+    ##
+    # Resets all connections to mecache servers.
+
+    def self.reset
+        CACHE.reset
+        ActiveRecord::Base.logger.debug("MemCache Reset")
+    end
+    
+end
+
+# vim: ts=4 sts=4 sw=4
+

metadata

@@ -0,0 +1,49 @@
+--- !ruby/object:Gem::Specification 
+rubygems_version: 0.8.11.6
+specification_version: 1
+name: memcache-client
+version: !ruby/object:Gem::Version 
+  version: 1.0.3
+date: 2006-01-17 00:00:00 -08:00
+summary: A Ruby memcached client
+require_paths: 
+- lib
+email: bob@robotcoop.com
+homepage: 
+rubyforge_project: 
+description: 
+autorequire: 
+default_executable: 
+bindir: bin
+has_rdoc: true
+required_ruby_version: !ruby/object:Gem::Version::Requirement 
+  requirements: 
+  - - ">"
+    - !ruby/object:Gem::Version 
+      version: 0.0.0
+  version: 
+platform: ruby
+signing_key: 
+cert_chain: 
+authors: 
+- Robert Cottrell
+files: 
+- Manifest.txt
+- README
+- Rakefile
+- lib/memcache.rb
+- lib/memcache_util.rb
+test_files: []
+
+rdoc_options: []
+
+extra_rdoc_files: []
+
+executables: []
+
+extensions: []
+
+requirements: []
+
+dependencies: []
+