timed_lru 0.3.1

data/.gitignore

@@ -0,0 +1 @@
+*.gem

data/Gemfile

@@ -0,0 +1,2 @@
+source "http://rubygems.org"
+gemspec

data/Gemfile.lock

@@ -0,0 +1,29 @@
+PATH
+  remote: .
+  specs:
+    timed_lru (0.3.1)
+
+GEM
+  remote: http://rubygems.org/
+  specs:
+    diff-lcs (1.2.1)
+    rake (10.0.3)
+    rspec (2.13.0)
+      rspec-core (~> 2.13.0)
+      rspec-expectations (~> 2.13.0)
+      rspec-mocks (~> 2.13.0)
+    rspec-core (2.13.0)
+    rspec-expectations (2.13.0)
+      diff-lcs (>= 1.1.3, < 2.0)
+    rspec-mocks (2.13.0)
+    yard (0.8.5.2)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  bundler
+  rake
+  rspec
+  timed_lru!
+  yard

data/README.md

@@ -0,0 +1,63 @@
+Timed LRU
+=========
+
+My implementation of a simple, thread-safe LRU with (optional) TTLs
+and constant time operations. There are many LRUs for Ruby available but
+I was unable to find one that matches all three requirements.
+
+Install
+-------
+
+Install it via `gem`:
+
+    gem install timed_lru
+
+Or just bundle it with your project.
+
+Usage Example
+-------------
+
+    # Initialize with a max size (default: 100) and a TTL (default: none)
+    lru = TimedLRU.new max_size: 3, ttl: 5
+
+    # Add values
+    lru["a"] = "value 1"
+    lru["b"] = "value 2"
+    lru["c"] = "value 3"
+    lru.keys # => ["a", "b"]
+
+    # Wait a second
+    sleep(1)
+
+    # Add more values
+    lru["d"] = "value 4"
+    lru.keys # => ["b", "c", "d"]
+
+    # Sleep a little longer
+    sleep(4)
+    lru["c"] # => "value 3"
+    lru.keys # => ["c", "d"]
+
+Licence
+-------
+
+Copyright (c) 2013 Black Square Media Ltd
+
+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,11 @@
+require 'rake'
+
+require 'rspec/mocks/version'
+require 'rspec/core/rake_task'
+RSpec::Core::RakeTask.new(:spec)
+
+require 'yard'
+YARD::Rake::YardocTask.new
+
+desc 'Default: run specs.'
+task :default => :spec

data/lib/timed_lru.rb

@@ -0,0 +1,136 @@
+require 'monitor'
+require 'forwardable'
+
+class TimedLRU
+  include MonitorMixin
+  extend Forwardable
+
+  module ThreadUnsafe
+    def mon_synchronize
+      yield
+    end
+  end
+
+  Node = Struct.new(:key, :value, :left, :right, :expires_at)
+  def_delegators :@hash, :size, :keys, :each_key, :empty?
+
+  # @attr_reader [Integer] max_size
+  attr_reader :max_size
+
+  # @attr_reader [Integer,NilClass] ttl
+  attr_reader :ttl
+
+  # @param [Hash] opts options
+  # @option opts [Integer] max_size
+  #   maximum allowed number of items, defaults to 100
+  # @option opts [Boolean] thread_safe
+  #   true by default, set to false if you are not using threads a *really* need
+  #   that extra bit of performance
+  # @option opts [Integer] ttl
+  #   the TTL in seconds
+  def initialize(opts = {})
+    super() # MonitorMixin
+
+    @hash     = {}
+    @max_size = Integer(opts[:max_size] || 100)
+    @ttl      = Integer(opts[:ttl]) if opts[:ttl]
+
+    raise ArgumentError, "Option :max_size must be > 0" unless max_size > 0
+    raise ArgumentError, "Option :ttl must be > 0" unless ttl.nil? || ttl > 0
+
+    extend ThreadUnsafe if opts[:thread_safe] == false
+  end
+
+  # Stores a `value` by `key`
+  # @param [Object] key the storage key
+  # @param [Object] value the associated value
+  # @return [Object] the value
+  def store(key, value)
+    mon_synchronize do
+      node = (@hash[key] ||= Node.new(key))
+      node.value      = value
+      touch(node)
+      compact!
+      node.value
+    end
+  end
+  alias_method :[]=, :store
+
+  # Retrieves a `value` by `key`
+  # @param [Object] key the storage key
+  # @return [Object,NilClass] value the associated value (or nil)
+  def fetch(key)
+    mon_synchronize do
+      node = @hash[key]
+      break unless node
+
+      touch(node)
+      node.value
+    end
+  end
+  alias_method :[], :fetch
+
+  # Deletes by `key`
+  # @param [Object] key the storage key
+  # @return [Object,NilClass] value the deleted value (or nil)
+  def delete(key)
+    mon_synchronize do
+      node = @hash[key]
+      remove(node).value if node
+    end
+  end
+
+  private
+
+    def compact!
+      while @hash.size > max_size
+        remove(@tail)
+      end
+
+      while ttl && @tail.expires_at < Time.now.to_i
+        remove(@tail)
+      end
+    end
+
+    def remove(node)
+      @hash.delete(node.key)
+      left, right = node.left, node.right
+      left.nil?  ? @head = right : left.right = right
+      right.nil? ? @tail = left : right.left = left
+      node
+    end
+
+    def touch(node)
+      node.expires_at = Time.now.to_i + ttl if ttl
+      return if node == @head
+
+      left, right = node.left, node.right
+      node.left, node.right = nil, @head
+      @head.left = node if @head
+
+      left.right = right if left
+      right.left = left  if right
+
+      @tail = left if @tail == node
+      @head = node
+      @tail = @head unless @tail
+    end
+
+end
+
+      # right ?  : @tail = left
+
+      # return if node == @head
+      # if @head
+      #   @head.left  = node
+      #   @head.right = right if @head.right == node
+      # end
+
+      # if right
+      #   right.left = left
+      # end
+
+      # if @tail == node
+      #   left.right = nil
+      #   @tail = left
+      # end

data/spec/spec_helper.rb

@@ -0,0 +1,4 @@
+require 'bundler/setup'
+require 'rspec'
+require 'timed_lru'
+

data/spec/timed_lru_spec.rb

@@ -0,0 +1,177 @@
+require 'spec_helper'
+
+describe TimedLRU do
+
+  subject { described_class.new max_size: 4 }
+
+  def full_chain
+    return [] unless head
+
+    res = [head]
+    while curr = res.last.right
+      curr.left.should == res.last
+      res << curr
+    end
+    head.left.should be_nil
+    tail.right.should be_nil
+    res.last.should == tail
+    res
+  end
+
+  def chain
+    full_chain.map &:key
+  end
+
+  def head
+    subject.instance_variable_get(:@head)
+  end
+
+  def tail
+    subject.instance_variable_get(:@tail)
+  end
+
+  describe "defaults" do
+    subject { described_class.new }
+
+    its(:max_size) { should be(100) }
+    its(:ttl)      { should be_nil }
+    it             { should be_a(MonitorMixin) }
+    it             { should_not be_a(described_class::ThreadUnsafe) }
+    it             { should respond_to(:empty?) }
+    it             { should respond_to(:keys) }
+    it             { should respond_to(:size) }
+    it             { should respond_to(:each_key) }
+  end
+
+  describe "init" do
+    subject { described_class.new max_size: 25, ttl: 120, thread_safe: false }
+
+    its(:max_size) { should be(25) }
+    its(:ttl)      { should be(120) }
+    it             { should be_a(described_class::ThreadUnsafe) }
+
+    it 'should assert correct option values' do
+      lambda { described_class.new(max_size: "X") }.should raise_error(ArgumentError)
+      lambda { described_class.new(max_size: -1) }.should raise_error(ArgumentError)
+      lambda { described_class.new(max_size: 0) }.should raise_error(ArgumentError)
+
+      lambda { described_class.new(ttl: "X") }.should raise_error(ArgumentError)
+      lambda { described_class.new(ttl: true) }.should raise_error(TypeError)
+      lambda { described_class.new(ttl: 0) }.should raise_error(ArgumentError)
+    end
+  end
+
+  describe "storing" do
+
+    it "should set head + tail on first item" do
+      lambda {
+        subject.store("a", 1).should == 1
+      }.should change { chain }.from([]).to(["a"])
+    end
+
+    it "should shift chain when new items are added" do
+      subject["a"] = 1
+      lambda { subject["b"] = 2 }.should change { chain }.from(%w|a|).to(%w|b a|)
+      lambda { subject["c"] = 3 }.should change { chain }.to(%w|c b a|)
+      lambda { subject["d"] = 4 }.should change { chain }.to(%w|d c b a|)
+    end
+
+    it "should expire LRU items when chain exceeds max size" do
+      ("a".."d").each {|x| subject[x] = 1 }
+      lambda { subject["e"] = 5 }.should change { chain }.to(%w|e d c b|)
+      lambda { subject["f"] = 6 }.should change { chain }.to(%w|f e d c|)
+    end
+
+    it "should update items" do
+      ("a".."d").each {|x| subject[x] = 1 }
+      lambda { subject["d"] = 2 }.should_not change { chain }
+      lambda { subject["c"] = 2 }.should change { chain }.to(%w|c d b a|)
+      lambda { subject["b"] = 2 }.should change { chain }.to(%w|b c d a|)
+      lambda { subject["a"] = 2 }.should change { chain }.to(%w|a b c d|)
+    end
+
+  end
+
+  describe "retrieving" do
+
+    it 'should fetch values' do
+      subject.fetch("a").should be_nil
+      subject["a"].should be_nil
+      subject["a"] = 1
+      subject["a"].should == 1
+    end
+
+    it 'should renew membership on access' do
+      ("a".."d").each {|x| subject[x] = 1 }
+      lambda { subject["d"] }.should_not change { chain }
+      lambda { subject["c"] }.should change { chain }.to(%w|c d b a|)
+      lambda { subject["b"] }.should change { chain }.to(%w|b c d a|)
+      lambda { subject["a"] }.should change { chain }.to(%w|a b c d|)
+      lambda { subject["x"] }.should_not change { chain }
+    end
+
+  end
+
+  describe "deleting" do
+
+    it 'should delete an return values' do
+      subject.delete("a").should be_nil
+      subject["a"] = 1
+      subject.delete("a").should == 1
+    end
+
+    it 'should re-arrange membership chain' do
+      ("a".."d").each {|x| subject[x] = 1 }
+      lambda { subject.delete("x") }.should_not change { chain }
+      lambda { subject.delete("c") }.should change { chain }.to(%w|d b a|)
+      lambda { subject.delete("a") }.should change { chain }.to(%w|d b|)
+      lambda { subject.delete("d") }.should change { chain }.to(%w|b|)
+      lambda { subject.delete("b") }.should change { subject.size }.from(1).to(0)
+    end
+
+  end
+
+  describe "TTL expiration" do
+    subject    { described_class.new max_size: 4, ttl: 60 }
+
+    def in_past(ago)
+      Time.stub now: (Time.now - ago)
+      yield
+    ensure
+      Time.unstub :now
+    end
+
+    it 'should expire on access' do
+      in_past(70) do
+        subject["a"] = 1
+        chain.should == %w|a|
+      end
+
+      in_past(50) do
+        subject["b"] = 2
+        chain.should == %w|b a|
+      end
+
+      subject["c"] = 3
+      chain.should == %w|c b|
+    end
+
+    it 'should renew expiration on access' do
+      in_past(70) do
+        subject["a"] = 1
+        subject["b"] = 2
+        chain.should == %w|b a|
+      end
+
+      in_past(50) do
+        subject["a"].should == 1
+        chain.should == %w|a b|
+      end
+
+      subject["c"] = 3
+      chain.should == %w|c a|
+    end
+
+  end
+
+end

data/timed_lru.gemspec

@@ -0,0 +1,22 @@
+Gem::Specification.new do |s|
+  s.required_ruby_version = '>= 1.9.1'
+  s.required_rubygems_version = ">= 1.8.0"
+
+  s.name        = File.basename(__FILE__, '.gemspec')
+  s.summary     = "Timed LRU"
+  s.description = "Thread-safe LRU implementation with (optional) TTL and constant time operations"
+  s.version     = "0.3.1"
+
+  s.authors     = ["Black Square Media"]
+  s.email       = "info@blacksquaremedia.com"
+  s.homepage    = "https://github.com/bsm/timed_lru"
+
+  s.require_path = 'lib'
+  s.files        = `git ls-files`.split("\n")
+  s.test_files   = `git ls-files -- {test,spec,features}/*`.split("\n")
+
+  s.add_development_dependency "rake"
+  s.add_development_dependency "bundler"
+  s.add_development_dependency "rspec"
+  s.add_development_dependency "yard"
+end

metadata

@@ -0,0 +1,119 @@
+--- !ruby/object:Gem::Specification
+name: timed_lru
+version: !ruby/object:Gem::Version
+  version: 0.3.1
+  prerelease: 
+platform: ruby
+authors:
+- Black Square Media
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2013-03-04 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rake
+  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'
+- !ruby/object:Gem::Dependency
+  name: bundler
+  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'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  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'
+- !ruby/object:Gem::Dependency
+  name: yard
+  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: Thread-safe LRU implementation with (optional) TTL and constant time
+  operations
+email: info@blacksquaremedia.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- .gitignore
+- Gemfile
+- Gemfile.lock
+- README.md
+- Rakefile
+- lib/timed_lru.rb
+- spec/spec_helper.rb
+- spec/timed_lru_spec.rb
+- timed_lru.gemspec
+homepage: https://github.com/bsm/timed_lru
+licenses: []
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: 1.9.1
+required_rubygems_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: 1.8.0
+requirements: []
+rubyforge_project: 
+rubygems_version: 1.8.24
+signing_key: 
+specification_version: 3
+summary: Timed LRU
+test_files: []
+has_rdoc: