markbates-cachetastic 3.0.0.20090611142033

data/LICENSE

@@ -0,0 +1,21 @@
+The MIT License
+
+Copyright (c) 2009 Mark Bates
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README

@@ -0,0 +1,89 @@
+=What is Cachetastic?
+Cachetastic is an incredibly easy to use and administer caching framework. Just because it is easy to use, does not mean that
+it is light with features. Cachetastic allows you to create classes that extend <tt>Cachetastic::Cache</tt>, configure them
+each individually, and much more.
+
+Unlike other systems each cache in your system can use different backends via the use of adapters that get assigned to each
+cache, and globally. You can define different expiration times, loggers, marshal methods, and more! And again, you can choose to 
+define these settings globally, or for each cache!
+
+Adapters are easy to write, so if the built in adapters don't float your boat, you can easily knock one off in short order.
+
+==Configuration:
+Configuration of Cachetastic is done using the Configatron gem. I would recommend reading the documentation on it first, http://configatron.mackframework.com, before continuing.
+
+All configuration settings hang off of the <tt>cachetastic</tt> namespace on <tt>configatron</tt>. The default settings
+all hang off the <tt>defaults</tt> namespace on the <tt>cachetastic</tt> namespace, as shown below:
+
+  # This will write detailed information to the logger.
+  configatron.cachetastic.defaults.debug = false
+
+  # This is the type of file store to be used for this cache.
+  # More adapters can be developed and plugged in as desired.
+  # The default is Cachetastic::Adapters::LocalMemory
+  configatron.cachetastic.defaults.adapter = Cachetastic::Adapters::LocalMemory
+  configatron.cachetastic.defaults.adapter = Cachetastic::Adapters::File
+  configatron.cachetastic.defaults.adapter = Cachetastic::Adapters::Memcached
+
+  # This will marshall objects into and out of the store.
+  # The default is :none, except for Cachetastic::Adapters::File, which defaults to :yaml
+  configatron.cachetastic.defaults.marshall_method = :none
+  configatron.cachetastic.defaults.marshall_method = :yaml
+  configatron.cachetastic.defaults.marshall_method = :ruby
+
+  # This sets how long objects will live in the cache before they are auto expired.
+  configatron.cachetastic.defaults.default_expiry = 86400 # time in seconds (default: 24 hours)
+
+  # When setting objects into the cache the expiry_swing is +/- to the expiry time.
+  # Example: if the expiry time is 1 minute, and the swing is 15 seconds,
+  # objects will go into the cache with an expiry time sometime between 45 seconds and 75 seconds.
+  # The default is 0 seconds.
+  configatron.cachetastic.defaults.expiry_swing = 15
+
+  # Configure logging for the system.
+  # n number of logs can be configured for a cache.
+  log_1 = Logger.new(STDOUT)
+  log_1.level = Logger::DEBUG
+  log_2 = Logger.new("log/cachetastic.log")
+  log_2.level = Logger::ERROR
+  configatron.cachetastic.defaults.logger = [log_1, log_2]
+    
+Overriding settings per cache is very simple. Let's take the following two caches:
+
+  class UserCache < Cachetastic::Cache
+  end
+
+  class Admin::UserCache < Cachetastic::Cache
+  end
+
+If we wanted to set the <tt>UserCache</tt> to use the <tt>Cachetastic::Adapters::File</tt> adapter and we wanted to set the adapter for 
+the <tt>Admin::UserCache</tt> to use <tt>Cachetastic::Adapters::Memcached</tt>, we would configure them like such:
+
+  configatron.cachetastic.user_cache.adapter = Cachetastic::Adapters::File
+  configatron.cachetastic.admin.user_cache.adapter = Cachetastic::Adapters::Memcached
+  
+In this scenario we have changed the adapters for each of the classes. All of the other default settings will remain intact for
+each of those classes. This makes it incredibly easy to just change the one parameter you need, and not have to reset them all.
+    
+==Examples:
+
+  class MyAwesomeCache < Cachetastic::Cache
+  end
+  
+  MyAwesomeCache.set(1, [1,2,3])
+  MyAwesomeCache.get(1) # => [1,2,3] 
+  
+  class MyAwesomeCache < Cachetastic::Cache
+    class << self
+      def get(key, x, y)
+        super(key) do
+          n = x + y
+          set(key, n)
+          n
+        end
+      end
+    end
+  end
+  
+  MyAwesomeCache.get(1, 2, 4) # => 8
+  MyAwesomeCache.get(1, 4, 4) # => 8

data/lib/cachetastic/adapters/base.rb

@@ -0,0 +1,178 @@
+module Cachetastic # :nodoc:
+  module Adapters
+    
+    class << self
+      
+      # This method will return the appropriate 
+      # <tt>Cachetastic::Adapters::Base</tt> class that is defined
+      # for the Class passed in. If an adapter has not been
+      # defined for the Class than the default adapter is returned.
+      # 
+      # Examples:
+      #   configatron.cachetastic.defaults.adapter = Cachetastic::Adapters::LocalMemory
+      #   configatron.cachetastic.user.adapter = Cachetastic::Adapters::Memcached
+      #   Cachetastic::Adapters.build(User).class # => Cachetastic::Adapters::Memcached
+      #   Cachetastic::Adapters.build(Comment).class # => Cachetastic::Adapters::LocalMemory
+      def build(klass)
+        adp = klass.to_configatron(:cachetastic).adapter
+        if adp.nil?
+          adp = configatron.cachetastic.defaults.adapter
+        end
+        adp.new(klass)
+      end
+      
+    end # class << self
+    
+    # This class should be extended to create new adapters for various
+    # backends. It is important that all subclasses call the <tt>initialize</tt>
+    # method in this base, otherwise things just will not work right.
+    # 
+    # This base class provides common functionality and an API for all
+    # adapters to be used with Cachetastic.
+    # 
+    # The default settings for all adapters are:
+    # 
+    #   configatron.cachetastic.defaults.marshal_method = :none
+    #   configatron.cachetastic.defaults.expiry_swing = 0
+    #   configatron.cachetastic.defaults.default_expiry = 86400
+    #   configatron.cachetastic.defaults.debug = true
+    #   configatron.cachetastic.defaults.adapter = Cachetastic::Adapters::LocalMemory
+    #   logger = ::Logger.new(File.join(FileUtils.pwd, 'log', 'cachetastic.log'))
+    #   logger.level = ::Logger::DEBUG
+    #   configatron.cachetastic.defaults.logger = logger
+    # 
+    # See the README for more information on what each of those settings mean,
+    # and what are values may be used for each one.
+    class Base
+      
+      # The Class that this adapter is associated with. Note that it is a
+      # <i>class</i> reference and not an instance reference.
+      attr_accessor :klass
+      
+      # Creates a new adapter. It takes a class reference to tie the
+      # instance of the adapter to a particular class. Note that it is a
+      # <i>class</i> reference and not an instance reference.
+      # 
+      # Examples:
+      #   Cachetastic::Adapters::Base.new(User)
+      # 
+      # Adapters are configured using the Configatron gem.
+      # 
+      # Examples:
+      #   configatron.cachetastic.user.adapter = Cachetastic::Adapters::File
+      #   configatron.cachetastic.user.expiry_time = 5.hours
+      #   configatron.cachetastic.defaults.expiry_time = 24.hours
+      # 
+      # Refered to each adapter for its specific configuration settings.
+      def initialize(klass)
+        self.klass = klass
+        configatron.cachetastic.defaults.configatron_keys.each do |key|
+          define_accessor(key)
+          self.send("#{key}=", configatron.cachetastic.defaults.send(key))
+        end
+        klass.to_configatron(:cachetastic).configatron_keys.each do |key|
+          define_accessor(key)
+          self.send("#{key}=", klass.to_configatron(:cachetastic).send(key))
+        end
+      end
+      
+      # <b>This method MUST be implemented by a subclass!</b>
+      # 
+      # The implementation of this method should take a key and return
+      # an associated object, if available, from the underlying persistence
+      # layer. 
+      def get(key)
+        raise NoMethodError.new('get')
+      end # get
+      
+      # <b>This method MUST be implemented by a subclass!</b>
+      # 
+      # The implementation of this method should take a key, a value, and
+      # an expiry time and save it to the persistence store, where it should
+      # live until it is either deleted by the user of the expiry time has passed.
+      def set(key, value, expiry_time = configatron.cachetastic.defaults.default_expiry)
+        raise NoMethodError.new('set')
+      end # set
+      
+      # <b>This method MUST be implemented by a subclass!</b>
+      # 
+      # The implementation of this method should take a key and remove
+      # an object, if it exists, from an underlying persistence store.
+      def delete(key)
+        raise NoMethodError.new('delete')
+      end # delete
+      
+      # <b>This method MUST be implemented by a subclass!</b>
+      # 
+      # The implementation of this method is expected to delete all
+      # objects belonging to the associated cache from the underlying
+      # persistence store. It is <b>NOT</b> meant to delete <b>ALL</b>
+      # objects across <b>ALL</b> caches for the underlying persistence
+      # store. That would be very very bad!!
+      def expire_all
+        raise NoMethodError.new('expire_all')
+      end # expire_all
+      
+      # Allows an adapter to transform the key
+      # to a safe representation for it's backend.
+      # For example, the key: '$*...123()%~q' is not a 
+      # key for the file system, so the 
+      # Cachetastic::Adapters::File class should override
+      # this to make it safe for the file system.
+      def transform_key(key)
+        key
+      end
+      
+      # <b>This method MUST be implemented by a subclass!</b>
+      # 
+      # The implementation of this method should return <tt>true</tt>
+      # if the adapter is in a valid state, and <tt>false</tt> if it is
+      # not.
+      def valid?
+        true
+      end
+      
+      def debug? # :nodoc:
+        return self.debug if self.respond_to?(:debug)
+        return false
+      end
+      
+      def marshal(value) # :nodoc:
+        return nil if value.nil?
+        case self.marshal_method.to_sym
+        when :yaml
+          return YAML.dump(value)
+        when :ruby
+          return Marshal.dump(value)
+        else
+          return value
+        end
+      end
+      
+      def unmarshal(value) # :nodoc:
+        return nil if value.nil?
+        case self.marshal_method.to_sym
+        when :yaml
+          return YAML.load(value)
+        when :ruby
+          return Marshal.load(value)
+        else
+          return value
+        end
+      end
+      
+      private
+      def define_accessor(key)
+        instance_eval(%{
+          def #{key}
+            @#{key}
+          end
+          def #{key}=(x)
+            @#{key} = x
+          end
+        })        
+      end
+      
+    end # Base
+  end # Adapters
+end # Cachetastic

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

data/lib/cachetastic/extensions/string.rb

@@ -0,0 +1,8 @@
+require 'digest'
+class String # :nodoc:
+  
+  def hexdigest # :nodoc:
+    Digest::SHA1.hexdigest(self)
+  end
+  
+end

data/lib/cachetastic/logger.rb

@@ -0,0 +1,49 @@
+module Cachetastic # :nodoc:
+  # This class handles logging for the caches and their adapters.
+  # This class exists simply to supply the ability to write to 
+  # multiple loggers simultaneously from a single call. It also 
+  # creates a standardized message to write to those loggers.
+  # 
+  # It is important that any logger type of class you decide to use
+  # reponds to the following methods:
+  #   fatal(message)
+  #   error(message)
+  #   warn(message)
+  #   info(message)
+  #   debug(message)
+  class Logger
+  
+    # An <tt>Array</tt> of 'real' loggers to write to.
+    attr_accessor :loggers
+  
+    # The <tt>initialize</tt> method takes an <tt>Array</tt>
+    # of your favorite logger style classes to write to.
+    def initialize(*loggers)
+      @loggers = [loggers].flatten
+    end
+  
+    LOG_LEVELS = [:fatal, :error, :warn, :info, :debug] # :nodoc:
+  
+    LOG_LEVELS.each do |level|
+      define_method(level) do |*args|
+        lm = "[CACHE] [#{level.to_s.upcase}]\t#{Time.now.strftime("%m/%d/%y %H:%M:%S")}"
+        exs = []
+        args.each do |arg|
+          if arg.is_a?(Exception)
+            exs << arg
+            continue
+          end
+          lm << "\t" << arg.to_s 
+        end
+        exs.each do |ex|
+          lm << "\n#{ex.message}\n" << ex.backtrace.join("\n")
+        end
+        # puts "lm: #{lm}"
+        self.loggers.each do |log|
+          log.send(level, lm)
+        end
+      end
+    end
+  
+  end # Logger
+end # Cachetastic

data/lib/cachetastic/store_object.rb

@@ -0,0 +1,22 @@
+module Cachetastic # :nodoc:
+  class Cache
+    
+    class StoreObject # :nodoc:
+      attr_accessor :expires_at
+      attr_accessor :key
+      attr_accessor :value
+      
+      def initialize(key, value, expires_at)
+        self.key = key
+        self.value = value
+        self.expires_at = expires_at
+      end
+      
+      def expired?
+        return Time.now > self.expires_at
+      end
+      
+    end # StoreObject
+    
+  end # Cache
+end # Cachetastic

data/lib/cachetastic.rb

@@ -0,0 +1,20 @@
+require 'configatron'
+require 'logger'
+require 'activesupport'
+require 'fileutils'
+require 'memcache'
+
+Dir.glob(File.join(File.dirname(__FILE__), 'cachetastic', '**/*.rb')).each do |f|
+  require File.expand_path(f)
+end
+
+configatron.cachetastic.defaults.set_default(:marshal_method, :none)
+configatron.cachetastic.defaults.set_default(:expiry_swing, 0)
+configatron.cachetastic.defaults.set_default(:default_expiry, 86400)
+configatron.cachetastic.defaults.set_default(:debug, true)
+configatron.cachetastic.defaults.set_default(:adapter, Cachetastic::Adapters::LocalMemory)
+log_path = File.join(FileUtils.pwd, 'log', 'cachetastic.log')
+FileUtils.mkdir_p(File.dirname(log_path))
+logger = ::Logger.new(log_path)
+logger.level = ::Logger::DEBUG
+configatron.cachetastic.defaults.set_default(:logger, logger)

metadata

@@ -0,0 +1,94 @@
+--- !ruby/object:Gem::Specification 
+name: markbates-cachetastic
+version: !ruby/object:Gem::Version 
+  version: 3.0.0.20090611142033
+platform: ruby
+authors: 
+- Mark Bates
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2009-06-11 00:00:00 -07:00
+default_executable: 
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: configatron
+  type: :runtime
+  version_requirement: 
+  version_requirements: !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: 2.3.2
+    version: 
+- !ruby/object:Gem::Dependency 
+  name: memcache-client
+  type: :runtime
+  version_requirement: 
+  version_requirements: !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: 1.7.4
+    version: 
+- !ruby/object:Gem::Dependency 
+  name: activesupport
+  type: :runtime
+  version_requirement: 
+  version_requirements: !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: 2.3.2
+    version: 
+description: A very simple, yet very powerful caching framework for Ruby.
+email: mark@mackframework.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: 
+- README
+- LICENSE
+files: 
+- lib/cachetastic/adapters/base.rb
+- lib/cachetastic/adapters/file.rb
+- lib/cachetastic/adapters/local_memory.rb
+- lib/cachetastic/adapters/memcached.rb
+- lib/cachetastic/cache.rb
+- lib/cachetastic/cacheable.rb
+- lib/cachetastic/extensions/string.rb
+- lib/cachetastic/logger.rb
+- lib/cachetastic/store_object.rb
+- lib/cachetastic.rb
+- README
+- LICENSE
+has_rdoc: true
+homepage: http://www.metabates.com
+post_install_message: 
+rdoc_options: []
+
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+requirements: []
+
+rubyforge_project: magrathea
+rubygems_version: 1.2.0
+signing_key: 
+specification_version: 2
+summary: A very simple, yet very powerful caching framework for Ruby.
+test_files: []
+