tagged-cache 1.0.0

data/History.txt

@@ -0,0 +1,3 @@
+=== 1.0.0 2010-10-06
+
+  * Added ActiveSupport::Cache adapter.

data/README.rdoc

@@ -0,0 +1,92 @@
+= tagged-cache
+
+* http://github.com/antage/tagged-cache
+
+== DESCRIPTION:
+
+ActiveSupport cache adapter with tagged dependencies.
+
+== SYNOPSIS:
+
+=== RUBY EXAMPLE:
+
+  require 'active_support'
+
+  cache = ActiveSupport::Cache.lookup_store(:tagged_store,
+    :tag_store => [:memory_store, :namespace => "tags"],
+    :entity_store => [:memory_store, :namespace => "entities"]
+  )
+
+  # tags management
+  cache.read_tag("tag1") # returns Fixnum
+  cache.read_tags("tag1", "tag2") # returns Hash { "tag1" => tag1_version, "tag2" => tag2_version }
+  cache.touch_tag("tag1") # increment tag1's version
+
+  # reading and writing cache
+  cache.write("cache key", value, :depends => ["tag1", "tag2"])
+  cache.fetch("cache key", :depends => ["tag1", "tag2]) { value }
+
+  # or
+
+  cache.tagged_fetch("cache key") do |entry|
+    entry.depends "tag1"
+    entry << "tag2"
+    entry.concat ["tag3", "tag4"]
+    entry.concat "tag5", "tag6"
+    value
+  end
+
+  # any object with method 'cache_tag' can be used as tag name
+  class A
+    attr_accessor :id
+
+    def cache_tag
+      "class/A/#{id}"
+    end
+  end
+
+  cache.tagged_fetch("some cache path") do |entry|
+    obj1 = A.new
+    obj1.id = 1
+
+    obj2 = A.new
+    obj2.id = 2
+
+    entry.depends obj1
+    entry.depends obj2
+
+    [obj1, obj2]
+  end
+
+== REQUIREMENTS:
+
+* activesupport >= 3.0.0
+
+== INSTALL:
+
+* sudo gem install tagged-cache
+
+== LICENSE:
+
+(The MIT License)
+
+Copyright (c) 2010 Anton Ageev
+
+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/Rakefile

@@ -0,0 +1,3 @@
+require 'rubygems'
+require 'bundler'
+Bundler::GemHelper.install_tasks

data/lib/active_support/cache/tagged_store.rb

@@ -0,0 +1,181 @@
+require "active_support/core_ext/integer/time"
+
+module ActiveSupport
+  module Cache
+    module TaggedEntry
+      attr_accessor :depends
+    end
+
+    class TaggedStore < Store
+      class Dependencies
+        def initialize(initial)
+          @tags = initial || []
+        end
+        
+        def tags
+          @tags
+        end
+        
+        def depends(tag)
+          @tags << tag
+        end
+        
+        def <<(tag)
+          @tags << tag
+        end
+        
+        def concat(*args)
+          if args.size == 1 && args.first.is_a?(Array)
+            @tags.concat(args.first)
+          else
+            @tags.concat(args)
+          end
+        end
+      end
+      
+      def initialize(options = nil)
+        unless options && options[:tag_store] && options[:entity_store]
+          raise ":tag_store and :entity_store options are required"
+        else
+          @tag_store = Cache.lookup_store(*options.delete(:tag_store))
+          @entity_store = Cache.lookup_store(*options.delete(:entity_store))
+          
+          @options = {}
+        end
+      end
+
+      def read_tag(key)
+        instrument(:read_tag, key) do
+          key = expanded_tag(key)
+          tag_value = @tag_store.read(key, :raw => true)
+          if tag_value.nil? || tag_value.to_i.zero?
+            new_value = Time.now.to_i
+            @tag_store.write(key, new_value, :raw => true)
+            new_value
+          else
+            tag_value.to_i
+          end
+        end
+      end
+
+      def read_tags(*keys)
+        instrument(:read_tags, keys) do
+          options = keys.extract_options! || {}
+          tag_names = keys.map { |k| expanded_tag(k) }
+          tags = @tag_store.read_multi(*(keys << options.merge(:raw => true)))
+          (tag_names - tags.keys).each do |unknown_tag|
+            tags[unknown_tag] = read_tag(unknown_tag)
+          end
+          tags
+        end
+      end
+
+      def touch_tag(key)
+        instrument(:touch_tag, key) do
+          key = expanded_tag(key)
+          @tag_store.increment(key) || @tag_store.write(key, Time.now.to_i, :raw => true)
+        end
+      end
+      
+      def tagged_fetch(name, options = nil)
+        if block_given?
+          options = merged_options(options)
+          key = namespaced_key(name, options)
+          unless options[:force]
+            entry = instrument(:read, name, options) do |payload|
+              payload[:super_operation] = :fetch if payload
+              read_entry(key, options)
+            end
+          end
+          if entry && entry.expired?
+            race_ttl = options[:race_condition_ttl].to_f
+            if race_ttl and Time.now.to_f - entry.expires_at <= race_ttl
+              entry.expires_at = Time.now + race_ttl
+              write_entry(key, entry, :expires_in => race_ttl * 2)
+            else
+              delete_entry(key, options)
+            end
+            entry = nil
+          end
+
+          if entry
+            instrument(:fetch_hit, name, options) { |payload| }
+            entry.value
+          else
+            dependencies = Dependencies.new(options[:depends])
+            result = instrument(:generate, name, options) do |payload|
+              yield(dependencies)
+            end
+            write(name, result, options.merge(:depends => dependencies.tags))
+            result
+          end
+        else
+          read(name, options)
+        end        
+      end
+      
+      def delete_matched(matcher, options = nil)
+        @entity_store.delete_matched(matcher, options)
+      end
+      
+      def increment(name, amount = 1, options = nil)
+        @entity_store.increment(name, amount, options)
+      end
+      
+      def decrement(name, amount = 1, options = nil)
+        @entity_store.decrement(name, amount, options)
+      end
+      
+      def cleanup(options = nil)
+        @entity_store.cleanup(options)
+      end
+      
+      def clear(options = nil)
+        @entity_store.clear(options)
+      end
+      
+      protected
+      
+      def read_entry(key, options)
+        entry = @entity_store.send(:read_entry, key, options)
+        if entry.respond_to?(:depends) && entry.depends && !entry.depends.empty?
+          tags = read_tags(*entry.depends.keys)
+          valid = entry.depends.all? { |k, v| tags[k] == v }
+          entry.expires_at = (entry.created_at - 1.year) unless valid
+        end
+        entry
+      end
+      
+      def write_entry(key, entry, options)
+        depends = (options[:depends] || []).uniq
+        unless depends.empty?
+          entry.extend(TaggedEntry)
+          entry.depends = read_tags(*depends)
+        end
+        @entity_store.send(:write_entry, key, entry, options.delete(:depends))
+      end
+      
+      def delete_entry(key, options)
+        @entity_store.send(:delete_entry, key, options)
+      end
+      
+      private
+      
+      def namespaced_key(key, options)
+        key = expanded_key(key)
+        namespace = @entity_store.options[:namespace] if @entity_store.options
+        prefix = namespace.is_a?(Proc) ? namespace.call : namespace
+        key = "#{prefix}:#{key}" if prefix
+        key    
+      end
+      
+      def expanded_tag(tag)
+        if tag.respond_to?(:cache_tag)
+          tag = tag.cache_tag.to_s
+        else
+          tag.to_s
+        end
+      end
+    end
+  end
+end

data/spec/spec_helper.rb

@@ -0,0 +1,7 @@
+require 'rspec'
+
+Rspec.configure do |c|
+  c.mock_with :rspec
+end
+
+$LOAD_PATH << File.expand_path(File.join(File.dirname(__FILE__), "..", "lib"))

data/spec/tagged_store_spec.rb

@@ -0,0 +1,185 @@
+require "active_support"
+
+describe "TaggedStore" do
+  before(:each) do
+    @options = { :tag_store => [:memory_store, { :namespace => "tags" }], :entity_store => [:memory_store, { :namespace => "entities" }] }
+  end
+
+  context "without :tag_store option" do
+    subject { lambda { ActiveSupport::Cache.lookup_store :tagged_store, @options.delete(:tag_store) } }
+    it { should raise_exception }
+  end
+
+  context "without :entity_store option" do
+    subject { lambda { ActiveSupport::Cache.lookup_store :tagged_store, @options.delete(:entity_store) } }
+    it { should raise_exception }
+  end
+
+  context "with :tag_store and :entity_store options" do
+    subject { lambda { ActiveSupport::Cache.lookup_store :tagged_store, @options } }
+    it { should_not raise_exception }
+  end
+
+  context "instance" do
+    before(:each) do
+      @store ||= ActiveSupport::Cache.lookup_store :tagged_store, @options
+      @store.clear
+    end
+    
+    context "#read_tag('abc')" do
+      subject  { @store.read_tag("abc") }
+
+      it { should_not be_nil }
+      it "should be less or equal Time.now.to_i" do
+        should <= Time.now.to_i
+      end
+    end
+
+    context "#touch_tag('abc')" do
+      it "should increment tag value" do
+        old_value = @store.read_tag("abc")
+        @store.touch_tag("abc")
+        @store.read_tag("abc").should > old_value
+      end
+    end
+
+    context "#read_tags('tag1', 'tag2')" do
+      before(:each) do
+        @tag1_value = @store.read_tag("tag1")
+        @tag2_value = @store.read_tag("tag2")
+
+        @tags = @store.read_tags("tag1", "tag2")
+      end
+
+      specify { @tags.should have_key("tag1") }
+      specify { @tags.should have_key("tag2") }
+      
+      it "should return tag1's value" do
+        @tags["tag1"].should == @tag1_value
+      end
+
+      it "should return tag2's value" do
+        @tags["tag2"].should == @tag2_value
+      end
+
+      ["tag1", "tag2"].each do |tag_name|
+        context "#{tag_name}" do
+          subject { @tags[tag_name] }
+          it { should be_instance_of(Fixnum) }
+        end
+      end
+    end
+    
+    context "#read_tags('tagA', 'tagB')" do
+      context "when 'tagA' and 'tagB' don't exist in cache" do
+        before(:each) do
+          @tags = @store.read_tags("tagA", "tagB")
+        end
+        
+        ["tagA", "tagB"].each do |tag_name|
+          context tag_name do
+            subject { @tags[tag_name] }
+            it { should_not be_nil }
+            it { should be_instance_of(Fixnum) }
+          end
+        end
+      end
+    end
+    
+    context "#clear" do
+      before(:each) do
+        @tag_abc_value = @store.read_tag("abc")
+        @store.write("abc_entity", "test")
+        sleep 0.1
+        @store.clear
+      end
+      
+      it "should clear store of entities" do
+        @store.read("abc_entity").should be_nil
+      end
+      
+      it "should not touch any tags" do
+        @store.read_tag("abc").should == @tag_abc_value
+      end
+    end
+    
+    context "entity" do
+      before(:each) do
+        @store.write("abc", "test", :depends => ["tag1", "tag2"])
+      end
+      
+      it "should be read from cache when tags are untouched" do
+        @store.read("abc").should == "test"
+      end
+      
+      ["tag1", "tag2"].each do |tag_name|
+        it "should not be read from cache when '#{tag_name}' is touched" do
+          @store.touch_tag(tag_name)
+          @store.read("abc").should be_nil
+        end
+      end
+    end
+
+    context "#fetch('abc', ...)" do
+      before(:each) do
+        @depends = ["tag1", "tag2"]
+        @store.write("abc", true, :depends => @depends)
+      end
+      
+      it "should fetch value from cache when tags are untouched" do
+        @store.fetch("abc", :depends => @depends) { false }.should be_true
+      end
+      
+      ["tag1", "tag2"].each do |tag_name|
+        it "should fetch value from proc when '#{tag_name}' is touched" do
+          @store.touch_tag(tag_name)
+          @store.fetch("abc", :depends => @depends) { false }.should be_false
+        end
+      end
+    end
+
+    context "#tagged_fetch('abc', ...)" do
+      before(:each) do
+        @depends = ["tag1", "tag2"]
+        @store.tagged_fetch("abc") do |entry|
+          "value".tap do
+            entry.depends "tag1"
+            entry << "tag2"
+            entry.concat "tag1", "tag2"
+            entry.concat ["tag1", "tag2"]
+          end
+        end
+      end
+      
+      it "should fetch value from cache when tags are untouched" do
+        @store.read("abc").should == "value"
+      end
+      
+      ["tag1", "tag2"].each do |tag_name|
+        it "should fetch value from proc when '#{tag_name}' is touched" do
+          @store.touch_tag(tag_name)
+          @store.read("abc").should be_nil
+        end
+      end
+    end
+    
+    context "#touch_tag(object)" do
+      before(:each) do
+        @tag_value = @store.read_tag("tag1")
+      end
+      
+      it "should calculate tag name and increment it" do
+        obj = Object.new
+        module ObjectCacheTag
+          def cache_tag
+            "tag1"
+          end
+        end
+        obj.extend(ObjectCacheTag)
+        @store.touch_tag(obj)
+        @store.read_tag("tag1").should > @tag_value
+      end
+    end
+    
+  end
+end

metadata

@@ -0,0 +1,90 @@
+--- !ruby/object:Gem::Specification 
+name: tagged-cache
+version: !ruby/object:Gem::Version 
+  hash: 23
+  prerelease: false
+  segments: 
+  - 1
+  - 0
+  - 0
+  version: 1.0.0
+platform: ruby
+authors: 
+- Anton Ageev
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2010-10-06 00:00:00 +04:00
+default_executable: 
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: activesupport
+  prerelease: false
+  requirement: &id001 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        hash: 7
+        segments: 
+        - 3
+        - 0
+        - 0
+        version: 3.0.0
+  type: :runtime
+  version_requirements: *id001
+description: 
+email: antage@gmail.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: []
+
+files: 
+- README.rdoc
+- History.txt
+- Rakefile
+- lib/active_support/cache/tagged_store.rb
+- spec/tagged_store_spec.rb
+- spec/spec_helper.rb
+has_rdoc: true
+homepage: http://github.com/antage/tagged-cache
+licenses: []
+
+post_install_message: 
+rdoc_options: []
+
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      hash: 3
+      segments: 
+      - 0
+      version: "0"
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      hash: 23
+      segments: 
+      - 1
+      - 3
+      - 6
+      version: 1.3.6
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.3.7
+signing_key: 
+specification_version: 3
+summary: ActiveSupport cache adapter with tagged dependencies
+test_files: 
+- spec/tagged_store_spec.rb
+- spec/spec_helper.rb