caches 0.0.3 → 0.0.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 5b755f8f05416c7bd3e24c8ba950f77ac2daea8c
-  data.tar.gz: a698c0d6cfeaf897adef53e6f13b028e2531ce1d
+  metadata.gz: 89ecbca50c8eeca4f3a3ba844fc8af31051e0aca
+  data.tar.gz: 7bb00ffe94dd6f21767037d14217223e7f4bad86
 SHA512:
-  metadata.gz: 639943fc289cfe0bb9e78c52671ca55f6908b2ec282da95222b60303a15138f3274b18ce8627de05a22f0d233d31430dc5196df3d8b475917dfe8b23a7b56cc4
-  data.tar.gz: 890232456a3682cb1883332c317cc0cfb68868801ef468f17faa7f0e4d130dec53590e61820e42176506210fa4e6e5397c38349c47834d35c662efdd396d5d76
+  metadata.gz: afa402ae0b268873414fbd05f13a9c1d15982272523ab3e70d6badd37b6d05d03bf5054e774e1f17cfee93317460839018766fd76b7d8eb286b118821acfaadd
+  data.tar.gz: 36e84e288dc638a1c0b184136965fba84b737d243d81f334a0feddd356c95d3fb16631336bed1b0770ed76e29635e5d34390418ffa57fa7846083b1b4c6c594c

data/CHANGELOG.md

@@ -1,11 +1,14 @@
 # Change Log
 All notable changes to this project will be documented in this file.
 
-## Unreleased
+## 0.0.4 - 2015-03-03
 
 ### Added
 
-Nothing
+- `Caches::TTL` supports `#delete(key)`
+- Added a CONTRIBUTING guide
+- Benchmarking with Ruby 2.1.3
+- `Caches::LRU` can handle `max_keys: 0`
 
 ### Changed
 Nothing
@@ -15,4 +18,4 @@ Nothing
 
 ## 0.0.3 - 2014-08-22
 
-Currently have Caches::TTL and Caches::LRU
+Currently have `Caches::TTL` and `Caches::LRU`

data/CONTRIBUTING.md

@@ -0,0 +1,11 @@
+# Contributing
+
+The goal of this gem is to provide a small collection of useful, performant caches.
+
+- To add a new kind of cache, you must convince us that it's useful
+- To change a cache, you must
+  - convince us that it's a useful change
+  - ensure that it's well-tested
+  - ensure that it's benchmarked and performant
+
+`rake` runs the specs and `rake benchmark` runs the benchmarks (still in-progress). They are expected to pass on Ruby 2.1.3

data/README.md

@@ -49,7 +49,7 @@ h.memoize(:a) { |k| calculation_for(k) }
 
 ### Caches::LRU
 
-LRU (Least Recently Used) remembers as many keys as you tell it to, dropping the least recently used key on each insert after its limit is reached.
+LRU (Least Recently Used) remembers as many keys as you tell it to, dropping the least recently used key on each insert after its limit is reached. (Inserts and reads count as a usage; updates do not.)
 
 ```ruby
 require 'caches/lru'
@@ -77,11 +77,7 @@ Or install it yourself as:
 
 ## Contributing
 
-1. Fork it
-2. Create your feature branch (`git checkout -b my-new-feature`)
-3. Commit your changes (`git commit -am 'Add some feature'`)
-4. Push to the branch (`git push origin my-new-feature`)
-5. Create new Pull Request
+See CONTRIBUTING.md
 
 # Thanks
 

data/Rakefile

@@ -1,11 +1,18 @@
 require "bundler/gem_tasks"
 require 'rspec/core/rake_task'
 
+task :default => :spec
+
 desc "Run the specs in documentation format"
 RSpec::Core::RakeTask.new(:spec) do |t|
   t.rspec_opts = '--format documentation'
 end
 
+desc "Run the benchmarks"
+RSpec::Core::RakeTask.new(:benchmark) do |t|
+  t.rspec_opts = '--format documentation --tag benchmark'
+end
+
 task :console do
   require 'irb'
   require 'irb/completion'

data/caches.gemspec

@@ -22,4 +22,5 @@ Gem::Specification.new do |spec|
   spec.add_development_dependency "rake"
   spec.add_development_dependency "rspec",   "~> 2.14"
 
+  spec.add_development_dependency "benchmark-ips",  "~> 2.0"
 end

data/lib/caches/lru.rb

@@ -13,6 +13,7 @@ module Caches
     end
 
     def [](key)
+      return nil if max_keys.zero?
       return nil unless data.has_key?(key)
       value, node = data[key]
       keys.move_to_head(node)
@@ -20,6 +21,7 @@ module Caches
     end
 
     def []=(key, val)
+      return nil if max_keys.zero?
       if data.has_key?(key)
         data[key][0] = val
       else

data/lib/caches/ttl.rb

@@ -1,5 +1,6 @@
 require 'time'
 require_relative 'accessible'
+require_relative 'linked_list'
 
 module Caches
   class TTL
@@ -16,13 +17,12 @@ module Caches
 
     def [](key)
       return nil unless data.has_key?(key)
-      if current?(key) 
-        data[key][:time] = current_time if refresh
-        data[key][:value]
+      if current?(key)
+        data[key][:value].tap {
+          data[key][:time] = current_time if refresh
+        }
       else
-        node = data[key][:node]
-        nodes.delete(node)
-        data.delete(key)
+        delete(key)
         nil
       end
     end
@@ -41,8 +41,15 @@ module Caches
       data[key] = {time: current_time, value: val, node: node}
     end
 
+    def delete(key)
+      node = data[key][:node]
+      nodes.delete(node)
+      hash = data.delete(key)
+      hash.fetch(:value)
+    end
+
     def size
-      keys.length
+      nodes.length
     end
 
     def keys

data/lib/caches/version.rb

@@ -1,3 +1,3 @@
 module Caches
-  VERSION = "0.0.3"
+  VERSION = "0.0.4"
 end

data/spec/benchmark_spec.rb

@@ -0,0 +1,92 @@
+require 'spec_helper'
+require 'benchmark/ips'
+require_relative '../lib/caches/all'
+require 'stringio'
+
+describe "benchmarks", benchmark: true do
+
+  # Comment to unmute the output from Benchmark
+  before(:all) { $stdout = StringIO.new }
+  after(:all)  { $stdout = STDOUT }
+
+  let(:klass) { described_class }
+
+  # These are both somewhat arbitrary and may depend on Ruby version
+  # Tested with Ruby 2.1.3
+  let(:reasonable_ratio) { 1.1 }
+  let(:reasonable_percent_variation) { 30 }
+
+  describe Caches::TTL do
+
+    let!(:small_range) { (1..10) }
+    let!(:small_cache) {
+      klass.new.tap { |sc| small_range.each {|key| sc[key] = key } }
+    }
+    let(:big_range) { (1..1_000_000) }
+    let(:big_cache) {
+      klass.new.tap { |sc| big_range.each {|key| sc[key] = key } }
+    }
+
+    let(:very_big_range) { 1..10_000_000 }
+    let(:very_big_cache) {
+      klass.new.tap { |sc| very_big_range.each { |key| sc[key] = key } }
+    }
+
+    it "has constant time reads" do
+      big_cache[1] # force creation
+      results = {}
+      report = Benchmark.ips do |x|
+        small_cache_test_keys = small_range.to_a.shuffle.cycle
+        big_cache_test_keys   = big_range.to_a.shuffle.cycle
+        results[:small] = x.report("reading from small cache") {
+          small_cache[small_cache_test_keys.next]
+        }
+        results[:big]   = x.report("reading from big cache") {
+          big_cache[big_cache_test_keys.next]
+        }
+      end
+      small_ips = report.entries.first.ips
+      big_ips   = report.entries.last.ips
+      expect(big_ips).to be < (small_ips * reasonable_ratio)
+    end
+
+    it "has constant time inserts" do
+      write_keys = (1..10_000_000).to_a.shuffle.cycle
+      report = Benchmark.ips do |x|
+        x.report("inserts") { small_cache[write_keys.next] = :a }
+      end
+      rand_report = report.entries.first
+
+      variance = rand_report.stddev_percentage
+      expect(variance).to be < reasonable_percent_variation
+    end
+
+    it "has constant time updates" do
+      write_keys = small_range.to_a.cycle
+      report = Benchmark.ips do |x|
+        x.report("updates") { small_cache[write_keys.next] = :a }
+      end
+      rand_report = report.entries.first
+
+      variance = rand_report.stddev_percentage
+      expect(variance).to be < reasonable_percent_variation
+    end
+
+    # Using a very big cache here in hopes that, even though IPS does as many
+    # deletes as it possibly can during its runtime, it won't finish deleting
+    # all the cache keys before it finishes
+    it "has constant time deletes" do
+      delete_keys = very_big_range.to_a.each
+      very_big_cache[1] # force creation
+      report = Benchmark.ips do |x|
+        x.report("deletes") { very_big_cache.delete(delete_keys.next) }
+      end
+      rand_report = report.entries.first
+
+      variance = rand_report.stddev_percentage
+      expect(variance).to be < reasonable_percent_variation
+    end
+
+  end
+
+end

data/spec/caches/lru_spec.rb

@@ -62,7 +62,8 @@ describe Caches::LRU do
 
       it "does not calculate the value" do
         expect(greeting).not_to receive(:upcase)
-        cache.memoize(:c) { greeting.upcase }
+        val = cache.memoize(:c) { greeting.upcase }
+        expect(val).to eq("Caspian")
       end
 
     end
@@ -72,8 +73,9 @@ describe Caches::LRU do
       let(:key) { :nonexistent }
 
       it "calculates the value" do
-        expect(greeting).to receive(:upcase)
-        cache.memoize(:nonexistent) { greeting.upcase }
+        expect(greeting).to receive(:upcase).and_call_original
+        val = cache.memoize(:nonexistent) { greeting.upcase }
+        expect(val).to eq("HI")
       end
 
       it "sets the value" do
@@ -104,5 +106,22 @@ describe Caches::LRU do
 
   end
 
+  describe "when max_keys is 0" do
+
+    let(:options) { {max_keys: 0} }
+    let(:greeting) { 'hi' }
+
+    it "doesn't store anything" do
+      expect(cache[:a]).to eq(nil)
+    end
+
+    it "always runs a memoize block" do
+      expect(greeting).to receive(:upcase).and_call_original
+      val = cache.memoize(:a) { greeting.upcase }
+      expect(val).to eq("HI")
+    end
+
+  end
+
 end
 

data/spec/caches/ttl_spec.rb

@@ -7,7 +7,7 @@ describe Caches::TTL do
   let(:ttl)         { 0.01 }
   let(:most_of_ttl) { ttl * 0.8 }
   let(:options)     { { ttl: ttl} }
-  let(:cache)   {
+  let!(:cache)   {
     described_class.new(options).tap {|c|
       c[:a] = 'Aravis'
       c[:b] = 'Bern'
@@ -19,24 +19,36 @@ describe Caches::TTL do
     expect(cache.size).to eq(3)
   end
 
-  it "remembers cached values before the TTL expires" do
-    expect(cache[:c]).to eq('Caspian')
+  it "can delete keys" do
+    expect(cache.keys).to eq(%i[a b c])
     expect(cache.size).to eq(3)
     # testing private method
     expect(cache.send(:nodes).length).to eq(3)
-  end
 
-  it "forgets cached values when a read is attempted after the TTL expires" do
-    expect(cache[:c]).to eq('Caspian')
-    sleep(ttl)
-    expect(cache[:c]).to be_nil
+    deleted = cache.delete(:b)
+    expect(deleted).to eq('Bern')
+
+    expect(cache.keys).to eq(%i[a c])
     expect(cache.size).to eq(2)
     # testing private method
     expect(cache.send(:nodes).length).to eq(2)
+  end
+
+  it "remembers cached values before the TTL expires" do
+    expect(cache).not_to receive(:delete)
+    expect(cache[:c]).to eq('Caspian')
+    expect(cache.size).to eq(3)
+  end
+
+  it "forgets cached values when a read is attempted after the TTL expires" do
+    sleep(ttl)
+    expect(cache).to receive(:delete).with(:a).and_call_original
     expect(cache[:a]).to be_nil
+    expect(cache.size).to eq(2)
+
+    expect(cache).to receive(:delete).with(:c).and_call_original
+    expect(cache[:c]).to be_nil
     expect(cache.size).to eq(1)
-    # testing private method
-    expect(cache.send(:nodes).length).to eq(1)
   end
 
   describe "listing keys and values" do

data/spec/spec_helper.rb

@@ -3,4 +3,5 @@ require 'bundler/setup'
 
 RSpec.configure do |config|
   config.order = :random
+  config.filter_run_excluding benchmark: true
 end

metadata

@@ -1,57 +1,71 @@
 --- !ruby/object:Gem::Specification
 name: caches
 version: !ruby/object:Gem::Version
-  version: 0.0.3
+  version: 0.0.4
 platform: ruby
 authors:
 - Nathan Long
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2014-09-22 00:00:00.000000000 Z
+date: 2015-03-03 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - ~>
+    - - "~>"
       - !ruby/object:Gem::Version
         version: '1.3'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - ~>
+    - - "~>"
       - !ruby/object:Gem::Version
         version: '1.3'
 - !ruby/object:Gem::Dependency
   name: rake
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - '>='
+    - - ">="
       - !ruby/object:Gem::Version
         version: '0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - '>='
+    - - ">="
       - !ruby/object:Gem::Version
         version: '0'
 - !ruby/object:Gem::Dependency
   name: rspec
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - ~>
+    - - "~>"
       - !ruby/object:Gem::Version
         version: '2.14'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - ~>
+    - - "~>"
       - !ruby/object:Gem::Version
         version: '2.14'
+- !ruby/object:Gem::Dependency
+  name: benchmark-ips
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
 description: A small collection of caches with good performance and hash-like access
   patterns
 email:
@@ -60,8 +74,9 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
-- .gitignore
+- ".gitignore"
 - CHANGELOG.md
+- CONTRIBUTING.md
 - Gemfile
 - LICENSE.txt
 - README.md
@@ -75,6 +90,7 @@ files:
 - lib/caches/lru.rb
 - lib/caches/ttl.rb
 - lib/caches/version.rb
+- spec/benchmark_spec.rb
 - spec/caches/linked_list_spec.rb
 - spec/caches/lru_spec.rb
 - spec/caches/ttl_spec.rb
@@ -90,21 +106,22 @@ require_paths:
 - lib
 required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
-  - - '>='
+  - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
-  - - '>='
+  - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 2.0.14
+rubygems_version: 2.2.2
 signing_key: 
 specification_version: 4
 summary: Caches with hash-like access
 test_files:
+- spec/benchmark_spec.rb
 - spec/caches/linked_list_spec.rb
 - spec/caches/lru_spec.rb
 - spec/caches/ttl_spec.rb