ramaze 2011.01.30 → 2011.07.25

data/lib/ramaze/cache.rb

@@ -1,21 +1,26 @@
 #          Copyright (c) 2009 Michael Fellinger m.fellinger@gmail.com
 # All files in this distribution are subject to the terms of the Ruby license.
-
 require 'innate/cache'
 
 module Ramaze
   Cache = Innate::Cache
 
-  # TODO: Describe what this class does and how it can be used.
+  #:nodoc:
   class Cache
     autoload :LRU,           'ramaze/cache/lru'
     autoload :LocalMemCache, 'ramaze/cache/localmemcache'
     autoload :MemCache,      'ramaze/cache/memcache'
     autoload :Sequel,        'ramaze/cache/sequel'
 
+    ##
+    # Clears the cache after a file has been reloaded.
+    #
+    # @author Michael Fellinger
+    # @since  17-07-2009
+    #
     def self.clear_after_reload
       action.clear if respond_to?(:action)
       action_value.clear if respond_to?(:action_value)
     end
-  end
-end
+  end # Cache
+end # Ramaze

data/lib/ramaze/cache/localmemcache.rb

@@ -5,7 +5,6 @@ require 'localmemcache'
 
 module Ramaze
   class Cache
-
     # Cache based on the localmemcache library which utilizes mmap to share
     # strings in memory between ruby instances.
     class LocalMemCache
@@ -19,14 +18,12 @@ module Ramaze
 
       # Connect to localmemcache
       def cache_setup(host, user, app, name)
-        @namespace = [host, user, app, name].compact.join('-')
-
-        options = {:namespace => @namespace}.merge(OPTIONS)
+        @namespace  = [host, user, app, name].compact.join('-')
+        options     = {:namespace => @namespace}.merge(OPTIONS)
 
-        @serialize = options.delete(:serialize)
+        @serialize  = options.delete(:serialize)
         @serializer = options.delete(:serializer)
-
-        @store = ::LocalMemCache.new(options)
+        @store      = ::LocalMemCache.new(options)
       end
 
       # Wipe out _all_ data in localmemcached, use with care.
@@ -35,22 +32,22 @@ module Ramaze
       end
 
       def cache_delete(*args)
-        super{|key| @store.delete(key.to_s); nil }
+        super { |key| @store.delete(key.to_s); nil }
       end
 
       # NOTE:
       #   * We have no way of knowing whether the value really is nil, we
       #     assume you wouldn't cache nil and return the default instead.
       def cache_fetch(*args)
-        super{|key|
+        super { |key|
           value = @store[key.to_s]
           @serializer.load(value) if value
         }
       end
 
       def cache_store(*args)
-        super{|key, value| @store[key.to_s] = @serializer.dump(value) }
+        super { |key, value| @store[key.to_s] = @serializer.dump(value) }
       end
-    end
-  end
-end
+    end # LocalMemCache
+  end # Cache
+end # Ramaze

data/lib/ramaze/cache/lru.rb

@@ -3,9 +3,18 @@
 
 module Ramaze
   class Cache
+    ##
+    # Cache class that uses Ramaze::LRUHash as a storage engine. This cache has
+    # the advantage that unlike Innate::Cache::Memory it does not leak memory
+    # over time.
+    #
+    # @author Michael Fellinger
+    # @since  17-07-2009
+    #
     class LRU
       include Cache::API
 
+      # Hash containing all the options for the cache.
       OPTIONS = {
         # expiration in seconds
         :expiration => nil,
@@ -17,26 +26,59 @@ module Ramaze
         :max_value => nil,
       }
 
-      # Connect to localmemcache
+      ##
+      # Prepares the cache by creating a new instance of Ramaze::LRUHash using
+      # the options set in Ramaze::Cache::LRU::OPTIONS.
+      #
+      # @author Michael Fellinger
+      # @since  17-07-2009
+      #
       def cache_setup(host, user, app, name)
         @store = Ramaze::LRUHash.new(OPTIONS)
       end
 
+      ##
+      # Clears the entire cache.
+      #
+      # @author Michael Fellinger
+      # @since  17-07-2009
+      #
       def cache_clear
         @store.clear
       end
 
+      ##
+      # Stores a set of data in the cache.
+      #
+      # @author Michael Fellinger
+      # @since  17-07-2009
+      # @see    Innate::Cache::API#cache_store
+      #
       def cache_store(*args)
-        super{|key, value| @store[key] = value }
+        super { |key, value| @store[key] = value }
       end
 
+      ##
+      # Retrieves a set of data from the cache.
+      #
+      # @author Michael Fellinger
+      # @since  17-07-2009
+      # @see    Innate::Cache::API#cache_fetch
+      #
       def cache_fetch(*args)
-        super{|key| @store[key] }
+        super { |key| @store[key] }
       end
 
+      ##
+      # Deletes a set of data from the cache
+      #
+      # @author Michael Fellinger
+      # @since  17-07-2009
+      # @see    Innate::Cache::API#cache_delete
+      #
       def cache_delete(*args)
-        super{|key| @store.delete(key) }
+        super { |key| @store.delete(key) }
       end
-    end
-  end
-end
+    end # LRU
+  end # Cache
+end # Ramaze

data/lib/ramaze/cache/memcache.rb

@@ -1,124 +1,202 @@
-#          Copyright (c) 2009 Michael Fellinger m.fellinger@gmail.com
-# All files in this distribution are subject to the terms of the Ruby license.
+require 'dalli'
 
-require 'memcache'
+# Kgio gives a nice performance boost but it isn't required
+begin; require 'kgio'; rescue LoadError => e; end
 
+#:nodoc:
 module Ramaze
+  #:nodoc:
   class Cache
-
-    # Cache based on the memcache library which utilizes the memcache-daemon to
-    # store key/value pairs in namespaces.
+    ##
+    # Cache driver for the Memcache storage engine. Memcache is a key/value
+    # store that's extremely useful for caching data such as views or API
+    # responses. More inforamtion about Memcache can be found on it's website:
+    # http://memcached.org/.
+    #
+    # Note that this cache driver requires the Dalli gem rather than Memcache
+    # Client. The reason for this is that the Memcache client hasn't been
+    # updated in over a year and Memcache has changed quite a bit. Dalli is also
+    # supposed to be faster and better coded. This cache driver will also try to
+    # load the kgio Gem if it's installed, if it's not it will just continue to
+    # operate but you won't get the nice speed boost.
+    #
+    # This driver works similar to Ramaze::Cache::Sequel in that it allows you
+    # to specify instance specific options uisng the using() method:
     #
-    # Please read the documentation of memcache-client for further methods.
+    #  Ramaze::Cache.options.view = Ramaze::Cache::Memcache.using(:compression => false)
     #
-    # It is highly recommended to install memcache-client_extensions for
-    # a bit of speedup and more functionality
+    # All options sent to the using() method will be sent to Dalli.
     #
-    # NOTE: There is a big issue with persisting sessions in memcache, not only
-    #       can they be dropped at any time, essentially logging the user out
-    #       without them noticing, but there is also a low limit to the maximum
-    #       time-to-live. After 30 days, your session will be dropped, no
-    #       matter what.
-    #       Please remember that memcache is, first of all, a cache, not a
-    #       persistence mechanism.
+    # @author Yorick Peterse
+    # @since  04-05-2011
     #
-    # NOTE: If you try to set a higher ttl than allowed, your stored key/value
-    #       will be expired immediately.
     class MemCache
+      include Cache::API
+      include Innate::Traited
+
+      # The maximum Time To Live that can be used in Memcache
       MAX_TTL = 2592000
 
-      include Cache::API
+      # Hash containing the default configuration options to use for Dalli
+      trait :default => {
+        # The default TTL for each item
+        :expires_in => 604800,
+
+        # Compresses everything with Gzip if it's over 1K
+        :compression => true,
 
-      # +:multithread+: May be turned off at your own risk.
-      #    +:readonly+: You most likely want that to be false.
-      #     +:servers+: Array containing at least one of:
-      #                 MemCache::Server instance
-      #                 Strings like "localhost", "localhost:11211", "localhost:11211:1"
-      #                 That accord to "host:port:weight", only host is required.
-      OPTIONS = {
-        :multithread => true,
-        :readonly    => false,
-        :servers     => ['localhost:11211:1'],
+        # Array containing all default Memcache servers
+        :servers => ['localhost:11211']
       }
 
-      # Connect to memcached
-      def cache_setup(host, user, app, name)
-        @namespace = [host, user, app, name].compact.join('-')
-        options = {:namespace => @namespace}.merge(OPTIONS)
-        servers = options.delete(:servers)
-        @store = ::MemCache.new(servers, options)
-        @warned = false
+      # Hash containing all the default options merged with the user specified 
+      # ones
+      attr_accessor :options
+
+      class << self
+        attr_accessor :options
+
+        ##
+        # This method will create a subclass of Ramaze::Cache::MemCache with all
+        # the custom options set. All options set in this method will be sent to
+        # Dalli as well.
+        #
+        # Using this method allows you to use different memcache settings for
+        # various parts of Ramaze. For example, you might want to use servers A
+        # and B for storing the sessions but server C for only views. Most of
+        # the way this method works was inspired by Ramaze::Cache::Sequel which
+        # was contributed by Lars Olsson.
+        #
+        # @example
+        #  Ramaze::Cache.options.session = Ramaze::Cache::MemCache.using(
+        #    :compression => false,
+        #    :username    => 'ramaze',
+        #    :password    => 'ramaze123',
+        #    :servers     => ['othermachine.com:12345'] # Overwrites the default server
+        #  )
+        #
+        # @author Yorick Peterse
+        # @since  04-05-2011
+        # @param  [Hash] options A hash containing all configuration options to
+        #  use for Dalli. For more information on all the available options you
+        #  can read the README in their repository. This repository can be found
+        #  here: https://github.com/mperham/dalli
+        #
+        def using(options = {})
+          merged = Ramaze::Cache::MemCache.trait[:default].merge(options)
+          Class.new(self) { @options = merged }
+        end
       end
 
-      # Wipe out _all_ data in memcached, use with care.
-      def cache_clear
-        @store.flush_all
-      rescue ::MemCache::MemCacheError => e
-        Log.error(e)
-        nil
+      ##
+      # Creates a new instance of the cache class.
+      #
+      # @author Michael Fellinger
+      # @since  04-05-2011
+      # @param  [Hash] options A hash with custom options, see 
+      #  Ramaze::Cache::MemCache.using for all available options.
+      #
+      def initialize(options = {})
+        self.class.options ||= Ramaze::Cache::MemCache.trait[:default].merge(
+          options
+        )
+        
+        @options = options.merge(self.class.options)
       end
 
+      ##
+      # Prepares the cache by creating the namespace and an instance of a Dalli 
+      # client.
       #
-      def cache_delete(*keys)
-        super{|key| @store.delete(key); nil }
-      rescue ::MemCache::MemCacheError => e
-        Log.error(e)
-        nil
-      end
+      # @author Yorick Peterse
+      # @since  04-05-2011
+      # @param  [String] hostname  The hostname of the machine running the 
+      #  application.
+      # @param  [String] username  The name of the user executing the process
+      # @param  [String] appname   Unique identifier for the application.
+      # @param  [String] cachename The namespace to use for this cache instance.
+      #
+      def cache_setup(hostname, username, appname, cachename)
+        # Validate the maximum TTL
+        if options[:expires_in] > MAX_TTL
+          raise(ArgumentError, "The maximum TTL of Memcache is 30 days")
+        end
 
-      # NOTE:
-      #   * We have no way of knowing whether the value really is nil, we
-      #     assume you wouldn't cache nil and return the default instead.
-      def cache_fetch(key, default = nil)
-        value = @store[key]
-        value.nil? ? default : value
-      rescue ::MemCache::MemCacheError => e
-        Log.error(e)
-        nil
+        options[:namespace] = [
+          hostname, username, appname, cachename
+        ].compact.join('-')
+        
+        @client = ::Dalli::Client.new(options[:servers], options)
       end
 
-      def cache_store(key, value, options = {})
-        ttl = options[:ttl] || 0
-
-        if ttl > MAX_TTL
-          unless @warned
-            Log.warn('MemCache cannot set a ttl greater than 2592000 seconds.')
-            Log.warn('Modify Ramaze.options.session.ttl to a value <= of that.')
-            @warned = true
-          end
+      ##
+      # Removes all items from the cache.
+      #
+      # @author Yorick Peterse
+      # @since  04-05-2011
+      #
+      def cache_clear
+        @client.flush
+      end
 
-          ttl = MAX_TTL
+      ##
+      # Removes the specified keys from the cache.
+      #
+      # @author Yorick Peterse
+      # @since  04-05-2011
+      # @param  [Array] keys The keys to remove from the cache.
+      #
+      def cache_delete(*keys)
+        keys.each do |key|
+          @client.delete(key)
         end
-
-        @store.set(key, value, ttl)
-        value
-      rescue ::MemCache::MemCacheError => e
-        Log.error(e)
-        nil
       end
 
-      # statistics about usage
-      def stats; @store.stats; end
+      ##
+      # Fetches the specified key from the cache. It the value was nil the 
+      # default value will be returned instead.
+      #
+      # @author Yorick Peterse
+      # @since  04-05-2011
+      # @param  [String] key The name of the key to retrieve.
+      # @param  [Mixed] default The default value.
+      # @return [Mixed]
+      #
+      def cache_fetch(key, default = nil)
+        value = @client.get(key)
 
-      # current namespace
-      def namespace; @store.namespace; end
+        if value.nil?
+          return default
+        else
+          return value
+        end
+      end
 
-      # switch to different namespace
-      def namespace=(ns) @namespace = @store.namespace = ns; end
+      ##
+      # Sets the given key to the specified value. Optionally you can specify a
+      # hash with options specific to the key. Once a key has been stored it's
+      # value will be returned.
+      #
+      # @author Yorick Peterse
+      # @since  04-05-2011
+      # @param  [String] key The name of the key to store.
+      # @param  [Mixed] value The value to store in Memcache.
+      # @param  [Fixnum] ttl The Time To Live to use for the current key.
+      # @param  [Hash] options A hash containing options specific for the 
+      #  specified key.
+      # @return [Mixed]
+      #
+      def cache_store(key, value, ttl = nil, options = {})
+        ttl = options.delete(:ttl) || @options[:expires_in]
 
-      # state of compression (true/false)
-      def compression; @store.compression; end
+        if ttl > MAX_TTL
+          raise(ArgumentError, "The maximum TTL of Memcache is 30 days")
+        end
 
-      # turn compression on or off
-      def compression=(bool); @store.compression = bool; end
+        @client.set(key, value, ttl, options)
 
-      # For everything else that we don't care to document right now.
-      def method_missing(*args, &block)
-        @store.__send__(*args, &block)
-      rescue ::MemCache::MemCacheError => e
-        Log.error(e)
-        nil
+        return value
       end
-    end
-  end
-end
+    end # MemCache
+  end # Cache
+end # Ramaze