cache_method 0.2.3 → 0.2.4

data/CHANGELOG

@@ -1,3 +1,9 @@
+0.2.4 / 2012-04-17
+
+* Enhancements
+
+  * Refactored to simplify and make thread-safe
+
 0.2.3 / 2012-04-06
 
 * Enhancements

data/Gemfile

@@ -7,3 +7,5 @@ gemspec
 gem 'rake'
 gem 'dalli'
 gem 'yard'
+gem 'minitest'
+gem 'minitest-reporters'

data/README.markdown

@@ -6,28 +6,35 @@ Lets you cache the results of calling methods given their arguments. Like memoiz
 
 ## Real-world usage
 
-In production use at [impact.brighterplanet.com](http://impact.brighterplanet.com) and [data.brighterplanet.com](http://data.brighterplanet.com).
+<p><a href="http://brighterplanet.com"><img src="https://s3.amazonaws.com/static.brighterplanet.com/assets/logos/flush-left/inline/green/rasterized/brighter_planet-160-transparent.png" alt="Brighter Planet logo"/></a></p>
+
+We use `cache_method` for [data science at Brighter Planet](http://brighterplanet.com/research) and in production at
+
+* [Brighter Planet's impact estimate web service](http://impact.brighterplanet.com)
+* [Brighter Planet's reference data web service](http://data.brighterplanet.com)
+
+## Rationale
+
+* It should be easy to cache instance methods
+* It should be easy to cache methods that depend on object state
+* It should be easy to uncache a method without clearing the whole cache
+* It should be easy to do all that using a default in-process store, memcached, dalli (if you're on heroku), redis, etc. (all supported by this gem through the [cache gem](https://rubygems.org/gems/cache))
 
 ## Example
 
     require 'cache_method'
     class Blog
-      attr_reader :name
-      attr_reader :url
-
+      attr_reader :name, :url
       def initialize(name, url)
         @name = name
         @url = url
       end
-
-      def get_latest_entries
+      # The slow method that you want to speed up
+      def entries(date)
         # ...
       end
-      cache_method :get_latest_entries
-
-      # By default, cache_method derives the cache key for an instance by getting the SHA1 hash of the Marshal.dump
-      # If you need to customize how an instance is recognized, you can define #as_cache_key.
-      # Marshal.load will be called on the result.
+      cache_method :entries
+      # Not always required
       def as_cache_key
         { :name => name, :url => url }
       end
@@ -35,37 +42,20 @@ In production use at [impact.brighterplanet.com](http://impact.brighterplanet.co
 
 Then you can do
 
-    my_blog.get_latest_entries => first time won't be cached
-    my_blog.get_latest_entries => second time will come from cache
+    my_blog.entries(Date.today) => first time won't be cached
+    my_blog.entries(Date.today) => second time will come from cache
 
 And clear them too
 
-    my_blog.cache_method_clear :get_latest_entries
+    my_blog.cache_method_clear :entries
 
 (which doesn't delete the rest of your cache)
 
-## ActiveRecord
-
-If you're caching methods ActiveRecord objects (aka instances of `ActiveRecord::Base`), then you should probably define something like:
-
-    class ActiveRecord::Base
-      def as_cache_key
-        attributes
-      end
-    end
-
-## Debug
-
-CacheMethod can warn you if your obj or args cache keys are suspiciously long.
-
-    require 'cache_method'
-    require 'cache_method/debug'
-
-Then watch your logs.
-
 ## Configuration (and supported cache clients)
 
-You need to set where the cache will be stored:
+By default, an in-process, non-shared cache is used.
+
+You can set where the cache will be stored:
 
     CacheMethod.config.storage = Memcached.new '127.0.0.1:11211'
 
@@ -79,13 +69,30 @@ or this might even work...
 
 See `Config` for the full list of supported caches.
 
-## Defining a #as_cache_key method
+## Cache keys
+
+Caching a method involves getting cache keys for
+
+1. the object where the method is defined - for example, `my_blog.as_cache_key`
+2. the arguments passed to the method - for example, `Marshal.dump(Date.today)`, because `Date#as_cache_key` is not defined
+
+Then the cache keys are SHA-1 hashed and combined for an overall key:
+
+    method signature + obj digest                                                                           + args digest
+    Blog#entries     + SHA1(Marshal.dump({:name="Seamus's blog",:url=>"http://numbers.brighterplanet.com"}) + SHA1(Marshal.dump(Date.today))
+
+Technically the full cache key is
+
+    # when caching class methods
+    method signature + generation + args digest
+    # when caching instance methods
+    method signature + obj digest + generation + args digest
 
-Since we're not pure functional programmers, sometimes cache hits depend on object state in addition to method arguments. To illustrate:
+(see "Generational caching" below for an explanation of the generation part)
 
-    my_blog.get_latest_entries
+### #as_cache_key
 
-get_latest_entries doesn't take any arguments, so it must depend on my_blog.url or something. This works because we define:
+As above, you can define a custom cache key for an object:
 
     class Blog
       # [...]
@@ -95,26 +102,97 @@ get_latest_entries doesn't take any arguments, so it must depend on my_blog.url
       # [...]
     end
 
-If you don't define `#as_cache_key`, then `cache_method` will `Marshal.dump` an instance.
+If you don't define `#as_cache_key`, the default is to `Marshal.dump` the whole object. (That's not as terrible as it seems - marshalling is fast!)
 
-## Danger: #to_cache_key
+### #to_cache_key (danger!)
 
-Let's say you want need cache keys from classes that undefine the `#class` method (how annoying). You can define `#to_cache_key`, but **make sure it identifies the class too!** (in addition to the instance.)
+There's another way to define a cache key, but it should be used with caution because it gives you total control.
 
-For example, if you find yourself passing association proxies as arguments to cached methods, this might be helpful:
+The key is to make sure your `#to_cache_key` method identifies both the class and the instance!
 
-    user = User.first
-    Foo.bar(user.groups) # you're passing an association as an argument
+### Comparison
 
+<table>
+  <tr>
+    <th>Method</th>
+    <th>Must uniquely identify class</th>
+    <th>Must uniquely identify instance</th>
+  </tr>
+  <tr>
+    <td><code>#as_cache_key</code></td>
+    <td>N&dagger;</td>
+    <td>Y</td>
+  </tr>
+  <tr>
+    <td><code>#to_cache_key</code></td>
+    <td>Y</td>
+    <td>Y</td>
+  </tr>
+</table>
+
+&dagger; The class name is automatically inserted for you by calling `object.class.name`, which is what causes all the trouble with `ActiveRecord::Associations::CollectionProxy`, etc.
+
+## ActiveRecord
+
+If you're caching methods on instances of `ActiveRecord::Base`, and/or using them as arguments to other cached methods, then you should probably define something like:
+
+    class ActiveRecord::Base
+      def as_cache_key
+        attributes
+      end
+    end
+
+If you find yourself passing association proxies as arguments to cached methods, this might be helpful:
+
+    # For use in ActiveRecord 3.0.x
     class ActiveRecord::Associations::AssociationCollection
-      # danger! this is a special case... try to use #as_cache_key instead
-      # also note that this example is based on ActiveRecord 3.0.10 ... YMMV
+      # rare use of to_cache_key
       def to_cache_key
-        [ proxy_owner.class.name, proxy_owner.id, proxy_reflection.name, conditions ].join('/')
+        [
+          'ActiveRecord::Associations::AssociationCollection',
+          proxy_owner.class.name,
+          proxy_owner.id,
+          proxy_reflection.name,
+          conditions
+        ].join('/')
       end
     end
 
-Otherwise, `cache_method` will try to run `user.groups.class` which causes the proxy to be loaded. You probably don't want to load 1000 AR objects just to generate a cache key.
+    # For use in ActiveRecord 3.2.x
+    class ActiveRecord::Associations::CollectionProxy
+      # rare use of to_cache_key
+      def to_cache_key
+        owner = proxy_association.owner
+        [
+          'ActiveRecord::Associations::CollectionProxy',   # [included because we're using #to_cache_key instead of #as_cache_key ]
+          owner.class.name,                                # User
+          owner.id,                                        # 'seamusabshere'
+          proxy_association.reflection.name,               # :comments
+          scoped.where_sql                                 # "WHERE `comments`.`user_id` = 'seamusabshere'" [maybe a little bit redundant, but play it safe]
+        ].join('/')
+      end
+    end
+
+Otherwise, `cache_method` will call `user.comments.class.name` which causes the proxy to load the target, i.e. load all the Comment objects into memory. You probably don't want to load 1000 AR objects just to generate a cache key.
+
+## Generational caching
+
+Generational caching allows clearing the cached results for only one method, for example
+
+    my_blog.cache_method_clear :entries
+
+You can disable it to get a little speed boost
+
+    CacheMethod.config.generational = false
+
+## Debug
+
+CacheMethod can warn you if your obj or args cache keys are suspiciously long.
+
+    require 'cache_method'
+    require 'cache_method/debug'
+
+Then watch your logs.
 
 ## Module methods
 
@@ -143,13 +221,6 @@ Rest assured that `Tiger.my_module_method` and `Lion.my_module_method` will be c
       # cache_method :my_module_method
     end
 
-## Rationale
-
-* It should be easy to cache a method using memcached, dalli (if you're on heroku), redis, etc. (that's why I made the [cache gem](https://rubygems.org/gems/cache))
-* It should be easy to uncache a method without clearing the whole cache
-* It should be easy to cache instance methods
-* It should be easy to cache methods that depend on object state (hence `#as_cache_key`)
-
 ## Copyright
 
 Copyright 2012 Seamus Abshere

data/lib/cache_method/cached_result.rb

@@ -1,91 +1,66 @@
-require 'digest/sha1'
 module CacheMethod
   class CachedResult #:nodoc: all
-    class << self
-      def resolve_cache_key(obj)
-        case obj
-        when ::Array
-          obj.map do |v|
-            resolve_cache_key v
-          end
-        when ::Hash
-          obj.inject({}) do |memo, (k, v)|
-            kk = resolve_cache_key k
-            vv = resolve_cache_key v
-            memo[kk] = vv
-            memo
-          end
-        else
-          if obj.respond_to?(:to_cache_key)
-            # this is meant to be used sparingly, usually when a proxy class is involved
-            obj.to_cache_key
-          elsif obj.respond_to?(:as_cache_key)
-            [obj.class.name, obj.as_cache_key]
-          else
-            obj
-          end
-        end
-      end
-    end
-    
-    CACHE_KEY_JOINER = ','
-
-    def initialize(obj, method_id, original_method_id, ttl, args)
+    def initialize(obj, method_id, original_method_id, ttl, args, &blk)
       @obj = obj
       @method_id = method_id
+      @method_signature = CacheMethod.method_signature obj, method_id
       @original_method_id = original_method_id
-      @ttl = ttl
+      @ttl = ttl || CacheMethod.config.default_ttl
       @args = args
+      @args_digest = args.empty? ? 'empty' : CacheMethod.digest(args)
+      @blk = blk
+      @fetch_mutex = ::Mutex.new
     end
 
     attr_reader :obj
     attr_reader :method_id
+    attr_reader :method_signature
     attr_reader :original_method_id
     attr_reader :args
+    attr_reader :args_digest
+    attr_reader :blk
+    attr_reader :ttl
     
     # Store things wrapped in an Array so that nil is accepted
     def fetch
-      if v = Config.instance.storage.get(cache_key) and v.is_a?(::Array)
-        v.first
+      if wrapped_v = get_wrapped
+        wrapped_v.first
       else
-        v = obj.send original_method_id, *args
-        Config.instance.storage.set cache_key, [v], ttl
-        v
+        @fetch_mutex.synchronize do
+          (get_wrapped || set_wrapped).first
+        end
       end
     end
 
     def exist?
-      Config.instance.storage.exist?(cache_key)
+      CacheMethod.config.storage.exist?(cache_key)
     end
-    
-    def ttl
-      @ttl ||= Config.instance.default_ttl
-    end
-    
+        
+    private
+
     def cache_key
       if obj.is_a?(::Class) or obj.is_a?(::Module)
         [ 'CacheMethod', 'CachedResult', method_signature, current_generation, args_digest ].compact.join CACHE_KEY_JOINER
       else
-        [ 'CacheMethod', 'CachedResult', method_signature, obj_digest, current_generation, args_digest ].compact.join CACHE_KEY_JOINER
+        [ 'CacheMethod', 'CachedResult', method_signature, CacheMethod.digest(obj), current_generation, args_digest ].compact.join CACHE_KEY_JOINER
       end
     end
-    
-    def method_signature
-      @method_signature ||= ::CacheMethod.method_signature(obj, method_id)
-    end
-            
-    def obj_digest
-      @obj_digest ||= ::Digest::SHA1.hexdigest(::Marshal.dump(CachedResult.resolve_cache_key(obj)))
-    end
-  
-    def args_digest
-      @args_digest ||= args.empty? ? 'empty' : ::Digest::SHA1.hexdigest(::Marshal.dump(CachedResult.resolve_cache_key(args)))
-    end
-        
+
     def current_generation
-      if Config.instance.generational?
-        @current_generation ||= Generation.new(obj, method_id).current
+      if CacheMethod.config.generational?
+        Generation.new(obj, method_id).fetch
       end
     end
+
+    def get_wrapped
+      CacheMethod.config.storage.get cache_key
+    end
+
+    def set_wrapped
+      v = obj.send(*([original_method_id]+args), &blk)
+      wrapped_v = [v]
+      CacheMethod.config.storage.set cache_key, wrapped_v, ttl
+      wrapped_v
+    end
   end
 end

data/lib/cache_method/config.rb

@@ -1,5 +1,5 @@
 require 'cache'
-require 'singleton'
+
 module CacheMethod
   # Here's where you set config options.
   #
@@ -9,7 +9,10 @@ module CacheMethod
   #
   # You'd probably put this in your Rails config/initializers, for example.
   class Config
-    include ::Singleton
+
+    def initialize
+      @mutex = ::Mutex.new
+    end
     
     # Whether to use "generational" caching. Default is true.
     #
@@ -44,7 +47,9 @@ module CacheMethod
     end
 
     def storage #:nodoc:
-      @storage ||= ::Cache.new
+      @storage || @mutex.synchronize do
+        @storage ||= ::Cache.new
+      end
     end
     
     # TTL for method caches. Defaults to 24 hours or 86,400 seconds.

data/lib/cache_method/debug.rb

@@ -1,17 +1,8 @@
 module CacheMethod
-  class CachedResult #:nodoc: all
-    def obj_digest
-      if (l = ::Marshal.dump(CachedResult.resolve_cache_key(obj)).length) > 500
-        $stderr.puts "Warn: #{l} long obj digest. #{obj.class} -> #{CachedResult.resolve_cache_key(obj).inspect}"
-      end
-      @obj_digest ||= ::Digest::SHA1.hexdigest(::Marshal.dump(CachedResult.resolve_cache_key(obj)))
-    end
-  
-    def args_digest
-      if (l = ::Marshal.dump(CachedResult.resolve_cache_key(args)).length) > 500
-        $stderr.puts "Warn: #{l} long args digest. #{method_signature}(#{CachedResult.resolve_cache_key(args).inspect})"
-      end
-      @args_digest ||= args.empty? ? 'empty' : ::Digest::SHA1.hexdigest(::Marshal.dump(CachedResult.resolve_cache_key(args)))
+  def CacheMethod.digest(obj)
+    if (l = ::Marshal.dump(resolve_cache_key(obj)).length) > 500
+      $stderr.puts "[cache_method] Warn: #{l} long digest. #{obj.class} -> #{resolve_cache_key(obj).inspect}"
     end
+    ::Digest::SHA1.hexdigest ::Marshal.dump(resolve_cache_key(obj))
   end
 end

data/lib/cache_method/generation.rb

@@ -1,49 +1,49 @@
-require 'digest/sha1'
 module CacheMethod
   class Generation #:nodoc: all
-    class << self
-      def random_name
-        rand(100_000_000).to_s
-      end
-    end
-
     def initialize(obj, method_id)
       @obj = obj
       @method_id = method_id
+      @method_signature = CacheMethod.method_signature obj, method_id
+      @fetch_mutex = ::Mutex.new
     end
     
     attr_reader :obj
     attr_reader :method_id
-    
-    def method_signature
-      @method_signature ||= ::CacheMethod.method_signature(obj, method_id)
+    attr_reader :method_signature
+        
+    def fetch
+      if existing = get
+        existing
+      else
+        @fetch_mutex.synchronize do
+          get || set
+        end
+      end
     end
     
-    def obj_digest
-      @obj_digest ||= ::Digest::SHA1.hexdigest(::Marshal.dump(obj.respond_to?(:as_cache_key) ? obj.as_cache_key : obj))
+    def mark_passing
+      CacheMethod.config.storage.delete cache_key
     end
-    
+
+    private
+
     def cache_key
       if obj.is_a?(::Class) or obj.is_a?(::Module)
-        [ 'CacheMethod', 'Generation', method_signature ].join ','
+        [ 'CacheMethod', 'Generation', method_signature ].join CACHE_KEY_JOINER
       else
-        [ 'CacheMethod', 'Generation', method_signature, obj_digest ].join ','
+        [ 'CacheMethod', 'Generation', method_signature, CacheMethod.digest(obj) ].join CACHE_KEY_JOINER
       end
     end
-    
-    def current
-      if cached_v = Config.instance.storage.get(cache_key)
-        cached_v
-      else
-        v = Generation.random_name
-        # never expire!
-        Config.instance.storage.set cache_key, v, 0
-        v
-      end
+
+    def get
+      CacheMethod.config.storage.get cache_key
     end
-    
-    def mark_passing
-      Config.instance.storage.delete cache_key
+
+    def set
+      random_name = ::Kernel.rand(1e11).to_s
+      # never expire!
+      CacheMethod.config.storage.set cache_key, random_name, 0
+      random_name
     end
   end
 end

data/lib/cache_method/version.rb

@@ -1,3 +1,3 @@
 module CacheMethod
-  VERSION = "0.2.3"
+  VERSION = "0.2.4"
 end

data/lib/cache_method.rb

@@ -1,24 +1,60 @@
+require 'thread'
+require 'digest/sha1'
+
 require 'cache_method/config'
 require 'cache_method/cached_result'
 require 'cache_method/generation'
 
-# See the README.rdoc for more info!
 module CacheMethod
-  def self.config #:nodoc:
-    Config.instance
+  MUTEX = ::Mutex.new
+  CACHE_KEY_JOINER = ','
+
+  def CacheMethod.config #:nodoc:
+    @config || MUTEX.synchronize do
+      @config ||= Config.new
+    end
   end
   
-  def self.klass_name(obj) #:nodoc:
+  def CacheMethod.klass_name(obj) #:nodoc:
     (obj.is_a?(::Class) or obj.is_a?(::Module)) ? obj.to_s : obj.class.to_s
   end
   
-  def self.method_delimiter(obj) #:nodoc:
+  def CacheMethod.method_delimiter(obj) #:nodoc:
     (obj.is_a?(::Class) or obj.is_a?(::Module)) ? '.' : '#'
   end
   
-  def self.method_signature(obj, method_id) #:nodoc:
+  def CacheMethod.method_signature(obj, method_id) #:nodoc:
     [ klass_name(obj), method_id ].join method_delimiter(obj)
   end
+
+  def CacheMethod.resolve_cache_key(obj)
+    case obj
+    when ::Array
+      obj.map do |v|
+        resolve_cache_key v
+      end
+    when ::Hash
+      obj.inject({}) do |memo, (k, v)|
+        kk = resolve_cache_key k
+        vv = resolve_cache_key v
+        memo[kk] = vv
+        memo
+      end
+    else
+      if obj.respond_to?(:to_cache_key)
+        # this is meant to be used sparingly, usually when a proxy class is involved
+        obj.to_cache_key
+      elsif obj.respond_to?(:as_cache_key)
+        [obj.class.name, obj.as_cache_key]
+      else
+        obj
+      end
+    end
+  end
+
+  def CacheMethod.digest(obj)
+    ::Digest::SHA1.hexdigest ::Marshal.dump(resolve_cache_key(obj))
+  end
     
   # All Objects, including instances and Classes, get the <tt>#cache_method_clear</tt> method.
   module InstanceMethods
@@ -59,15 +95,13 @@ module CacheMethod
     def cache_method(method_id, ttl = nil)
       original_method_id = "_uncached_#{method_id}"
       alias_method original_method_id, method_id
-      define_method method_id do |*args|
-        ::CacheMethod::CachedResult.new(self, method_id, original_method_id, ttl, args).fetch
+      define_method method_id do |*args, &blk|
+        ::CacheMethod::CachedResult.new(self, method_id, original_method_id, ttl, args, &blk).fetch
       end
     end
   end
 end
 
-unless ::Object.method_defined? :cache_method
-  ::Object.send :include, ::CacheMethod::InstanceMethods
-  ::Class.send :include, ::CacheMethod::ClassMethods
-  ::Module.send :include, ::CacheMethod::ClassMethods
-end
+::Object.send :include, ::CacheMethod::InstanceMethods
+::Class.send :include, ::CacheMethod::ClassMethods
+::Module.send :include, ::CacheMethod::ClassMethods

data/test/helper.rb

@@ -1,19 +1,17 @@
 require 'rubygems'
-require 'bundler'
-Bundler.setup
-require 'test/unit'
+require 'bundler/setup'
+require 'minitest/spec'
+require 'minitest/autorun'
+require 'minitest/reporters'
+MiniTest::Unit.runner = MiniTest::SuiteRunner.new
+MiniTest::Unit.runner.reporters << MiniTest::Reporters::SpecReporter.new
 
 if ::Bundler.definition.specs['ruby-debug19'].first or ::Bundler.definition.specs['ruby-debug'].first
   require 'ruby-debug'
 end
 
-$LOAD_PATH.unshift(File.join(File.dirname(__FILE__), '..', 'lib'))
-$LOAD_PATH.unshift(File.dirname(__FILE__))
 require 'cache_method'
 
-class Test::Unit::TestCase
-end
-
 class CopyCat1
   attr_reader :name
   def initialize(name)