cachetastic-three 3.0.0

data/lib/cachetastic/adapters/file.rb

@@ -0,0 +1,66 @@
+module Cachetastic # :nodoc:
+  module Adapters
+    # An adapter to cache objects to the file system.
+    # 
+    # This adapter supports the following configuration settings,
+    # in addition to the default settings:
+    # 
+    #   configatron.cachetastic.defaults.storage_path = ::File.join(FileUtils.pwd, 'cachetastic')
+    #   configatron.cachetastic.defaults.marshal_method = :yaml
+    # 
+    # The <tt>storage_path</tt> setting defines the path to where cached
+    # objects are written to on disk.
+    # 
+    # See <tt>Cachetastic::Adapters::Base</tt> for a list of public API
+    # methods.
+    class File < Cachetastic::Adapters::Base
+      
+      def initialize(klass) # :nodoc:
+        define_accessor(:storage_path)
+        self.storage_path = ::File.join(FileUtils.pwd, 'cachetastic')
+        super
+        self.marshal_method = :yaml if self.marshal_method == :none
+        @_file_paths = {}
+      end
+      
+      def get(key) # :nodoc:
+        path = file_path(key)
+        val = nil
+        val = ::File.read(path) if ::File.exists?(path)
+        return val
+      end # get
+      
+      def set(key, value, expiry_time = configatron.cachetastic.defaults.default_expiry) # :nodoc:
+        so = Cachetastic::Cache::StoreObject.new(key, value, expiry_time.from_now)
+        path = file_path(key)
+        ::File.open(path, 'w') {|f| f.write marshal(so)}
+        value
+      end # set
+      
+      def delete(key) # :nodoc:
+        FileUtils.rm(file_path(key))
+      end # delete
+      
+      def expire_all # :nodoc:
+        @_file_paths = {}
+        ::FileUtils.rm_rf(::File.join(self.storage_path, klass.name.underscore))
+        return nil
+      end # expire_all
+      
+      def transform_key(key) # :nodoc:
+        key.to_s.hexdigest
+      end
+      
+      def file_path(key) # :nodoc:
+        path = @_file_paths[key]
+        if path.nil?
+          path = ::File.join(self.storage_path, klass.name.underscore, transform_key(key).scan(/(.{1,4})/).flatten, 'cache.data')
+          @_file_paths[key] = path
+          FileUtils.mkdir_p(::File.dirname(path))
+        end
+        return path
+      end
+      
+    end # File
+  end # Adapters
+end # Cachetastic

data/lib/cachetastic/adapters/local_memory.rb

@@ -0,0 +1,37 @@
+module Cachetastic # :nodoc:
+  module Adapters
+    # An adapter to cache objects to memory. It is important to note
+    # that this cache is <b>volatile</b>. If the VM it is running in
+    # shuts down, everything in the cache gets vaporized.
+    # 
+    # See <tt>Cachetastic::Adapters::Base</tt> for a list of public API
+    # methods.
+    class LocalMemory < Cachetastic::Adapters::Base
+      
+      def initialize(klass) # :nodoc:
+        super
+        @_store = {}
+      end
+      
+      def get(key) # :nodoc:
+        @_store[key]
+      end # get
+      
+      def set(key, value, expiry_time = configatron.cachetastic.defaults.default_expiry) # :nodoc:
+        so = Cachetastic::Cache::StoreObject.new(key, value, expiry_time.from_now)
+        @_store[key] = marshal(so)
+        value
+      end # set
+      
+      def delete(key) # :nodoc:
+        @_store.delete(key)
+      end # delete
+      
+      def expire_all # :nodoc:
+        @_store = {}
+        return nil
+      end # expire_all
+      
+    end # LocalMemory
+  end # Adapters
+end # Cachetastic

data/lib/cachetastic/adapters/memcached.rb

@@ -0,0 +1,114 @@
+module Cachetastic # :nodoc:
+  module Adapters
+    # An adapter to cache objects to the file system.
+    # 
+    # This adapter supports the following configuration settings,
+    # in addition to the default settings:
+    # 
+    #   configatron.cachetastic.defaults.servers = ['127.0.0.1:11211']
+    #   configatron.cachetastic.defaults.mc_options = {:c_threshold => 10_000,
+    #                                                  :compression => true,
+    #                                                  :debug => false,
+    #                                                  :readonly => false,
+    #                                                  :urlencode => false}
+    #   configatron.cachetastic.delete_delay = 0
+    # 
+    # The <tt>servers</tt> setting defines an <tt>Array</tt> of Mecached
+    # servers, represented as "<host>:<port>".
+    # 
+    # The <tt>mc_options</tt> setting is a <tt>Hash</tt> of settings required
+    # by Memcached. See the Memcached documentation for more information on
+    # what the settings mean.
+    # 
+    # The <tt>delete_delay</tt> setting tells Memcached how long to wait
+    # before it deletes the object. This is not the same as <tt>expiry_time</tt>.
+    # It is only used when the <tt>delete</tt> method is called.
+    # 
+    # See <tt>Cachetastic::Adapters::Base</tt> for a list of public API
+    # methods.
+    class Memcached < Cachetastic::Adapters::Base
+      
+      def initialize(klass) # :nodoc:
+        define_accessor(:servers)
+        define_accessor(:mc_options)
+        define_accessor(:delete_delay)
+        self.delete_delay = 0
+        self.servers = ['127.0.0.1:11211']
+        self.mc_options = {:c_threshold => 10_000,
+                           :compression => true,
+                           :debug => false,
+                           :readonly => false,
+                           :urlencode => false}
+        super
+        connection
+      end
+      
+      def get(key) # :nodoc:
+        connection.get(transform_key(key), false)
+      end # get
+      
+      def set(key, value, expiry_time = configatron.cachetastic.defaults.default_expiry) # :nodoc:
+        connection.set(transform_key(key), marshal(value), expiry_time, false)
+      end # set
+      
+      def delete(key) # :nodoc:
+        connection.delete(transform_key(key), self.delete_delay)
+      end # delete
+      
+      def expire_all # :nodoc:
+        increment_version
+        @_mc_connection = nil
+        return nil
+      end # expire_all
+      
+      def transform_key(key) # :nodoc:
+        key.to_s.hexdigest
+      end
+      
+      # Return <tt>false</tt> if the connection to Memcached is
+      # either <tt>nil</tt> or not active.
+      def valid?
+        return false if @_mc_connection.nil?
+        return false unless @_mc_connection.active?
+        return true
+      end
+      
+      private
+      def connection
+        unless @_mc_connection && valid? && @_ns_version == get_version
+          @_mc_connection = MemCache.new(self.servers, self.mc_options.merge(:namespace => namespace))
+        end
+        @_mc_connection
+      end
+      
+      def ns_connection
+        unless @_ns_connection
+          @_ns_connection = MemCache.new(self.servers, self.mc_options.merge(:namespace => :namespace_versions))
+        end
+        @_ns_connection
+      end
+      
+      def increment_version
+        name = self.klass.name
+        v = get_version
+        ns_connection.set(name, v + 1)
+      end
+
+      def get_version
+        name = self.klass.name
+        v = ns_connection.get(name)
+        if v.nil?
+          ns_connection.set(name, 1)
+          v = 1
+        end
+        v
+      end
+      
+      def namespace
+        @_ns_version = get_version
+        "#{self.klass.name}.#{@_ns_version}"
+      end
+      
+    end # Memcached
+  end # Adapters
+end # Cachetastic

data/lib/cachetastic/cache.rb

@@ -0,0 +1,165 @@
+module Cachetastic # :nodoc:
+  # When creating a new 'Cache' this class should be extended.
+  # Once extended you'll only need to override just the methods
+  # that are different for your cache.
+  #   class MyAwesomeCache < Cachetastic::Cache
+  #   end
+  # 
+  #   MyAwesomeCache.set(1, "One")
+  #   MyAwesomeCache.get(1) # => "One"
+  #   MyAwesomeCache.update(1, "One!!")
+  #   MyAwesomeCache.get(1) # => "One!!"
+  #   MyAwesomeCache.delete(1)
+  #   MyAwesomeCache.get(1) # => nil
+  # 
+  #   class MyAwesomeCache < Cachetastic::Cache
+  #     class << self
+  #       def get(key)
+  #         super(key) do
+  #           set(key, key * 10)
+  #         end
+  #       end
+  #     end
+  #   end
+  # 
+  #   MyAwesomeCache.set(1, "One")
+  #   MyAwesomeCache.get(1) # => "One"
+  #   MyAwesomeCache.delete(1)
+  #   MyAwesomeCache.get(1) # => 10
+  class Cache
+    
+    # everything is done at the class level. there won't be any 'instances of it'
+    # using class << self means we don't have to prefix each method with 'self.'
+    class << self
+      
+      # Returns an object from the cache for a given key.
+      # If the object comes back as nil and a block is given
+      # that block will be run and the results of the block
+      # will be returned. This can be used to JIT caches, just make
+      # sure in the block to call the set method because the
+      # results of the block are not automatically cached.
+      def get(key, &block)
+        do_with_logging(:get, key) do
+          val = self.adapter.get(key)
+          handle_store_object(key, adapter.unmarshal(val), &block)
+        end
+      end # get
+      
+      # Set a particular object info the cache for the given key.
+      # 
+      # An optional third parameter sets the expiry time for the object in the cache.
+      # If no expiry_time is passed in then the default expiry_time that has been configured
+      # will be used.
+      # 
+      # If there is an the expiry_swing setting is configured it will be +/- to the
+      # expiry time.
+      def set(key, value, expiry_time = nil)
+        do_with_logging(:set, key) do
+          self.adapter.set(key, value, calculate_expiry_time(expiry_time))
+        end
+      end # set
+      
+      # Deletes an object from the cache.
+      def delete(key)
+        do_with_logging(:delete, key) do
+          self.adapter.delete(key)
+          nil
+        end
+      end # delete
+      
+      # Expires all objects for this cache.
+      def expire_all
+        do_with_logging(:expire_all, nil) do
+          self.adapter.expire_all
+          nil
+        end
+      end # expire_all
+      
+      # Returns the underlying Cachetastic::Adapters::Base for this cache.
+      def adapter
+        unless @_adapter && @_adapter.valid?
+          @_adapter = Cachetastic::Adapters.build(cache_klass)
+        end
+        @_adapter
+      end # adapter
+      
+      # Clears the adapter so it can be redefined. This is useful if you have
+      # reconfigured the cache to use a different adapater, or different settings.
+      def clear_adapter!
+        @_adapter = nil
+      end
+      
+      def cache_klass # :nodoc:
+        self
+      end
+      
+      # Returns the Cachetastic::Logger for this cache.
+      def logger
+        unless @_logger
+          @_logger = Cachetastic::Logger.new(adapter.logger)
+        end
+        @_logger
+      end
+      
+      private
+      # If the expiry time is set to 60 minutes and the expiry_swing time is set to
+      # 15 minutes, this method will return a number between 45 minutes and 75 minutes.
+      def calculate_expiry_time(expiry_time) # :doc:
+        expiry_time = self.adapter.default_expiry if expiry_time.nil?
+        exp_swing = self.adapter.expiry_swing
+        if exp_swing && exp_swing != 0
+          swing = rand(exp_swing.to_i)
+          case rand(2)
+          when 0
+            expiry_time = (expiry_time.to_i + swing)
+          when 1
+            expiry_time = (expiry_time.to_i - swing)
+          end
+        end
+        expiry_time
+      end
+      
+      def handle_store_object(key, val, &block)
+        if val.is_a?(Cachetastic::Cache::StoreObject)
+          if val.expired?
+            self.delete(key)
+            val = nil
+          else
+            val = val.value
+          end
+        end
+        
+        if val.respond_to?(:empty?)
+          val = nil if val.empty?
+        elsif val.respond_to?(:blank?)
+          val = nil if val.blank?
+        end
+        return val unless val.nil?
+        
+        val = yield if block_given?
+        return val
+      end
+      
+      def do_with_logging(action, key)
+        if adapter.debug?
+          start_time = Time.now
+          logger.debug(:starting, action, cache_klass.name, key)
+          res = yield if block_given?
+          end_time = Time.now
+          str = ''
+          unless res.nil?
+            str = "[#{res.class.name}]"
+            str << "\t[Size = #{res.size}]" if res.respond_to? :size
+            str << "\t" << res.inspect
+          end
+          logger.debug(:finished, action, cache_klass.name, key, (end_time - start_time), str)
+          return res
+        else
+          return yield if block_given?
+        end
+      end
+      
+    end # class << self
+    
+  end # Cache
+end # Cachetastic

data/lib/cachetastic/cacheable.rb

@@ -0,0 +1,202 @@
+module Cachetastic # :nodoc:
+  # Include this module into an Object to achieve simplistic Object level caching.
+  # 
+  # Example:
+  #   class Person
+  #     include Cachetastic::Cacheable
+  #   
+  #     attr_accessor :name
+  #   
+  #     def cachetastic_key
+  #       self.name
+  #     end
+  #   
+  #     def always_the_same(x, y)
+  #       cacher("always_the_same") do
+  #         x + y
+  #       end
+  #     end
+  #   
+  #   end
+  module Cacheable
+    
+    module ClassAndInstanceMethods
+      # Returns the Cachetastic::Cache object associated with the object.
+      # If a cache hasn't been defined the one will be created on the fly.
+      # The cache for the object is expected to be defined as:
+      # Cachetastic::Cacheable::{CLASS_NAME_HERE}Cache
+      # 
+      # Examples:
+      #   class Person
+      #     include Cachetastic::Cacheable
+      #   end
+      # 
+      #  Person.cache_class # => Cachetastic::Cacheable::PersonCache
+      # 
+      #   class Admin::Person
+      #     include Cachetastic::Cacheable
+      #   end
+      # 
+      #  Admin::Person.cache_class # => Cachetastic::Cacheable::Admin_PersonCache
+      def cache_class
+        n = self.class.name
+        n = self.name if n == "Class"
+        c_name = "Cachetastic::Cacheable::#{n.gsub('::', '_')}Cache"
+        begin
+          return c_name.constantize
+        rescue NameError => e
+          eval %{
+            class #{c_name} < Cachetastic::Cache
+              
+              def self.cache_klass
+                #{n}
+              end
+              
+            end
+          }
+          return c_name.constantize
+        end
+        
+      end
+    
+      # How much did I want to call this method cache?? It originally was that, but
+      # in Rails 2.0 they decided to use that name, so I had to rename this method.
+      # This method will attempt to get an object from the cache for a given key.
+      # If the object is nil and a block is given the block will be run, and the results
+      # of the block will be automatically cached.
+      # 
+      # Example:
+      #   class Person
+      #     include Cachetastic::Cacheable
+      # 
+      #     def always_the_same(x,y)
+      #       cacher("always_the_same") do
+      #         x + y
+      #       end
+      #     end
+      #   end
+      # 
+      #   Person.new.always_the_same(1,2) # => 3
+      #   Person.new.always_the_same(2,2) # => 3
+      #   Person.new.always_the_same(3,3) # => 3
+      #   Person.cacher("always_the_same") # => 3
+      #   Person.get_from_cache("always_the_same") # => 3
+      #   Cachetastic::Cacheable::PersonCache.get("always_the_same") # => 3
+      #   
+      #   Person.cacher("say_hi") {"Hi There"} # => "Hi There"
+      #   Person.get_from_cache("say_hi") # => "Hi There"
+      #   Cachetastic::Cacheable::PersonCache.get("say_hi") # => "Hi There"
+      def cacher(key, expiry = nil)
+        cache_class.get(key) do
+          if block_given?
+            res = yield
+            cache_class.set(key, res, expiry)
+          end
+        end
+      end
+    
+      # Expires the entire cache associated with this objects's cache.
+      # 
+      # Example:
+      #   class Person
+      #     include Cachetastic::Cacheable
+      #     attr_accessor :name
+      #     def cachetastic_key
+      #       self.name
+      #     end
+      #   end
+      # 
+      #   Person.set_into_cache(1, "one")
+      #   Person.get_from_cache(1) # => "one"
+      #   Person.expire_all
+      #   Person.get_from_cache(1) # => nil
+      #   Person.set_into_cache(1, "one")
+      #   Person.get_from_cache(1) # => "one"
+      #   Cachetastic::Cacheable::PersonCache.expire_all
+      #   Person.get_from_cache(1) # => nil
+      def expire_all
+        cache_class.expire_all
+      end
+      
+    end
+    
+    # --------------------------
+    # Instance only methods:
+    
+    # Unless the object's cachetastic_key method returns nil this method will store
+    # the object in the cache using the object's cachetastic_key as the key.
+    # You *MUST* create an instance level method called cachetastic_key and 
+    # have it return a valid key! If you return nil from the cachetastic_key method or you will not be
+    # able to use the cache_self and uncache_self methods.
+    # 
+    # Example:
+    #   class Person
+    #     include Cachetastic::Cacheable
+    #     attr_accessor :name
+    #     def cachetastic_key
+    #       self.name
+    #     end
+    #   end
+    # 
+    #   Person.get_from_cache("Mark Bates") # => nil
+    #   p = Person.new
+    #   p.name = "Mark Bates"
+    #   p.cache_self
+    #   Person.get_from_cache("Mark Bates") # => "Mark Bates"
+    def cache_self
+      cache_class.set(self.cachetastic_key, self) unless self.cachetastic_key.nil?
+    end
+
+    # Unless the object's cachetastic_key method returns nil this method will delete
+    # the object in the cache using the object's cachetastic_key as the key.
+    # You *MUST* create an instance level method called cachetastic_key and 
+    # have it return a valid key! If you return nil from the cachetastic_key method or you will not be
+    # able to use the cache_self and uncache_self methods.
+    # 
+    # Example:
+    #   class Person
+    #     include Cachetastic::Cacheable
+    #     attr_accessor :name
+    #     def cachetastic_key
+    #       self.name
+    #     end
+    #   end
+    # 
+    #   Person.get_from_cache("Mark Bates") # => nil
+    #   p = Person.new
+    #   p.name = "Mark Bates"
+    #   p.cache_self
+    #   Person.get_from_cache("Mark Bates") # => "Mark Bates"
+    #   p.uncache_self
+    #   Person.get_from_cache("Mark Bates") # => nil
+    def uncache_self
+      cache_class.delete(self.cachetastic_key) unless self.cachetastic_key.nil?
+    end
+    
+    # --------------------------
+    
+    def self.included(klass) # :nodoc:
+      klass.send(:include, ClassAndInstanceMethods)
+      klass.extend(ClassOnlyMethods)
+      klass.extend(ClassAndInstanceMethods)
+    end
+    
+    module ClassOnlyMethods
+      # Returns an object from the cache for a given key.
+      def get_from_cache(key, &block)
+        cache_class.get(key, &block)
+      end
+
+      # Deletes an object from the cache for a given key.
+      def delete_from_cache(key)
+        cache_class.delete(key)
+      end
+
+      # Sets an object into the cache for a given key.
+      def set_into_cache(key, value, expiry = 0)
+        cache_class.set(key, value, expiry)
+      end
+    end # ClassMethods
+    
+  end # Cacheable
+end # Cachetastic