hash_cache 0.0.1 → 0.0.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 61ac041d1e693549eb5e98520b4e974b0f8197f7
-  data.tar.gz: 42c22e0f28c1df9c7d91073e29455cab89c4075a
+  metadata.gz: dbcce2aa290c97f9ea5e548fec1cd869cf2b427a
+  data.tar.gz: dbca8cf97e3aefbda13e2d33576d193df35179b1
 SHA512:
-  metadata.gz: 6ee6af4165117ee25f8f8c707aeba7c8a923ef9af0bea40af20ffe2c72f443391edbb81959157f97c97819468e001ec7d6d9ddf7c6a39409cbc5c35f482bf0bc
-  data.tar.gz: f9be59948e4c22d7801f5e3055ba1ccdbb2c7a2d9b1a0bf12b4e8a933215db8abf5399b2575218bd9cd7fc6a10dd458e736d65a42928395587fd9ad03e3db96d
+  metadata.gz: b29355549ca2d293c4adb71f5281708af0ceb144f7d81538627d590bdc5d502d5e0610541fbc78855d7816b145ef8e11a11df7cc697c007cfee105e9d0986c10
+  data.tar.gz: be73b34d5de59cb592b0fff58b726520960c1bb80fce502b34e92df5d0bbd45bc3fde16020c07b979a77354c65fdbd9ab031fee104e67d794ddd06f20fd715e9

data/README.md

@@ -1,70 +1,3 @@
-# HashCache
+# Renamed
 
-HashCache is a small collection of hashes that cache data.
-
-## Usage
-
-HashCache provides the following classes.
-
-### HashCache::TTL
-
-TTL (Time To Live) remembers values for as many seconds as you tell it. The default is 3600 seconds (1 hour).
-
-```ruby
-require 'hash_cache/ttl'
-
-h = HashCache::TTL.new(ttl: 5)
-h[:a] = 'aardvark'
-h[:a] #=> 'aardvark'
-sleep(6)
-h[:a] #=> nil
-```
-
-If you pass `refresh: true`, reading a value will reset its timer; otherwise, only writing will.
-
-The `memoize` method fetches a key if it exists and isn't expired; otherwise, it calculates the value using the block and saves it.
-
-```ruby
-h = HashCache::TTL.new(ttl: 5)
-
-# Runs the block
-h.memoize(:a) { |k| calculation_for(k) }
-
-# Returns the previously-calculated value
-h.memoize(:a) { |k| calculation_for(k) }
-
-sleep(6)
-
-# Runs the block
-h.memoize(:a) { |k| calculation_for(k) }
-```
-
-## Installation
-
-Add this line to your application's Gemfile:
-
-    gem 'hash_cache'
-
-And then execute:
-
-    $ bundle
-
-Or install it yourself as:
-
-    $ gem install hash_cache
-
-## Coming Soon
-
-Other classes with different cache expiration strategies.
-
-## 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
-
-# Thanks
-
-Original tests were adapted from [volatile_hash](https://github.com/satyap/volatile_hash).
+See [https://github.com/nathanl/caches](https://github.com/nathanl/caches)

data/Rakefile

@@ -6,4 +6,12 @@ RSpec::Core::RakeTask.new(:spec) do |t|
   t.rspec_opts = '--format documentation'
 end
 
+task :console do
+  require 'irb'
+  require 'irb/completion'
+  require 'hash_cache/all'
+  ARGV.clear
+  IRB.start
+end
+
 task :default => :spec

data/TODO.md

@@ -0,0 +1,29 @@
+# TODO
+
+## General
+
+- Refactor LinkedList
+- Add benchmarks: speed (and maybe memory usage), runnable with rake task for all cache classes. Be able to compare over the course of development (eg, version 0.0.1 vs 0.0.3). Maybe output ASCII graphs for fun.
+- Add Travis CI testing
+- Give all caches a way to manually invalidate a given key. Return nil if it wasn't here and the value if it was.
+- Add "least used" cache class
+- Define `blank?`, etc on list and caches
+- Should TTL keys be renewed by updates? LRU ones aren't. If the cache exists to be read, probably not.
+- Ride a skateboard and, simultaneously, shoot a potato gun
+
+## New types
+
+Build LU - Least Used. Expiration criteria is essentially "uses per second" - reads divided by time since write.
+
+Implementation ideas:
+  - Passage of time doesn't change ranking of keys; only writing does.
+  - Keep a doubly-linked list of keys ordered by usefulness and a reference to the tail for easy dropping
+  - When updating a key, be able to quickly compare it with the one ahead of it and swap if it overtook it in rank
+  - Normal hash data structure has pointers into linked list segments
+
+
+## Benchmarks
+
+TTL: Prepopulate instances differing in size by orders of magnitude. Measure N operations of various types. These vary on three axes: read/write, expired/fresh, and update/insert for writes. Output results as graph. Visually confirm that it appears O(1) and is reasonably fast (?) in absolute terms.
+
+LRU: ?

data/hash_cache.gemspec

@@ -8,8 +8,8 @@ Gem::Specification.new do |spec|
   spec.version       = HashCache::VERSION
   spec.authors       = ["Nathan Long"]
   spec.email         = ["nathanmlong@gmail.com"]
-  spec.description   = %q{A small collection of hashes that cache}
-  spec.summary       = %q{A small collection of hashes that cache}
+  spec.description   = %q{Renamed - see 'caches' gem}
+  spec.summary       = %q{Renamed - see 'caches' gem}
   spec.homepage      = "https://github.com/nathanl/hash_cache"
   spec.license       = "MIT"
 

data/lib/hash_cache/accessible.rb

@@ -0,0 +1,19 @@
+module HashCache
+  module Accessible
+
+    def fetch(key, default = (default_omitted = true; nil))
+      return self[key]  if data.has_key?(key)
+      return yield(key) if block_given?
+      return default    unless default_omitted
+      raise KeyError
+    end
+
+    def memoize(key)
+      raise ArgumentError, "Block is required" unless block_given?
+      self[key] # triggers flush or refresh if expired
+      return self[key]       if data.has_key?(key)
+      self[key] = yield(key) if block_given?
+    end
+
+  end
+end

data/lib/hash_cache/all.rb

@@ -0,0 +1,2 @@
+require_relative 'ttl'
+require_relative 'lru'

data/lib/hash_cache/linked_list.rb

@@ -0,0 +1,115 @@
+module HashCache
+  # This LinkedList class is unusual in that it gives direct access to its nodes.
+  # It trusts the user not to break it! The advantage is that outsiders with
+  # a node reference can reorder the list (eg, using #move_to_head) in O(1) time.
+  class LinkedList
+    include Enumerable
+
+    attr_reader :length
+
+    def initialize(item = nil)
+      if item
+        Node.new(item).tap { |node|
+          self.head   = self.tail = node
+          self.length = 1
+        }
+      else
+        self.length = 0
+      end
+    end
+
+    def each
+      current = head
+      while current do
+        yield(current.value)
+        current = current.right
+      end
+    end
+
+    def append(item)
+      return initialize(item) if empty?
+      Node.new(item, left: tail).tap { |new_tail|
+        tail.right = new_tail
+        self.tail  = new_tail
+        self.length = length + 1
+      }
+    end
+
+    def prepend(item)
+      return initialize(item) if empty?
+      Node.new(item, right: head).tap { |new_head|
+        head.left = new_head
+        self.head = new_head
+        self.length = length + 1
+      }
+    end
+    alias :unshift :prepend
+
+    def pop
+      tail.tap {
+        new_tail       = tail.left
+        new_tail.right = nil
+        self.tail      = new_tail
+        self.length = length - 1
+      }
+    end
+
+    def lpop
+      head.tap {
+        new_head      = head.right
+        new_head.left = nil
+        self.head     = new_head
+        self.length = length - 1
+      }
+    end
+    alias :shift :lpop
+
+    def move_to_head(node)
+      excise(node)
+      node.right = head
+      self.head  = node
+    end
+
+    def empty?
+      length == 0
+    end
+
+    # TODO - move these to a module and use in caches, too
+    alias :blank? :empty?
+    def present?
+      !empty?
+    end
+    def presence
+      self if present?
+    end
+
+    private
+    attr_accessor :head, :tail
+    attr_writer   :length
+
+    def excise(node)
+      raise InvalidNode unless node.is_a?(Node)
+      left       = node.left
+      right      = node.right
+      left.right = right unless left.nil?
+      right.left = left  unless right.nil?
+      self.head  = right if head == node
+      self.tail  = left  if tail == node
+      node
+    end
+
+    class Node
+      attr_accessor :value, :right, :left
+      def initialize(value, pointers = {})
+        self.value = value
+        self.right = pointers[:right]
+        self.left  = pointers[:left]
+      end
+
+      def right?; !right.nil?; end
+      def left?;  !left.nil?   end
+    end
+
+    InvalidNode = Class.new(StandardError)
+  end
+end

data/lib/hash_cache/lru.rb

@@ -0,0 +1,47 @@
+require_relative 'accessible'
+require_relative 'linked_list'
+
+module HashCache
+  class LRU
+    include Accessible
+    attr_accessor :max_keys
+
+    def initialize(options = {})
+      self.max_keys = options.fetch(:max_keys, 20)
+      self.data     = {}
+      self.keys = LinkedList.new
+    end
+
+    def [](key)
+      return nil unless data.has_key?(key)
+      value, node = data[key]
+      keys.move_to_head(node)
+      value
+    end
+
+    def []=(key, val)
+      if data.has_key?(key)
+        data[key][0] = val
+      else
+        node = keys.prepend(key)
+        data[key] = [val, node]
+      end
+      prune
+      val
+    end
+
+    def size
+      keys.length
+    end
+
+    private
+    attr_accessor :keys, :data
+
+    def prune
+      return unless keys.length > max_keys
+      expiring_node = keys.pop
+      data.delete(expiring_node.value)
+    end
+
+  end
+end

data/lib/hash_cache/ttl.rb

@@ -1,5 +1,8 @@
+require_relative 'accessible'
+
 module HashCache
   class TTL
+    include Accessible
     attr_accessor :ttl, :refresh
 
     def initialize(options = {})
@@ -23,18 +26,8 @@ module HashCache
       data[key] = {time: current_time, value: val}
     end
 
-    def fetch(key, default = (default_omitted = true; nil))
-      return self[key]  if data.has_key?(key)
-      return default    unless default_omitted
-      return yield(key) if block_given?
-      raise KeyError
-    end
-
-    def memoize(key)
-      raise ArgumentError, "Block is required" unless block_given?
-      self[key] # triggers flush or refresh if expired
-      return self[key]       if data.has_key?(key)
-      self[key] = yield(key) if block_given?
+    def size
+      data.keys.length
     end
 
     private

data/lib/hash_cache/version.rb

@@ -1,3 +1,3 @@
 module HashCache
-  VERSION = "0.0.1"
+  VERSION = "0.0.2"
 end

data/spec/fetch_examples.rb

@@ -0,0 +1,24 @@
+shared_examples "fetch" do
+
+  it "returns the value if an existing key is accessed" do
+    expect(cache.fetch(:c)).to eq('Caspian')
+  end
+
+  it "raises an error if a missing key is accessed" do
+    expect{cache.fetch(:nonexistent)}.to raise_error(KeyError)
+  end
+
+  it "uses a default value if one is supplied" do
+    expect(cache.fetch(:nonexistent, 'hi')).to eq('hi')
+  end
+
+  it "gets its default from a block if one is supplied" do
+    expect(cache.fetch(:nonexistent) { |key| key.to_s.upcase }).to eq('NONEXISTENT')
+  end
+
+  it "prefers a block value to an immediate one (like native hashes do)" do
+    expect(cache.fetch(:nonexistent, 'hi') { |key| key.to_s.upcase }).to eq('NONEXISTENT')
+  end
+
+end
+

data/spec/hash_cache/linked_list_spec.rb

@@ -0,0 +1,120 @@
+require          'spec_helper'
+require_relative '../../lib/hash_cache/linked_list'
+
+describe HashCache::LinkedList do
+
+  let(:empty_list) { described_class.new }
+  let(:list)       { described_class.new('lemur') }
+  let(:node_class) { HashCache::LinkedList::Node }
+
+  it "can convert itself to an array of values" do
+    expect(list.to_a).to eq(['lemur'])
+  end
+
+  describe '#append' do
+
+    it "adds an item to the end" do
+      list.append('wombat')
+      expect(list.to_a).to eq(['lemur', 'wombat'])
+    end
+
+    it "returns a Node" do
+      node = list.append('wombat')
+      expect(node).to be_a(node_class)
+    end
+
+    it "sets up the list correctly if it was empty to start with" do
+      empty_list.append('jimmy')
+      expect{empty_list.prepend('jammy')}.not_to raise_error
+    end
+
+  end
+
+  describe "#prepend" do
+
+    it "adds an item to the beginning" do
+      list.prepend('vole')
+      expect(list.to_a).to eq(['vole', 'lemur'])
+    end
+
+    it "returns a Node" do
+      node = list.prepend('vole')
+      expect(node).to be_a(node_class)
+    end
+
+    it "sets up the list correctly if it was empty to start with" do
+      empty_list.prepend('jimmy')
+      expect{empty_list.append('jammy')}.not_to raise_error
+    end
+
+  end
+
+  it "knows its length" do
+    expect(list.length).to eq(1)
+    list.append('wombat')
+    list.prepend('vole')
+    expect(list.length).to eq(3)
+  end
+
+  describe "#move_to_head" do
+
+    context "when the argument is a Node" do
+
+      it "makes it the new head" do
+        list.append('mittens')
+        node = list.append('cozy')
+        list.move_to_head(node)
+        expect(list.to_a).to eq(%w[cozy lemur mittens])
+      end
+
+    end
+
+    context "when the argument is not a Node" do
+
+      it "raises an error" do
+        list.append('cozy')
+        expect{list.move_to_head('super duper')}.to raise_error(HashCache::LinkedList::InvalidNode)
+      end
+
+    end
+
+  end
+
+  context "when there's more than one item" do
+
+    let(:list) {
+      list = described_class.new('lemur')
+      list.append('muskrat')
+      list
+    }
+
+    describe "#pop" do
+
+      it "removes the last item" do
+        list.pop
+        expect(list.to_a).to eq(['lemur'])
+      end
+
+      it "returns a node" do
+        expect(list.pop).to be_a(node_class)
+      end
+
+    end
+
+
+    describe "#lpop" do
+
+      it "removes the first item" do
+        list.lpop
+        expect(list.to_a).to eq(['muskrat'])
+      end
+
+      it "returns a node" do
+        expect(list.lpop).to be_a(node_class)
+      end
+
+    end
+
+  end
+
+end

data/spec/hash_cache/lru_spec.rb

@@ -0,0 +1,108 @@
+require          'spec_helper'
+require          'fetch_examples'
+require_relative '../../lib/hash_cache/lru'
+
+describe HashCache::LRU do
+
+  let(:options) { {max_keys: 4} }
+  let(:cache)   {
+    described_class.new(options).tap {|c|
+      c[:a] = 'Alambil'
+      c[:b] = 'Belisar'
+      c[:c] = 'Caspian'
+    }
+  }
+
+  it "remembers its values" do
+    expect(cache[:a]).to eq('Alambil')
+    expect(cache[:b]).to eq('Belisar')
+    expect(cache[:c]).to eq('Caspian')
+  end
+
+  it "can report its size" do
+    expect(cache.size).to eq(3)
+  end
+
+  it "can grow up to the max size given" do
+    cache[:d] = 'Destrier'
+    expect(cache.size).to eq(4)
+  end
+
+  it "does not grow beyond the max size given" do
+    cache[:d] = 'Destrier'
+    cache[:e] = 'Erimon'
+    expect(cache.size).to eq(4)
+  end
+
+  it "drops the least-recently accessed key" do
+    cache[:d] = 'Destrier'
+    cache[:e] = 'Erimon'
+    expect(cache[:a]).to be_nil
+  end
+
+  it "counts a read as access" do
+    cache[:d] = 'Destrier'
+    cache[:a]
+    cache[:e] = 'Erimon'
+    expect(cache[:a]).to eq('Alambil')
+    expect(cache[:b]).to be_nil
+  end
+
+  include_examples "fetch"
+
+  describe "memoize" do
+
+    it "requires a block" do
+      expect{cache_memoize(:c)}.to raise_error
+    end
+
+    let(:greeting) { 'hi' }
+
+    context "when the key already exists" do
+
+      it "does not calculate the value" do
+        expect(greeting).not_to receive(:upcase)
+        cache.memoize(:c) { greeting.upcase }
+      end
+
+    end
+
+    context "when the key has not been set" do
+
+      let(:key) { :nonexistent }
+
+      it "calculates the value" do
+        expect(greeting).to receive(:upcase)
+        cache.memoize(:nonexistent) { greeting.upcase }
+      end
+
+      it "sets the value" do
+        cache.memoize(:nonexistent) { greeting.upcase }
+        expect(cache[:nonexistent]).to eq(greeting.upcase)
+      end
+
+    end
+
+    context "when the key has been dropped" do
+
+      before :each do
+        cache[:d] = 'Destrier'
+        cache[:e] = 'Erimon'
+      end
+
+      it "calculates the value" do
+        expect(greeting).to receive(:upcase)
+        cache.memoize(:a) { greeting.upcase }
+      end
+
+      it "sets the value" do
+        cache.memoize(:a) { greeting.upcase }
+        expect(cache[:a]).to eq(greeting.upcase)
+      end
+
+    end
+
+  end
+
+end
+

data/spec/hash_cache/ttl_spec.rb

@@ -1,4 +1,5 @@
 require          'spec_helper'
+require          'fetch_examples'
 require_relative '../../lib/hash_cache/ttl'
 
 describe HashCache::TTL do
@@ -15,6 +16,10 @@ describe HashCache::TTL do
   let(:before_ttl) { start_time + 1800 }
   let(:after_ttl)  { start_time + 3601 }
 
+  it "can report its size" do
+    expect(cache.size).to eq(1)
+  end
+
   it "remembers cached values before the TTL expires" do
     expect(cache[:c]).to eq('Caspian')
     cache.stub(:current_time).and_return(before_ttl)
@@ -61,29 +66,7 @@ describe HashCache::TTL do
 
   end
 
-  describe "fetch" do
-
-    it "returns the value if an existing key is accessed" do
-      expect(cache.fetch(:c)).to eq('Caspian')
-    end
-
-    it "raises an error if a missing key is accessed" do
-      expect{cache.fetch(:nonexistent)}.to raise_error(KeyError)
-    end
-
-    it "uses a default value if one is supplied" do
-      expect(cache.fetch(:nonexistent, 'hi')).to eq('hi')
-    end
-
-    it "gets its default from a block if one is supplied" do
-      expect(cache.fetch(:nonexistent) { |key| key.to_s.upcase }).to eq('NONEXISTENT')
-    end
-
-    it "uses the immediate value if both it and the block are supplied" do
-      expect(cache.fetch(:nonexistent, 'hi') { |key| key.to_s.upcase }).to eq('hi')
-    end
-
-  end
+  include_examples "fetch"
 
   describe "memoize" do
 

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: hash_cache
 version: !ruby/object:Gem::Version
-  version: 0.0.1
+  version: 0.0.2
 platform: ruby
 authors:
 - Nathan Long
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2014-01-17 00:00:00.000000000 Z
+date: 2014-09-22 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -52,7 +52,7 @@ dependencies:
     - - ~>
       - !ruby/object:Gem::Version
         version: '2.14'
-description: A small collection of hashes that cache
+description: Renamed - see 'caches' gem
 email:
 - nathanmlong@gmail.com
 executables: []
@@ -64,10 +64,18 @@ files:
 - LICENSE.txt
 - README.md
 - Rakefile
+- TODO.md
 - hash_cache.gemspec
 - lib/hash_cache.rb
+- lib/hash_cache/accessible.rb
+- lib/hash_cache/all.rb
+- lib/hash_cache/linked_list.rb
+- lib/hash_cache/lru.rb
 - lib/hash_cache/ttl.rb
 - lib/hash_cache/version.rb
+- spec/fetch_examples.rb
+- spec/hash_cache/linked_list_spec.rb
+- spec/hash_cache/lru_spec.rb
 - spec/hash_cache/ttl_spec.rb
 - spec/spec_helper.rb
 homepage: https://github.com/nathanl/hash_cache
@@ -93,7 +101,10 @@ rubyforge_project:
 rubygems_version: 2.0.14
 signing_key: 
 specification_version: 4
-summary: A small collection of hashes that cache
+summary: Renamed - see 'caches' gem
 test_files:
+- spec/fetch_examples.rb
+- spec/hash_cache/linked_list_spec.rb
+- spec/hash_cache/lru_spec.rb
 - spec/hash_cache/ttl_spec.rb
 - spec/spec_helper.rb