timeout_cache 0.0.1 → 0.0.2

data/README.md

@@ -2,6 +2,10 @@
 
 A `TimeoutCache` is a simple cache where objects are stored with a fixed expiration time. It is useful when you want to keep an object around for a sufficiently long period of time, but want them to disappear after, say, 5 seconds, or on the first day of next month.
 
+```
+gem install timeout_cache
+```
+
 # How do I use this thing?
 
 A `TimeoutCache` is easy to use.
@@ -31,6 +35,8 @@ You can also use an instance of `Time`:
 cache.set(:x, :y, :time => Time.now + 50)
 ```
 
+You can use any object as the value for `:time` provided it is an `Integer`, a `Time`, has a `to_int` method, or has a `to_time` method.
+
 If you want to change the default expiration time, do so when you make a new instance of `TimeoutCache` by passing the length of time in seconds.
 
 ```ruby
@@ -41,7 +47,11 @@ Unless an object is added to the cache using the `:time` option, the default is
 
 # Entry deletion and pruning
 
-Expired entries are deleted lazily. If an entry is added with an expire time of 15 seconds and nothing touches the cache, the entry will still be in the cache after 20 seconds. Expired entries are deleted only when a call to `#[]` (or, equivalently, `#get`) finds an expired entry. At that point, `#prune` is called.
+Expired entries are deleted lazily to try and avoid to cost of excessively pruning. If an entry is added with an expire time of 15 seconds and nothing touches the cache, the entry will still be in the cache after 20 seconds. Expired entries are deleted when certain methods are called:
+
+* `#[]` (or, equivalently, `#get`) provided that the entry being retrieved has expired
+* `#size`
+* `#empty?`
 
 If you want to manually prune the cache, you may do so by calling `#prune`.
 

data/lib/timeout_cache.rb

@@ -13,7 +13,7 @@
 #     cache[:foo] #=> nil
 #
 class TimeoutCache
-  VERSION = "0.0.1"
+  VERSION = "0.0.2"
   
   # Wraps an object by attaching a time to it.
   class TimedObject # :nodoc:
@@ -38,12 +38,15 @@ class TimeoutCache
   
   # Creates a new TimeoutCache.
   #
-  # If <tt>timeout</tt> is specified, the default survival time for
-  # a cache entry is <tt>timeout</tt> in seconds.
+  # If <tt>timeout</tt> is specified, #to_int is called on the argument,
+  # and the return value is used as the default survival time for
+  # a cache entry in seconds.
   #
   # If no default value is used, then DEFAULT_TIMEOUT is the default
   # time-to-expire in seconds.
   def initialize(timeout = DEFAULT_TIMEOUT)
+    timeout = timeout.to_int if timeout.respond_to?(:to_int)
+    
     raise ArgumentError.new("Timeout must be > 0") unless timeout > 0
     
     @timeout = timeout
@@ -52,8 +55,9 @@ class TimeoutCache
     @store = {}
   end
   
-  # Returns the number of items in the cache.
+  # Calls #prune and then returns the number of items in the cache.
   def size
+    prune
     @store.size
   end
   alias_method :length, :size
@@ -62,8 +66,7 @@ class TimeoutCache
   # then this returns nil. If the value has an expire time earlier than or equal
   # to the current time, this returns nil.
   #
-  # As an implementation detail, this method calls #prune whenever it finds
-  # an element that has expired.
+  # This method calls #prune whenever it finds an element that has expired.
   def [](key)
     val = @store[key]
     
@@ -103,13 +106,27 @@ class TimeoutCache
   def set(key, value, options = {})
     time = options[:time] || timeout
     
+    # we can technically do away with checking against Integer explicitly since
+    # the to_int call will take care of it for us through Integer#to_int returning
+    # self, but it's here for the sake of clarity, mostly.
+    #
+    # on the other hand, the #to_time call is necessary, since, for some reason,
+    # Time#to_time only exists if you require "time".
     time = case time
            when Integer
              Time.now + time
            when Time
              time
+           else
+             if time.respond_to?(:to_int)
+               Time.now + time.to_int
+             elsif time.respond_to?(:to_time)
+               time.to_time
+             end
            end
     
+    raise(ArgumentError, "time argument #{time.inspect} could not be converted to a time") if time.nil?
+    
     return nil if time <= Time.now
     
     v = TimedObject.new(value, time)
@@ -118,8 +135,9 @@ class TimeoutCache
     value
   end
   
-  # Returns true if the cache is empty, otherwise false.
+  # Calls #prune and then returns true if the cache is empty, otherwise false.
   def empty?
+    prune
     @store.empty?
   end
   
@@ -136,7 +154,7 @@ class TimeoutCache
   # If nothing was removed, returns nil, otherwise returns
   # the number of elements removed.
   def prune
-    return nil if empty?
+    return nil if @store.empty?
     
     count = 0
     

data/lib/timeout_cache.rb~

@@ -16,7 +16,7 @@ class TimeoutCache
   VERSION = "0.0.1"
   
   # Wraps an object by attaching a time to it.
-  class TimedObject #:nodoc:
+  class TimedObject # :nodoc:
     attr_reader :value, :expires_at
     
     def initialize(value, time)
@@ -38,12 +38,15 @@ class TimeoutCache
   
   # Creates a new TimeoutCache.
   #
-  # If <tt>timeout</tt> is specified, the default survival time for
-  # a cache entry is <tt>timeout</tt> in seconds.
+  # If <tt>timeout</tt> is specified, #to_int is called on the argument,
+  # and the return value is used as the default survival time for
+  # a cache entry in seconds.
   #
   # If no default value is used, then DEFAULT_TIMEOUT is the default
   # time-to-expire in seconds.
   def initialize(timeout = DEFAULT_TIMEOUT)
+    timeout = timeout.to_int if timeout.respond_to?(:to_int)
+    
     raise ArgumentError.new("Timeout must be > 0") unless timeout > 0
     
     @timeout = timeout
@@ -52,8 +55,9 @@ class TimeoutCache
     @store = {}
   end
   
-  # Returns the number of items in the cache.
+  # Calls #prune and then returns the number of items in the cache.
   def size
+    prune
     @store.size
   end
   alias_method :length, :size
@@ -62,8 +66,7 @@ class TimeoutCache
   # then this returns nil. If the value has an expire time earlier than or equal
   # to the current time, this returns nil.
   #
-  # As an implementation detail, this method calls #prune whenever it finds
-  # an element that has expired.
+  # This method calls #prune whenever it finds an element that has expired.
   def [](key)
     val = @store[key]
     
@@ -103,13 +106,27 @@ class TimeoutCache
   def set(key, value, options = {})
     time = options[:time] || timeout
     
+    # we can technically do away with checking against Integer explicitly since
+    # the to_int call will take care of it for us through Integer#to_int returning
+    # self, but it's here for the sake of clarity, mostly.
+    #
+    # on the other hand, the #to_time call is necessary, since, for some reason,
+    # Time#to_time only exists if you require "time".
     time = case time
            when Integer
              Time.now + time
            when Time
              time
+           else
+             if time.respond_to?(:to_int)
+               Time.now + time.to_int
+             elsif time.respond_to?(:to_time)
+               time.to_time
+             end
            end
     
+    raise(ArgumentError, "time argument #{time.inspect} could not be converted to a time") if time.nil?
+    
     return nil if time <= Time.now
     
     v = TimedObject.new(value, time)
@@ -118,8 +135,9 @@ class TimeoutCache
     value
   end
   
-  # Returns true if the cache is empty, otherwise false.
+  # Calls #prune and then returns true if the cache is empty, otherwise false.
   def empty?
+    prune
     @store.empty?
   end
   
@@ -136,7 +154,7 @@ class TimeoutCache
   # If nothing was removed, returns nil, otherwise returns
   # the number of elements removed.
   def prune
-    return nil if empty?
+    return nil if @store.empty?
     
     count = 0
     

data/rakefile

@@ -6,7 +6,7 @@ $:.unshift(File.expand_path("lib", __FILE__))
 require "timeout_cache"
 
 RSpec::Core::RakeTask.new(:test) do |t|
-  t.rspec_opts = "-I test --color --format nested"
+  t.rspec_opts = "-I test --color"
   t.pattern = "test/**/*_spec.rb"
   t.verbose = false
   t.fail_on_error = true
@@ -23,4 +23,13 @@ Rake::RDocTask.new(:docs) do |rd|
   rd.rdoc_files.include("README.md", "lib")
 end
 
+namespace :gem do
+  desc "Build the gem from the .gemspec"
+  task :build do
+    sh("gem build timeout_cache.gemspec")
+    puts
+    puts "You can push with gem push <built-gem>.gem"
+  end
+end
+
 task :default => :test

data/test/timeout_cache_spec.rb

@@ -1,7 +1,18 @@
 require "timeout_cache"
 require "rspec"
+require "timecop"
 
 describe TimeoutCache do
+  def sleep(n)
+    Timecop.travel(Time.now + n)
+  end
+  
+  after :all do
+    # If we don't return, the runtime for the tests makes it seem like
+    # we had actually slept!
+    Timecop.return
+  end
+
   it "uses the global default timeout with no time specified" do
     subject.timeout.should == TimeoutCache::DEFAULT_TIMEOUT
   end
@@ -10,6 +21,17 @@ describe TimeoutCache do
     TimeoutCache.new(50).timeout.should == 50
   end
   
+  it "can be instantiated with anything that responds to to_int" do
+    x = double("")
+    x.should_receive(:to_int).and_return(2)
+    
+    c = TimeoutCache.new(x)
+    c[:a] = :b
+    c[:a].should == :b
+    sleep 3
+    c[:a].should be_nil
+  end
+  
   it "cannot be instantiated with a global timeout <= 0" do
     [0, -1, -5].each do |i|
       expect { TimeoutCache.new(i) }.to raise_error(ArgumentError)
@@ -30,6 +52,32 @@ describe TimeoutCache do
       subject.expire_time(:a).should == t
     end
     
+    context "if the :time value is neither a Time nor an Integer" do
+      it "accepts any object which responds to #to_time" do
+        s = double("")
+        s.should_receive(:to_time).and_return(Time.now + 2)
+        
+        subject.set(:a, 5, :time => s)
+        subject[:a].should_not be_nil
+        sleep 3
+        subject[:a].should be_nil
+      end
+      
+      it "accepts any object which responds to #to_int" do
+        s = double("")
+        s.should_receive(:to_int).any_number_of_times.and_return(2)
+        
+        subject.set(:a, 5, :time => s)
+        subject[:a].should_not be_nil
+        sleep(s.to_int + 1)
+        subject[:a].should be_nil
+      end
+      
+      it "throws ArgumentError if it can't get a time out of it" do
+        expect { subject.set(:a, :b, :time => "not a time") }.to raise_error(ArgumentError)
+      end
+    end
+    
     # here be dragons. if it takes too long to execute these
     # commands, the times won't match, so this test isn't deterministic
     it "sets a default timeout time with no time value specified" do
@@ -116,6 +164,12 @@ describe TimeoutCache do
         subject[:a] = 1
         subject.size.should_not == 0
     end
+    
+    it "ignores expired entries" do
+      subject.set(:a, :b, :time => 1)
+      sleep 2
+      subject.size.should == 0
+    end
   end
   
   describe "pruning" do
@@ -123,18 +177,26 @@ describe TimeoutCache do
       subject.set(:a, 1, :time => 2)
       subject.set(:b, 1, :time => 2)
       sleep 3
-      subject.size.should == 2
+      subject.should_receive(:prune)
       subject.get(:a)
-      subject.size.should == 0
     end
 
     it "does not happen when calling #get(key) when get(key) is not expired" do
       subject.set(:a, 1, :time => 200)
       subject.set(:b, 1, :time => 2)
       sleep 3
-      subject.size.should == 2
+      subject.should_not_receive(:prune)
       subject.get(:a)
-      subject.size.should == 2
+    end
+    
+    it "happens on #size call" do
+      subject.should_receive(:prune)
+      subject.size
+    end
+    
+    it "happens on an #empty? call" do
+      subject.should_receive(:prune)
+      subject.empty?
     end
   end
   

data/test/timeout_cache_spec.rb~

@@ -1,7 +1,16 @@
 require "timeout_cache"
 require "rspec"
+require "timecop"
 
 describe TimeoutCache do
+  def sleep(n)
+    Timecop.travel(Time.now + n)
+  end
+  
+  after :all do
+    Timecop.return
+  end
+
   it "uses the global default timeout with no time specified" do
     subject.timeout.should == TimeoutCache::DEFAULT_TIMEOUT
   end
@@ -10,6 +19,17 @@ describe TimeoutCache do
     TimeoutCache.new(50).timeout.should == 50
   end
   
+  it "can be instantiated with anything that responds to to_int" do
+    x = double("")
+    x.should_receive(:to_int).and_return(2)
+    
+    c = TimeoutCache.new(x)
+    c[:a] = :b
+    c[:a].should == :b
+    sleep 3
+    c[:a].should be_nil
+  end
+  
   it "cannot be instantiated with a global timeout <= 0" do
     [0, -1, -5].each do |i|
       expect { TimeoutCache.new(i) }.to raise_error(ArgumentError)
@@ -30,6 +50,32 @@ describe TimeoutCache do
       subject.expire_time(:a).should == t
     end
     
+    context "if the :time value is neither a Time nor an Integer" do
+      it "accepts any object which responds to #to_time" do
+        s = double("")
+        s.should_receive(:to_time).and_return(Time.now + 2)
+        
+        subject.set(:a, 5, :time => s)
+        subject[:a].should_not be_nil
+        sleep 3
+        subject[:a].should be_nil
+      end
+      
+      it "accepts any object which responds to #to_int" do
+        s = double("")
+        s.should_receive(:to_int).any_number_of_times.and_return(2)
+        
+        subject.set(:a, 5, :time => s)
+        subject[:a].should_not be_nil
+        sleep(s.to_int + 1)
+        subject[:a].should be_nil
+      end
+      
+      it "throws ArgumentError if it can't get a time out of it" do
+        expect { subject.set(:a, :b, :time => "not a time") }.to raise_error(ArgumentError)
+      end
+    end
+    
     # here be dragons. if it takes too long to execute these
     # commands, the times won't match, so this test isn't deterministic
     it "sets a default timeout time with no time value specified" do
@@ -86,6 +132,10 @@ describe TimeoutCache do
     
     it "returns nil if nothing was deleted" do
       subject[:no_such_key].should be_nil
+      
+      subject[0] = 1
+      subject.delete(0)
+      subject.delete(0).should be_nil
     end
     
     it "returns the value deleted if the key is deleted" do
@@ -112,6 +162,12 @@ describe TimeoutCache do
         subject[:a] = 1
         subject.size.should_not == 0
     end
+    
+    it "ignores expired entries" do
+      subject.set(:a, :b, :time => 1)
+      sleep 2
+      subject.size.should == 0
+    end
   end
   
   describe "pruning" do
@@ -119,18 +175,26 @@ describe TimeoutCache do
       subject.set(:a, 1, :time => 2)
       subject.set(:b, 1, :time => 2)
       sleep 3
-      subject.size.should == 2
+      subject.should_receive(:prune)
       subject.get(:a)
-      subject.size.should == 0
     end
 
     it "does not happen when calling #get(key) when get(key) is not expired" do
       subject.set(:a, 1, :time => 200)
       subject.set(:b, 1, :time => 2)
       sleep 3
-      subject.size.should == 2
+      subject.should_not_receive(:prune)
       subject.get(:a)
-      subject.size.should == 2
+    end
+    
+    it "happens on #size call" do
+      subject.should_receive(:prune)
+      subject.size
+    end
+    
+    it "happens on an #empty? call" do
+      subject.should_receive(:prune)
+      subject.empty?
     end
   end
   

data/timeout_cache.gemspec

@@ -16,4 +16,5 @@ Gem::Specification.new do |s|
   s.test_files   = Dir["test/*"]
   s.add_development_dependency "rake"
   s.add_development_dependency "rspec"
+  s.add_development_dependency "timecop"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: timeout_cache
 version: !ruby/object:Gem::Version
-  version: 0.0.1
+  version: 0.0.2
   prerelease: 
 platform: ruby
 authors:
@@ -43,6 +43,22 @@ dependencies:
     - - ! '>='
       - !ruby/object:Gem::Version
         version: '0'
+- !ruby/object:Gem::Dependency
+  name: timecop
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
 description: Simple time-based cache.
 email:
 - adam@aprescott.com
@@ -72,12 +88,18 @@ required_ruby_version: !ruby/object:Gem::Requirement
   - - ! '>='
     - !ruby/object:Gem::Version
       version: '0'
+      segments:
+      - 0
+      hash: -1494641401151669738
 required_rubygems_version: !ruby/object:Gem::Requirement
   none: false
   requirements:
   - - ! '>='
     - !ruby/object:Gem::Version
       version: '0'
+      segments:
+      - 0
+      hash: -1494641401151669738
 requirements: []
 rubyforge_project: 
 rubygems_version: 1.8.24