cached_model 1.0.1 → 1.1.0

data/README

@@ -4,12 +4,30 @@ Rubyforge Project:
 
 http://rubyforge.org/projects/rctools/
 
+Documentation:
+
+http://dev.robotcoop.com/Libraries/cached_model/
+
 == About
 
 CachedModel stores Rails ActiveRecord objects in memcache allowing for very
 fast retrievals.  CachedModel uses the ActiveRecord::Locking to ensure that
 you don't perform multiple updates.
 
+== CachedModel Doesn't...
+
+CachedModel is not magic.
+
+CachedModel only accelerates simple finds for single rows.
+
+CachedModel won't cache every query you run.
+
+CachedModel isn't smart enough to determine the dependencies between your
+queries so that it can accelerate more complicated queries.  Without these
+smarts you'll only end up with a broken application.
+
+If you want to cache more complicated queries you need do it by hand.
+
 == Using CachedModel
 
 First, install the cached_model gem:
@@ -50,7 +68,7 @@ Then make Rails load the gem:
   $ tail -n 4 config/environment.rb 
   # Include your application configuration below
   
-  require_gem 'cached_model'
+  require 'cached_model'
 
 Then edit your ActiveRecord model to inherit from CachedModel instead of
 ActiveRecord::Base:
@@ -64,3 +82,33 @@ ActiveRecord::Base:
     belongs_to :point
     belongs_to :route
 
+== Extra Features
+
+=== Local Cache
+
+CachedModel also incorporates an in-process cache, but it is disabled by
+default.  In order to enable the in-process cache enable it in your
+environment.rb:
+
+  CachedModel.use_local_cache = true
+
+And add a after_filter that flushes the local cache:
+
+  class ApplicationController < ActionController::Base
+  
+    after_filter { CachedModel.cache_reset }
+  
+  end
+
+IF YOU DO NOT ADD THE AFTER FILTER YOU WILL EXPERIENCE EXTREME PROCESS GROWTH.
+
+=== Memcache
+
+Memcache may be disabled and the TTL for objects stored in memcache may be
+changed:
+
+  CachedModel.use_memcache = false
+  CachedModel.ttl = 86400
+
+The default TTL for memcache objects is 900 seconds.
+

data/Rakefile

@@ -8,7 +8,7 @@ $VERBOSE = nil
 
 spec = Gem::Specification.new do |s|
   s.name = 'cached_model'
-  s.version = '1.0.1'
+  s.version = '1.1.0'
   s.summary = 'An ActiveRecord::Base model that caches records'
   s.authors = 'Robert Cottrell, Eric Hodel'
   s.email = 'bob@robotcoop.com'

data/lib/cached_model.rb

@@ -9,12 +9,53 @@ require 'memcache_util' unless $TESTING == :cached_model
 
 class CachedModel < ActiveRecord::Base
 
-  KEY = 'active_record'
-  TTL = 60 * 15 # seconds
-  
   @cache_local = {}
+  @use_local_cache = false
+  @use_memcache = true
+  @ttl = 60 * 15
 
-  class << self; attr_reader :cache_local; end
+  class << self
+
+    ##
+    # The local process cache.  You shouldn't touch me.
+
+    attr_reader :cache_local
+
+    ##
+    # Enables or disables use of the local cache.
+    #
+    # NOTE if you enable this you must call #cache_reset or you will
+    # experience uncontrollable process growth!
+    #
+    # Defaults to false.
+
+    attr_writer :use_local_cache
+
+    ##
+    # Enables or disables the use of memcache.
+
+    attr_writer :use_memcache
+
+    ##
+    # Memcache record time-to-live for stored records.
+
+    attr_accessor :ttl
+
+    ##
+    # Returns true if use of the local cache is enabled.
+
+    def use_local_cache?
+      return @use_local_cache
+    end
+
+    ##
+    # Returns true if use of memcache is enabled.
+
+    def use_memcache?
+      return @use_memcache
+    end
+
+  end
 
   ##
   # Override the flawed assumption ActiveRecord::Base makes about inheritance.
@@ -22,7 +63,7 @@ class CachedModel < ActiveRecord::Base
   def self.descends_from_active_record?
     superclass == CachedModel
   end
-          
+
   ##
   # Override the flawed assumption ActiveRecord::Base makes about inheritance.
 
@@ -36,21 +77,21 @@ class CachedModel < ActiveRecord::Base
     end
   end
 
-  ##      
+  ##
   # Invalidate the cache entry for an record.  The update method will
   # automatically invalidate the cache when updates are made through
   # ActiveRecord model record.  However, several methods update tables with
   # direct sql queries for effeciency.  These methods should call this method
   # to invalidate the cache after making those changes.
-  #   
+  #
   # NOTE - if a SQL query updates multiple rows with one query, there is
   # currently no way to invalidate the affected entries unless the entire
   # cache is dumped or until the TTL expires, so try not to do this.
 
   def self.cache_delete(klass, id)
     key = "#{klass}:#{id}"
-    CachedModel.cache_local.delete key
-    Cache.delete "#{KEY}:#{key}"
+    CachedModel.cache_local.delete key if CachedModel.use_local_cache?
+    Cache.delete "active_record:#{key}" if CachedModel.use_memcache?
   end
 
   ##
@@ -58,7 +99,7 @@ class CachedModel < ActiveRecord::Base
   # filter at the beginning of each request.
 
   def self.cache_reset
-    CachedModel.cache_local.clear
+    CachedModel.cache_local.clear if CachedModel.use_local_cache?
   end
 
   ##
@@ -73,12 +114,14 @@ class CachedModel < ActiveRecord::Base
     if ($TESTING and $TESTING != :cached_model) or
        args.length != 1 or not Fixnum === args.first then
       records = super
+      # Rails requires two levels of indirection to look up a record
+      return records if args.first == :all and @skip_find_hack
       return records if RAILS_ENV == 'test'
       case records
       when Array then
         records.each { |r| r.cache_store }
       when CachedModel then
-        records.cache_store
+        records.cache_store # Model.find 1 gets cached here
       end
       return records
     end
@@ -86,26 +129,33 @@ class CachedModel < ActiveRecord::Base
     # Try to find the record in the local cache.
     id = args.first
     cache_key_local = "#{name}:#{id}"
-    record = CachedModel.cache_local[cache_key_local]
-    return record unless record.nil?
+    if CachedModel.use_local_cache? then
+      record = CachedModel.cache_local[cache_key_local]
+      return record unless record.nil?
+    end
 
     # Try to find the record in memcache and add it to the local cache
-    record = Cache.get "#{KEY}:#{cache_key_local}"
-    unless record.nil? then
-      CachedModel.cache_local[cache_key_local] = record
-      return record
+    if CachedModel.use_memcache? then
+      record = Cache.get "active_record:#{cache_key_local}"
+      unless record.nil? then
+        if CachedModel.use_local_cache? then
+          CachedModel.cache_local[cache_key_local] = record
+        end
+        return record
+      end
     end
 
-    # Fetch the record from the DB and cache it.
+    # Fetch the record from the DB.  Inside the mulitple levels of indirection
+    # of find it will get cached.
     #
     # We don't want the subsequent find_by_sql to loop back here, so guard
     # the call.
     #
-    # NOTE - this guard isn't thread safe.
+    # NOTE This guard is not thread safe, beware use of CachedModel where
+    # ActiveRecord's thread safety is disabled.
     begin
       @skip_find_hack = true
       record = super(args).first
-      record.cache_store
     ensure
       @skip_find_hack = false
     end
@@ -160,8 +210,8 @@ class CachedModel < ActiveRecord::Base
   # Remove this record from the cache.
 
   def cache_delete
-    cache_local.delete cache_key_local
-    Cache.delete cache_key_memcache
+    cache_local.delete cache_key_local if CachedModel.use_local_cache?
+    Cache.delete cache_key_memcache if CachedModel.use_memcache?
   end
 
   ##
@@ -175,7 +225,7 @@ class CachedModel < ActiveRecord::Base
   # The memcache key for this record.
 
   def cache_key_memcache
-    return "#{KEY}:#{cache_key_local}"
+    return "active_record:#{cache_key_local}"
   end
 
   ##
@@ -192,8 +242,12 @@ class CachedModel < ActiveRecord::Base
   def cache_store
     obj = dup
     obj.send :instance_variable_set, :@attributes, attributes_before_type_cast
-    cache_local[cache_key_local] = obj
-    Cache.put cache_key_memcache, obj, TTL
+    if CachedModel.use_local_cache? then
+      cache_local[cache_key_local] = obj
+    end
+    if CachedModel.use_memcache? then
+      Cache.put cache_key_memcache, obj, CachedModel.ttl
+    end
   end
 
 end

data/test/test_cached_model.rb

@@ -12,6 +12,32 @@ class ActiveRecord::Base
 
   attr_accessor :id, :attributes
 
+  def self.find(*args)
+    args.flatten!
+    case args.first
+    when :first then
+      return find(:all, *args)
+    when :all then
+      [new]
+    else
+      case args.length
+      when 1 then
+        return find(:first, *args) if Fixnum === args.first
+        raise "Dunno what to do"
+      when 2 then
+        return new
+      when 3 then
+        return [new, new, new]
+      else
+        raise "Dunno what to do"
+      end
+    end
+  end
+
+  def self.find_by_sql(query)
+    return [new]
+  end
+
   def self.next_id
     @count += 1
     return @count
@@ -25,17 +51,6 @@ class ActiveRecord::Base
     'id'
   end
 
-  def self.find(*args)
-    args.flatten!
-    return [new] if args.length == 1 and Fixnum === args.first
-    return new if args.length == 2
-    return [new, new, new] if args.length == 3
-  end
-
-  def self.find_by_sql(query)
-    return [new]
-  end
-
   def initialize
     @id = ActiveRecord::Base.next_id
     @attributes = { :data => 'data' }
@@ -102,14 +117,26 @@ end
 
 class TestCachedModel < Test::Unit::TestCase
 
+  DEFAULT_USE_LOCAL_CACHE = CachedModel.use_local_cache?
+  DEFAULT_USE_MEMCACHE = CachedModel.use_memcache?
+
   def setup
     @model = Concrete.new
     Cache.cache = {}
     Cache.ttl = {}
     CachedModel.cache_local = {}
+    CachedModel.use_local_cache = DEFAULT_USE_LOCAL_CACHE
+    CachedModel.use_memcache = DEFAULT_USE_MEMCACHE
+  end
+
+  def teardown
+    CachedModel.use_local_cache = DEFAULT_USE_LOCAL_CACHE
+    CachedModel.use_memcache = DEFAULT_USE_MEMCACHE
   end
 
   def test_class_cache_delete
+    CachedModel.use_local_cache = true
+    CachedModel.use_memcache = true
     util_set
 
     CachedModel.cache_delete @model.class, @model.id
@@ -118,7 +145,53 @@ class TestCachedModel < Test::Unit::TestCase
     assert_equal true, Cache.cache.empty?
   end
 
+  def test_class_cache_delete_without_local_cache
+    CachedModel.use_local_cache = false
+    CachedModel.use_memcache = true
+    util_set
+
+    CachedModel.cache_delete @model.class, @model.id
+
+    assert_equal false, CachedModel.cache_local.empty?
+    assert_equal true, Cache.cache.empty?
+  end
+
+  def test_class_cache_delete_without_memcache
+    CachedModel.use_local_cache = true
+    CachedModel.use_memcache = false
+    util_set
+
+    CachedModel.cache_delete @model.class, @model.id
+
+    assert_equal true, CachedModel.cache_local.empty?
+    assert_equal false, Cache.cache.empty?
+  end
+
   def test_class_cache_reset
+    CachedModel.use_local_cache = true
+    CachedModel.use_memcache = true
+    util_set
+
+    CachedModel.cache_reset
+    
+    assert_equal true, CachedModel.cache_local.empty?
+    assert_equal false, Cache.cache.empty?
+  end
+
+  def test_class_cache_reset_without_local_cache
+    CachedModel.use_local_cache = false
+    CachedModel.use_memcache = true
+    util_set
+
+    CachedModel.cache_reset
+    
+    assert_equal false, CachedModel.cache_local.empty?
+    assert_equal false, Cache.cache.empty?
+  end
+
+  def test_class_cache_reset_without_memcache
+    CachedModel.use_local_cache = true
+    CachedModel.use_memcache = false
     util_set
 
     CachedModel.cache_reset
@@ -133,45 +206,78 @@ class TestCachedModel < Test::Unit::TestCase
   end
 
   def test_class_find_complex
+    CachedModel.use_local_cache = true
+    CachedModel.use_memcache = true
+
     record = Concrete.find(1, :order => 'lock_version')
+
     assert_equal @model.id + 1, record.id
 
     assert_equal record, CachedModel.cache_local[record.cache_key_local]
     assert_equal record, Cache.cache[record.cache_key_memcache]
   end
 
+  def test_class_find_complex_without_local_cache
+    CachedModel.use_local_cache = false
+    CachedModel.use_memcache = true
+
+    record = Concrete.find(1, :order => 'lock_version')
+
+    assert_equal @model.id + 1, record.id
+
+    assert_equal nil, CachedModel.cache_local[record.cache_key_local]
+    assert_equal record, Cache.cache[record.cache_key_memcache]
+  end
+
+  def test_class_find_complex_without_memcache
+    CachedModel.use_local_cache = true
+    CachedModel.use_memcache = false
+
+    record = Concrete.find(1, :order => 'lock_version')
+
+    assert_equal @model.id + 1, record.id
+
+    assert_equal record, CachedModel.cache_local[record.cache_key_local]
+    assert_equal nil, Cache.cache[record.cache_key_memcache]
+  end
+
   def test_class_find_in_local_cache
+    CachedModel.use_local_cache = true
     util_set
 
     record = Concrete.find(1, :order => 'lock_version')
     assert_equal @model.id + 1, record.id
 
     assert_equal record, CachedModel.cache_local[record.cache_key_local]
-    assert_equal record, Cache.cache[record.cache_key_memcache]
   end
 
   def test_class_find_in_memcache
+    CachedModel.use_local_cache = true
+    CachedModel.use_memcache = true
     util_set
     CachedModel.cache_reset
 
     record = Concrete.find @model.id
+
     assert_equal @model, record
 
     assert_equal record, CachedModel.cache_local[record.cache_key_local]
   end
 
   def test_class_find_multiple
+    CachedModel.use_local_cache = true
     ids = [@model.id + 1, @model.id + 2, @model.id + 3]
     records = Concrete.find(*ids)
     assert_equal ids, records.map { |r| r.id }
 
-    assert_equal ids.map { |i| "#{@model.class}:#{i}" },
-                 CachedModel.cache_local.keys
-    assert_equal ids.map { |i| "#{CachedModel::KEY}:#{@model.class}:#{i}" },
-                 Cache.cache.keys
+    assert_equal ids.map { |i| "#{@model.class}:#{i}" }.sort,
+                 CachedModel.cache_local.keys.sort
+    assert_equal ids.map { |i| "active_record:#{@model.class}:#{i}" }.sort,
+                 Cache.cache.keys.sort
   end
 
   def test_class_find_not_cached
+    CachedModel.use_local_cache = true
     record = Concrete.find @model.id + 1
     assert_equal @model.id + 1, record.id
 
@@ -180,6 +286,7 @@ class TestCachedModel < Test::Unit::TestCase
   end
 
   def test_class_find_by_sql
+    CachedModel.use_local_cache = true
     q = "SELECT * FROM concrete WHERE (concrete.id = #{@model.id + 1}) LIMIT 1"
     record = Concrete.find_by_sql(q).first
     assert_equal @model.id + 1, record.id
@@ -207,7 +314,28 @@ class TestCachedModel < Test::Unit::TestCase
                  CachedModel.class_name_of_active_record_descendant(STILameness)
   end
 
+  def test_class_ttl
+    assert_equal 900, CachedModel.ttl
+    CachedModel.ttl = 800
+    assert_equal 800, CachedModel.ttl
+  end
+
+  def test_class_use_local_cache_eh
+    CachedModel.use_local_cache = true
+    assert_equal true, CachedModel.use_local_cache?
+    CachedModel.use_local_cache = false
+    assert_equal false, CachedModel.use_local_cache?
+  end
+
+  def test_class_use_memcache_eh
+    CachedModel.use_memcache = true
+    assert_equal true, CachedModel.use_memcache?
+    CachedModel.use_memcache = false
+    assert_equal false, CachedModel.use_memcache?
+  end
+
   def test_cache_delete
+    CachedModel.use_local_cache = true
     util_set
 
     @model.cache_delete
@@ -221,7 +349,7 @@ class TestCachedModel < Test::Unit::TestCase
   end
 
   def test_cache_key_memcache
-    assert_equal "#{CachedModel::KEY}:#{@model.class}:#{@model.id}",
+    assert_equal "active_record:#{@model.class}:#{@model.id}",
                  @model.cache_key_memcache
   end
 
@@ -230,16 +358,48 @@ class TestCachedModel < Test::Unit::TestCase
   end
 
   def test_cache_store
+    CachedModel.use_local_cache = true
+    CachedModel.use_memcache = true
+
     @model.cache_store
+
     assert_equal false, CachedModel.cache_local.empty?
     assert_equal false, Cache.cache.empty?
 
     assert_equal @model, CachedModel.cache_local[@model.cache_key_local]
     assert_equal @model, Cache.cache[@model.cache_key_memcache]
-    assert_equal CachedModel::TTL, Cache.ttl[@model.cache_key_memcache]
+    assert_equal CachedModel.ttl, Cache.ttl[@model.cache_key_memcache]
+  end
+
+  def test_cache_store_without_local_cache
+    CachedModel.use_local_cache = false
+    CachedModel.use_memcache = true
+
+    @model.cache_store
+
+    assert_equal true, CachedModel.cache_local.empty?
+    assert_equal false, Cache.cache.empty?
+
+    assert_equal nil, CachedModel.cache_local[@model.cache_key_local]
+    assert_equal @model, Cache.cache[@model.cache_key_memcache]
+    assert_equal CachedModel.ttl, Cache.ttl[@model.cache_key_memcache]
+  end
+
+  def test_cache_store_without_memcache
+    CachedModel.use_local_cache = true
+    CachedModel.use_memcache = false
+
+    @model.cache_store
+
+    assert_equal false, CachedModel.cache_local.empty?
+    assert_equal true, Cache.cache.empty?
+
+    assert_equal @model, CachedModel.cache_local[@model.cache_key_local]
+    assert_equal nil, Cache.cache[@model.cache_key_memcache]
   end
 
   def test_cache_store_with_attributes
+    CachedModel.use_local_cache = true
     @model.attributes[:extra] = 'extra'
     @model.cache_store
     assert_equal false, CachedModel.cache_local.empty?
@@ -249,7 +409,7 @@ class TestCachedModel < Test::Unit::TestCase
     mem_model = Cache.cache[@model.cache_key_memcache]
     assert_equal @model, local_model
     assert_equal @model, mem_model
-    assert_equal CachedModel::TTL, Cache.ttl[@model.cache_key_memcache]
+    assert_equal CachedModel.ttl, Cache.ttl[@model.cache_key_memcache]
 
     expected = {:data => 'data'}
 
@@ -258,6 +418,7 @@ class TestCachedModel < Test::Unit::TestCase
   end
 
   def test_destroy
+    CachedModel.use_local_cache = true
     util_set
 
     @model.destroy
@@ -298,7 +459,7 @@ class TestCachedModel < Test::Unit::TestCase
   def util_set(klass = @model.class, id = @model.id, data = @model)
     key = "#{klass}:#{id}"
     CachedModel.cache_local[key] = data
-    Cache.cache["#{CachedModel::KEY}:#{key}"] = data
+    Cache.cache["active_record:#{key}"] = data
   end
 
 end

metadata

@@ -3,8 +3,8 @@ rubygems_version: 0.8.11.6
 specification_version: 1
 name: cached_model
 version: !ruby/object:Gem::Version 
-  version: 1.0.1
-date: 2006-01-30 00:00:00 -08:00
+  version: 1.1.0
+date: 2006-02-19 00:00:00 -08:00
 summary: An ActiveRecord::Base model that caches records
 require_paths: 
 - lib
@@ -25,6 +25,7 @@ required_ruby_version: !ruby/object:Gem::Version::Requirement
 platform: ruby
 signing_key: 
 cert_chain: 
+post_install_message: 
 authors: 
 - Robert Cottrell, Eric Hodel
 files: