lrucache 0.0.1 → 0.1.0

data/Guardfile

@@ -10,5 +10,6 @@ guard 'rspec', :cli => '-c --format documentation -r ./spec/spec_helper.rb',
                :version => 2 do
   watch(%r{^spec/.+_spec\.rb})
   watch(%r{^lib/(.+)\.rb})        { |m| "spec/lib/#{m[1]}_spec.rb" }
+  watch('lib/lrucache.rb')        { "spec/lrucache_spec.rb" }
   watch('spec/spec_helper.rb')    { "spec" }
 end

data/README.md

@@ -21,7 +21,7 @@ Example
 
 TTL (time-to-live)
 ==================
-    cache = LRUCache.new(:expires => 1.hour)
+    cache = LRUCache.new(:ttl => 1.hour)
     cache.store("banana", "yellow")
     cache.store("monkey", "banana", Time.now + 3.days)
     # or ...

data/lib/lrucache.rb

@@ -4,13 +4,14 @@ require "priority_queue"
 # Not thread-safe!
 class LRUCache
 
-  attr_reader :default, :max_size
+  attr_reader :default, :max_size, :ttl
 
   def initialize(opts={})
-    @max_size = (opts[:max_size] || 100).to_i
+    @max_size = Integer(opts[:max_size] || 100)
     @default = opts[:default]
-    @expires = (opts[:expires] || 0).to_f
-    raise "max_size must be greather than zero" unless @max_size > 0
+    @ttl = Float(opts[:ttl] || 0)
+    raise "max_size must be greater than zero" unless @max_size > 0
+    raise "ttl must be positive or zero" unless @ttl >= 0
     @pqueue = PriorityQueue.new
     @data = {}
     @counter = 0
@@ -19,6 +20,7 @@ class LRUCache
   def clear
     @data.clear
     @pqueue.delete_min until @pqueue.empty?
+    @counter = 0 #might as well
   end
 
   def include?(key)
@@ -34,38 +36,48 @@ class LRUCache
     end
   end
 
-  def store(key, value, expires=nil)
-    expire_lru! unless @data.include?(key) || @data.size < @max_size
-    expiration =
-      if expires.nil?
-        (@expires > 0) ? (Time.now + @expires) : nil
-      elsif expires.is_a?(Time)
-        expires
+  def store(key, value, ttl=nil)
+    evict_lru! unless @data.include?(key) || @data.size < @max_size
+    ttl ||= @ttl
+    expires =
+      if ttl.is_a?(Time)
+        ttl
       else
-        expires = expires.to_f
-        (expires > 0) ? (Time.now + expires) : nil
+        ttl = Float(ttl)
+        (ttl > 0) ? (Time.now + ttl) : nil
       end
-    @data[key] = [value, expiration]
+    @data[key] = [value, expires]
     access(key)
   end
 
   alias :[]= :store
 
-  def fetch(key)
+  def fetch(key, ttl=nil)
     datum = @data[key]
-    return @default if datum.nil?
-    value, expires = datum
-    if expires.nil? || expires > Time.now # no expiration, or not expired
-      access(key)
+    unless datum.nil?
+      value, expires = datum
+      if expires.nil? || expires > Time.now # no expiration, or not expired
+        access(key)
+        return value
+      else # expired
+        delete(key)
+      end
+    end
+    if block_given?
+      value = yield
+      store(key, value, ttl)
       value
-    else # expired
-      delete(key)
+    else
       @default
     end
   end
 
   alias :[] :fetch
 
+  def empty?
+    size == 0
+  end
+
   def size
     @data.size
   end
@@ -75,13 +87,13 @@ class LRUCache
   end
 
   def delete(key)
-    @data.delete(key)
     @pqueue.delete(key)
+    @data.delete(key)
   end
 
   private
 
-  def expire_lru!
+  def evict_lru!
     key, priority = @pqueue.delete_min
     @data.delete(key) unless priority.nil?
   end

data/lib/lrucache/version.rb

@@ -1,3 +1,3 @@
 class LRUCache
-  VERSION = "0.0.1"
+  VERSION = "0.1.0"
 end

data/spec/lrucache_spec.rb

@@ -1,102 +1,471 @@
 describe LRUCache do
-  it "should never exceed its max_size" do
-    c = LRUCache.new(:max_size => 7)
-    (1..100).each do |i|
-      c[i] = rand(2**16)
-      c.size.should <= 7
+  describe ".new" do
+
+    it "should default :max_size to 100" do
+      LRUCache.new.max_size.should == 100
+    end
+    it "should accept a :max_size parameter" do
+      LRUCache.new(:max_size => 7).max_size.should == 7
+    end
+    it "should raise an exception if :max_size parameter can't be converted to an integer" do
+      expect { LRUCache.new(:max_size => "moocow") }.to raise_exception
+    end
+    it "should raise an exception if :max_size parameter is converted to a negative integer" do
+      expect { LRUCache.new(:max_size => -1) }.to raise_exception
+    end
+
+    it "should default :default to nil" do
+      LRUCache.new.default.should be_nil
+    end
+    it "should accept a :default parameter" do
+      default = double(:default)
+      LRUCache.new(:default => default).default.should == default
+    end
+
+    it "should default :ttl to 0 (no expiration)" do
+      LRUCache.new.ttl.should == 0
+    end
+    it "should accept a :ttl parameter" do
+      LRUCache.new(:ttl => 98.6).ttl.should == 98.6
+    end
+    it "should raise an exception if :ttl parameter can't be converted to a float" do
+      expect { LRUCache.new(:ttl => "moocow") }.to raise_exception
+    end
+    it "should raise an exception if :ttl parameter is converted to a negative float" do
+      expect { LRUCache.new(:ttl => -1) }.to raise_exception
+    end
+
+    it "should initially be empty" do
+      LRUCache.new.should be_empty
     end
-    c.size.should == 7
   end
 
-  it "should expire the eldest entries first" do
-    c = LRUCache.new(:max_size => 3)
-    c[1] = 'a'
-    c[2] = 'b'
-    c[3] = 'c'
-    c[2].should == 'b'
-    c[1].should == 'a'
-    c[3].should == 'c'
-    c[4] = 'd' # Out of space! Throws out the least-recently used (2 => 'b').
-    c.keys.sort.should == [1,3,4]
-    c[5] = 'e'
-    c.keys.sort.should == [3,4,5]
-    c[1] = 'a'
-    c.keys.sort.should == [1,4,5]
+  describe ".clear" do
+    it "should empty the hash and the priority queue" do
+      c = LRUCache.new
+      10.times { c[rand(2**16)] = :x }
+      c.should_not be_empty
+      c.instance_variable_get(:@data).should_not be_empty
+      c.instance_variable_get(:@pqueue).should_not be_empty
+
+      c.clear
+
+      c.should be_empty
+      c.instance_variable_get(:@data).should be_empty
+      c.instance_variable_get(:@pqueue).should be_empty
+    end
   end
 
-  it "should return the default value for expired and non-existent entries" do
-    default = double(:default)
-    c = LRUCache.new(:max_size => 3, :default => default)
-    c[:a].should == default
-    c[:a] = 'a'
-    c[:a].should == 'a'
-    c[:b] = 'b'
-    c[:c] = 'c'
-    c[:d] = 'd'
-    c[:a].should == default
+  describe ".include?(key)" do
+    before(:each) { @cache = LRUCache.new }
+    context "when the key is not present" do
+      it "should return false" do
+        @cache.include?(:a).should be_false
+      end
+      it "should not affect priorities" do
+        @cache.should_not_receive(:access)
+        @cache.include?(:a)
+      end
+    end
+    context "when the key is present, but the value has expired" do
+      before(:each) do
+        now = Time.now
+        Timecop.freeze(now) { @cache.store(:a, 'a', now + 10) }
+        Timecop.freeze(now + 20)
+      end
+      after(:each) do
+        Timecop.return
+      end
+      it "should return false" do
+        @cache.include?(:a).should be_false
+      end
+      it "should delete the key" do
+        @cache.should_receive(:delete).with(:a)
+        @cache.include?(:a)
+      end
+      it "should not affect priorities" do
+        @cache.should_not_receive(:access)
+        @cache.include?(:a)
+      end
+    end
+    context "when the key is present, and the value has no expiration" do
+      before(:each) do
+        @cache.store(:a, 'a', nil)
+      end
+      it "should return true" do
+        @cache.include?(:a).should be_true
+      end
+      it "should update the key's access stamp" do
+        @cache.should_receive(:access).with(:a)
+        @cache.include?(:a)
+      end
+    end
+    context "when the key is present, and the value has not yet expired" do
+      before(:each) do
+        now = Time.now
+        Timecop.freeze(now)
+        @cache.store(:a, 'a', now + 10)
+      end
+      after(:each) do
+        Timecop.return
+      end
+      it "should return true" do
+        @cache.include?(:a).should be_true
+      end
+      it "should update the key's access stamp" do
+        @cache.should_receive(:access).with(:a)
+        @cache.include?(:a)
+      end
+    end
   end
 
-  it "should honor TTL" do
-    c = LRUCache.new(:expires => 20)
-    now = Time.now
-    Timecop.freeze(now) do
-      c.store(:a, 'a')
-      c.store(:b, 'b', now + 50)
-      c.store(:c, 'c', 50)
-      c[:a].should == 'a'
-      c[:b].should == 'b'
-      c[:c].should == 'c'
-      c.size.should == 3
-    end
-    Timecop.freeze(now + 19) do
-      c[:a].should == 'a'
-      c[:b].should == 'b'
-      c[:c].should == 'c'
-      c.size.should == 3
-    end
-    Timecop.freeze(now + 49) do
-      c[:a].should be_nil
-      c[:b].should == 'b'
-      c[:c].should == 'c'
-      c.size.should == 2
-    end
-    Timecop.freeze(now + 50) do
-      c[:a].should be_nil
-      c[:b].should be_nil
-      c[:c].should be_nil
-      c.size.should == 0
+  describe ".store(key, value, ttl=nil)" do
+    context "regarding evictions" do
+      before(:each) do
+        @cache = LRUCache.new(:max_size => 2)
+      end
+      context "when the cache is not full" do
+        context "and the key is not present" do
+          it "should not evict an entry" do
+            @cache.should_not_receive(:evict_lru!)
+            @cache.store(:a, 'a')
+          end
+          it "should store the value" do
+            @cache.store(:a, 'a')
+            @cache.fetch(:a).should == 'a'
+          end
+          it "should update the key's access stamp" do
+            @cache.should_receive(:access).with(:a)
+            @cache.store(:a, 'a')
+          end
+        end
+        context "and the key is present" do
+          it "should not evict an entry" do
+            @cache.should_not_receive(:evict_lru!)
+            @cache.store(:a, 'a')
+          end
+          it "should store the value" do
+            @cache.store(:a, 'a')
+            @cache.fetch(:a).should == 'a'
+          end
+          it "should update the key's access stamp" do
+            @cache.should_receive(:access).with(:a)
+            @cache.store(:a, 'a')
+          end
+        end
+      end
+      context "when the cache is full" do
+        before(:each) do
+          @cache = LRUCache.new(:max_size => 2)
+          @cache[:b] = 'b'
+          @cache[:c] = 'c'
+          @lru = :b
+        end
+        context "and the key is not present" do
+          it "should evict the least-recently used entry from the cache" do
+            @cache.keys.should include(@lru)
+            @cache.store(:a, 'a')
+            @cache.keys.should_not include(@lru)
+          end
+          it "should store the value" do
+            @cache.store(:a, 'a')
+            @cache.fetch(:a).should == 'a'
+          end
+          it "should update the key's access stamp" do
+            @cache.should_receive(:access).with(:a)
+            @cache.store(:a, 'a')
+          end
+        end
+        context "and the key is present" do
+          it "should not evict an entry" do
+            @cache.should_not_receive(:evict_lru!)
+            @cache.store(:c, 'c')
+          end
+          it "should store the value" do
+            @cache.store(:c, 'c')
+            @cache.fetch(:c).should == 'c'
+          end
+          it "should update the key's access stamp" do
+            @cache.should_receive(:access).with(:c)
+            @cache.store(:c, 'c')
+          end
+        end
+      end
+    end
+    context "when ttl is not given and the cache's default ttl is zero" do
+      it "should set the entry with no expiration time" do
+        c = LRUCache.new(:ttl => 0)
+        c.store(:a,'a')
+        stored = c.instance_variable_get(:@data)[:a]
+        stored.should == ['a', nil]
+      end
+    end
+    context "when ttl is not given and the cache's default ttl is greater than zero" do
+      it "should set the entry to expire that many seconds in the future" do
+        c = LRUCache.new(:ttl => 1)
+        now = Time.now
+        Timecop.freeze(now) { c.store(:a,'a') }
+        stored = c.instance_variable_get(:@data)[:a]
+        stored.last.should == now + 1
+      end
+    end
+    context "when ttl is a Time" do
+      it "should set the entry to expire at the given time" do
+        c = LRUCache.new
+        ttl = Time.now + 246
+        c.store(:a, 'a', ttl)
+        stored = c.instance_variable_get(:@data)[:a]
+        stored.last.should == ttl
+      end
+    end
+    context "when ttl can be parsed as a float" do
+      it "should set the entry to expire that many seconds in the future" do
+        c = LRUCache.new
+        now = Time.now
+        Timecop.freeze(now) { c.store(:a, 'a', "98.6") }
+        stored = c.instance_variable_get(:@data)[:a]
+        stored.last.should == now + 98.6
+      end
+    end
+    context "when ttl cannot be parsed as a float" do
+      it "should raise an exception" do
+        c = LRUCache.new
+        expect { c.store(:a, 'a', "moocow") }.to raise_exception
+      end
     end
-    c[:a].should be_nil
-    c[:b].should be_nil
-    c[:c].should be_nil
-    c.size.should == 0
   end
 
-  it "should have a default max_size of 100" do
-    LRUCache.new.max_size.should == 100
-    LRUCache.new(:max_size => 82).max_size.should == 82
+  describe ".fetch(key, ttl=nil)" do
+    context "when no block is given" do
+      context "and the key does not exist" do
+        before(:each) do
+          @default = double(:default)
+          @cache = LRUCache.new(:default => @default)
+        end
+        it "should return the default value" do
+          @cache.fetch(:a).should == @default
+        end
+        it "should not affect the priorities" do
+          @cache.should_not_receive(:access)
+          @cache.fetch(:a)
+        end
+      end
+      context "and the key has been evicted" do
+        before(:each) do
+          @cache = LRUCache.new(:max_size => 2)
+          @cache[:a] = 'a'
+          @cache[:b] = 'b'
+          @cache[:c] = 'c'
+        end
+        it "should return the default value" do
+          @cache.fetch(:a).should == @default
+        end
+        it "should not affect the priorities" do
+          @cache.should_not_receive(:access)
+          @cache.fetch(:a)
+        end
+      end
+      context "and the key has expired" do
+        before(:each) do
+          @cache = LRUCache.new(:ttl => 10)
+          now = Time.now
+          Timecop.freeze(now) { @cache[:a] = 'a' }
+          Timecop.freeze(now + 20)
+        end
+        after(:each) do
+          Timecop.return
+        end
+        it "should return the default value" do
+          @cache.fetch(:a).should == @default
+        end
+        it "should not affect the priorities" do
+          @cache.should_not_receive(:access)
+          @cache.fetch(:a)
+        end
+        it "should delete the key" do
+          @cache.should_receive(:delete).with(:a)
+          @cache.fetch(:a)
+        end
+      end
+      context "and the key is present and un-expired" do
+        before(:each) do
+          @cache = LRUCache.new(:ttl => nil)
+          @cache[:a] = 'a'
+        end
+        it "should return the cached value" do
+          @cache.fetch(:a).should == 'a'
+        end
+        it "should update the key's access stamp" do
+          @cache.should_receive(:access).with(:a)
+          @cache.fetch(:a)
+        end
+      end
+    end
+    context "when a block is given" do
+      context "when the key does not exist" do
+        it "should call the block and store and return the result" do
+          c = LRUCache.new
+          ttl = double(:ttl)
+          result = double(:result)
+          c.should_receive(:store).with(:a, result, ttl)
+          c.fetch(:a, ttl){ result }.should == result
+        end
+      end
+      context "when the key has been evicted" do
+        it "should call the block and store and return the result" do
+          c = LRUCache.new
+          c[:a] = 'a'
+          c.send(:evict_lru!)
+          ttl = double(:ttl)
+          result = double(:result)
+          c.should_receive(:store).with(:a, result, ttl)
+          c.fetch(:a, ttl){ result }.should == result
+        end
+      end
+      context "when the key has expired" do
+        it "should call the block and store and return the result" do
+          c = LRUCache.new
+          now = Time.now
+          Timecop.freeze(now) { c.store(:a, 'a', now + 10) }
+          Timecop.freeze(now + 20) do
+            ttl = double(:ttl)
+            result = double(:result)
+            c.should_receive(:store).with(:a, result, ttl)
+            c.fetch(:a, ttl){ result }.should == result
+          end
+        end
+      end
+      context "when the key is present and un-expired" do
+        it "should return the cached value without calling the block" do
+          c = LRUCache.new(:ttl => nil)
+          c[:a] = 'a'
+          c.fetch(:a) { raise 'fail' }.should == 'a'
+        end
+      end
+    end
   end
 
-  it "can be cleared" do
-    c = LRUCache.new
-    (1..100).each {|i| c[i] = rand(2**16)}
-    c.size.should == 100
-    c.clear
-    c.size.should == 0
-    c.keys.should == []
+  describe ".empty?" do
+    it "should return true if and only if size is zero" do
+      c = LRUCache.new
+      c.empty?.should be_true
+      c[:a] = 'a'
+      c.empty?.should be_false
+      c.clear
+      c.empty?.should be_true
+    end
   end
 
-  describe ".include?(key)" do
-    it "affects the access time of the key" do
-      c = LRUCache.new(:max_size => 3)
+  describe ".size and .keys" do
+    it "should return a count / list of entries in the cache" do
+      c = LRUCache.new(:max_size => 10)
+      (1..10).each do |i|
+        c.size.should == i-1
+        c[i] = :x
+        c.size.should == i
+        c.keys.sort.should == (1..i).to_a
+      end
+      (1..3).each do |i|
+        c.delete(i)
+        c.size.should == 10 - i
+        c.keys.sort.should == ((i+1)..10).to_a
+      end
+      (1..3).each do |i|
+        c[i] = :x
+        c.size.should == 7+i
+        c.keys.sort.should == (1..i).to_a + (4..10).to_a
+      end
+      (1..10).each do |i|
+        c[i] = :x
+        c.size.should == 10
+        c.keys.sort.should == (1..10).to_a
+      end
+      c.clear
+      c.size.should == 0
+      c.keys.should == []
+    end
+    it "may include expired entries" do
+      c = LRUCache.new(:ttl => 10, :max_size => 100)
+      now = Time.now
+      (0..19).each do |i|
+        Timecop.freeze(now + i) do
+          c[i] = :x
+          c.size.should == i+1
+          c.keys.sort.should == (0..i).to_a
+        end
+      end
+      Timecop.freeze(now + 20) do
+        c.size.should == 20
+        (0..19).each do |i|
+          c.include?(i)
+        end
+        c.size.should == 9
+        c.keys.sort.should == (11..19).to_a
+      end
+    end
+    it "should always return a value less than or equal to the cache's max_size" do
+      c = LRUCache.new(:max_size => 7)
+      (1..100).each do |i|
+        c[i] = :x
+        c.size.should <= 7
+      end
+    end
+  end
+
+
+  describe ".delete(key)" do
+    it "should remove the key from the internal hash and priority queue" do
+      c = LRUCache.new
+      c[:a] = 'a'
+      c.instance_variable_get(:@data).should include(:a)
+      c.instance_variable_get(:@pqueue).should include([:a,1])
+      c.delete(:a)
+      c.instance_variable_get(:@data).should_not include(:a)
+      c.instance_variable_get(:@pqueue).should_not include([:a,1])
+    end
+  end
+
+  describe ".evict_lru!" do
+    it "should find the least-recently used entry, and delete it" do
+      c = LRUCache.new
       c[1] = 'a'
       c[2] = 'b'
       c[3] = 'c'
-      c.include?(1).should be_true
       c[4] = 'd'
-      c[5] = 'e'
-      c.include?(1).should be_true
-      c.include?(2).should be_false
+      c[:dne1].should be_nil # Doesn't affect LRU.
+      c[2].should == 'b'
+      c[1].should == 'a'
+      c[3].should == 'c'
+      c[4].should == 'd'
+      c[:dne2].should be_nil # Doesn't affect LRU.
+      c.keys.sort.should == [1,2,3,4]
+      c.send(:evict_lru!)
+      c.keys.sort.should == [1,3,4]
+      c.send(:evict_lru!)
+      c.keys.sort.should == [3,4]
+      c.send(:evict_lru!)
+      c.keys.sort.should == [4]
+      c.send(:evict_lru!)
+      c.keys.should == []
+      c.send(:evict_lru!)
+      c.keys.should == []
+    end
+    it "should leave the internal hash the same size as the priority queue" do
+      c = LRUCache.new
+      expected_size = 0
+      counter = 0
+      100.times do
+        if rand < 0.8
+          c[counter += 1] = :x
+          expected_size += 1
+        else
+          c.send(:evict_lru!)
+          expected_size -= 1
+        end
+        expected_size = [expected_size,0].max
+        c.instance_variable_get(:@data).size.should == expected_size
+        c.instance_variable_get(:@pqueue).count.should == expected_size
+      end
     end
   end
 end

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification 
 name: lrucache
 version: !ruby/object:Gem::Version 
-  hash: 29
+  hash: 27
   prerelease: 
   segments: 
   - 0
-  - 0
   - 1
-  version: 0.0.1
+  - 0
+  version: 0.1.0
 platform: ruby
 authors: 
 - Chris Johnson