lru_redux 0.8.4 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 44f9731a90a6a4021eec3488c38c5a82399f7089
-  data.tar.gz: cd4f27cc1d9eca928e1a1e8c9b75507a4c06a81d
+  metadata.gz: ee0116ff3d2b67bcd4afa09cc37dff5d64d1f173
+  data.tar.gz: 1a8db0cbbecb94b2f112ef2482f7a76f2335dd03
 SHA512:
-  metadata.gz: e5b6832027fc7e09a7e319981ef2acc9399b11fdce5015c7c24354f6e50dbc8794b056cc995733387dbc9b658e67bc610b92a55dc905905f53b7d8e1f8a50398
-  data.tar.gz: ac925de76a377ffd499c20c626f4eb650232b4deb888cd7958452a24c425ce0a64fe6a8e62373d6c8e8e2a1bc3bd0f14f4aeb54475fb70edb1cf6bea2ae061a4
+  metadata.gz: 1982913819cd75633cef5158c3adc14d0680a3a5fd1c4c4bec4a5f73455817c76d4f7a65e0ffc3fd9ef2b03c73db4948c39464585439c6867e5850c5a1f080e9
+  data.tar.gz: 3da4da91b505b90a9ce57fc0f1abc288aee7cc1496e16e020e234dfa621c1b1cd179fed22d467addeb2fedcbc7acdbc1d797c8e072549f405a8016ec1c78cdc1

data/README.md

@@ -1,10 +1,14 @@
-# LruRedux
-
-An efficient thread safe lru cache.
-
-Lru Redux uses a Hash/Double link list backed storage to keep track of nodes in a cache based on last usage.
-
-This provides a correct and well specified LRU cache, that is very efficient. Additionally you can optionally use a thread safe wrapper.
+# LruRedux [![Gem Version](https://badge.fury.io/rb/lru_redux.svg)](http://badge.fury.io/rb/lru_redux)
+An efficient, thread safe LRU cache.
+
+- [Installation](#installation)
+- [Usage](#usage)
+  - [TTL Cache](#ttl-cache)
+- [Cache Methods](#cache-methods)
+- [Benchmarks](#benchmarks)
+- [Other Caches](#other-caches)
+- [Contributing](#contributing)
+- [Changelog](#changelog)
 
 ## Installation
 
@@ -20,6 +24,10 @@ Or install it yourself as:
 
     $ gem install lru_redux
 
+Ruby 1.8 - v0.8.4 is the last compatible release:
+
+    gem 'lru_redux', '~> 0.8.4'
+
 ## Usage
 
 ```ruby
@@ -61,29 +69,174 @@ cache = LruRedux::ThreadSafeCache.new(100)
 
 ```
 
+#### TTL Cache
+The TTL cache extends the functionality of the LRU cache with a Time To Live eviction strategy. TTL eviction occurs on every access and takes precedence over LRU eviction, meaning a 'live' value will never be evicted over an expired one.
+
+```ruby
+# Timecop is gem that allows us to change Time.now
+# and is used for demonstration purposes.
+require 'lru_redux'
+require 'timecop'
+
+# Create a TTL cache with a size of 100 and TTL of 5 minutes.
+# The first argument is the size and
+# the second optional argument is the TTL in seconds.
+cache = LruRedux::TTL::Cache.new(100, 5 * 60)
+
+Timecop.freeze(Time.now)
+
+cache[:a] = "1"
+cache[:b] = "2"
+
+cache.to_a
+# => [[:b,"2"],[:a,"1"]]
+
+# Now we advance time 5 min 30 sec into the future.
+Timecop.freeze(Time.now + 330)
+
+# And we see that the expired values have been evicted.
+cache.to_a
+# => []
+
+# The TTL can be updated on a live cache using #ttl=.
+# Currently cached items will be evicted under the new TTL.
+cache[:a] = "1"
+cache[:b] = "2"
+
+Timecop.freeze(Time.now + 330)
+
+cache.ttl = 10 * 60
+
+# Since ttl eviction is triggered by access,
+# the items are still cached when the ttl is changed and
+# are now under the 10 minute TTL.
+cache.to_a
+# => [[:b,"2"],[:a,"1"]]
+
+# TTL eviction can be triggered manually with the #expire method.
+Timecop.freeze(Time.now + 330)
+
+cache.expire
+cache.to_a
+# => []
+
+Timecop.return
+
+# The behavior of a TTL cache with the TTL set to `:none`
+# is identical to the LRU cache.
+
+cache = LruRedux::TTL::Cache.new(100, :none)
+
+# The TTL argument is optional and defaults to `:none`.
+cache = LruRedux::TTL::Cache.new(100)
+
+# A thread safe version is available.
+cache = LruRedux::TTL::ThreadSafeCache.new(100, 5 * 60)
+```
+
+## Cache Methods
+- `#getset` Takes a key and block.  Will return a value if cached, otherwise will execute the block and cache the resulting value.
+- `#fetch` Takes a key and optional block.  Will return a value if cached, otherwise will execute the block and return the resulting value or return nil if no block is provided.
+- `#[]` Takes a key.  Will return a value if cached, otherwise nil.
+- `#[]=` Takes a key and value. Will cache the value under the key.
+- `#delete` Takes a key.  Will return the deleted value, otherwise nil.
+- `#evict` Alias for `#delete`.
+- `#clear` Clears the cache. Returns nil.
+- `#each` Takes a block.  Executes the block on each key-value pair in LRU order (most recent first).
+- `#to_a` Return an array of key-value pairs (arrays) in LRU order (most recent first).
+- `#key?` Takes a key.  Returns true if the key is cached, otherwise false.
+- `#has_key?` Alias for `#key?`.
+- `#count` Return the current number of items stored in the cache.
+- `#max_size` Returns the current maximum size of the cache.
+- `#max_size=` Takes a positive number.  Changes the current max_size and triggers a resize.  Also triggers TTL eviction on the TTL cache.
+
+#### TTL Cache Specific
+- `#ttl` Returns the current TTL of the cache.
+- `#ttl=` Takes `:none` or a positive number.  Changes the current ttl and triggers a TTL eviction.
+- `#expire` Triggers a TTL eviction.
+
 ## Benchmarks
 
 see: benchmark directory (a million random lookup / store)
 
+#### LRU
+##### Ruby 2.2.1
 ```
 $ ruby ./bench/bench.rb
-Rehearsal ---------------------------------------------------------
-thread safe lru         4.530000   0.020000   4.550000 (  4.540861)
-lru gem                 2.040000   0.000000   2.040000 (  2.046777)
-lru_cache gem           1.660000   0.010000   1.670000 (  1.670404)
-lru_redux gem           1.200000   0.000000   1.200000 (  1.197036)
-lru_redux thread safe   2.520000   0.000000   2.520000 (  2.526945)
------------------------------------------------ total: 11.980000sec
-
-                            user     system      total        real
-thread safe lru         4.550000   0.030000   4.580000 (  4.581848)
-lru gem                 2.060000   0.000000   2.060000 (  2.056636)
-lru_cache gem           1.660000   0.010000   1.670000 (  1.669312)
-lru_redux gem           1.180000   0.000000   1.180000 (  1.187639)
-lru_redux thread safe   2.530000   0.000000   2.530000 (  2.532061)
 
+Rehearsal -------------------------------------------------------------
+ThreadSafeLru               4.500000   0.030000   4.530000 (  4.524213)
+LRU                         2.250000   0.000000   2.250000 (  2.249670)
+LRUCache                    1.720000   0.010000   1.730000 (  1.728243)
+LruRedux::Cache             0.960000   0.000000   0.960000 (  0.961292)
+LruRedux::ThreadSafeCache   2.180000   0.000000   2.180000 (  2.187714)
+--------------------------------------------------- total: 11.650000sec
+
+                                user     system      total        real
+ThreadSafeLru               4.390000   0.020000   4.410000 (  4.415703)
+LRU                         2.140000   0.010000   2.150000 (  2.149626)
+LRUCache                    1.680000   0.010000   1.690000 (  1.688564)
+LruRedux::Cache             0.910000   0.000000   0.910000 (  0.913108)
+LruRedux::ThreadSafeCache   2.200000   0.010000   2.210000 (  2.212108)
 ```
 
+##### Ruby 2.0.0-p643
+Implementation is slightly different for Ruby versions before 2.1 due to a Ruby bug. http://bugs.ruby-lang.org/issues/8312
+```
+$ ruby ./bench/bench.rb
+Rehearsal -------------------------------------------------------------
+ThreadSafeLru               4.790000   0.040000   4.830000 (  4.828370)
+LRU                         2.170000   0.010000   2.180000 (  2.180630)
+LRUCache                    1.810000   0.000000   1.810000 (  1.814737)
+LruRedux::Cache             1.330000   0.010000   1.340000 (  1.325554)
+LruRedux::ThreadSafeCache   2.770000   0.000000   2.770000 (  2.777754)
+--------------------------------------------------- total: 12.930000sec
+
+                                user     system      total        real
+ThreadSafeLru               4.710000   0.060000   4.770000 (  4.773233)
+LRU                         2.120000   0.010000   2.130000 (  2.135111)
+LRUCache                    1.780000   0.000000   1.780000 (  1.781392)
+LruRedux::Cache             1.190000   0.010000   1.200000 (  1.201908)
+LruRedux::ThreadSafeCache   2.650000   0.010000   2.660000 (  2.652580)
+```
+
+#### TTL
+##### Ruby 2.2.1
+```
+$ ruby ./bench/bench_ttl.rb
+Rehearsal -----------------------------------------------------------------------
+FastCache                             6.240000   0.070000   6.310000 (  6.302569)
+LruRedux::TTL::Cache                  4.700000   0.010000   4.710000 (  4.712858)
+LruRedux::TTL::ThreadSafeCache        6.300000   0.010000   6.310000 (  6.319032)
+LruRedux::TTL::Cache (TTL disabled)   2.460000   0.010000   2.470000 (  2.470629)
+------------------------------------------------------------- total: 19.800000sec
+
+                                          user     system      total        real
+FastCache                             6.470000   0.070000   6.540000 (  6.536193)
+LruRedux::TTL::Cache                  4.640000   0.010000   4.650000 (  4.661793)
+LruRedux::TTL::ThreadSafeCache        6.310000   0.020000   6.330000 (  6.328840)
+LruRedux::TTL::Cache (TTL disabled)   2.440000   0.000000   2.440000 (  2.446269)
+```
+
+## Other Caches
+This is a list of the caches that are used in the benchmarks.
+
+#### LRU
+- RubyGems: https://rubygems.org/gems/lru
+- Homepage: http://lru.rubyforge.org/
+
+#### LRUCache
+- RubyGems: https://rubygems.org/gems/lru_cache
+- Homepage: https://github.com/brendan/lru_cache
+
+#### ThreadSafeLru
+- RubyGems: https://rubygems.org/gems/threadsafe-lru
+- Homepage: https://github.com/draganm/threadsafe-lru
+
+#### FastCache
+- RubyGems: https://rubygems.org/gems/fast_cache
+- Homepage: https://github.com/swoop-inc/fast_cache
+
 
 ## Contributing
 
@@ -94,20 +247,28 @@ lru_redux thread safe   2.530000   0.000000   2.530000 (  2.532061)
 5. Create new Pull Request
 
 ## Changlog
+###version 1.1.0 - 30-Mar-2015
+
+- New: TTL cache added.  This cache is LRU like with the addition of time-based eviction.  Check the Usage -> TTL Cache section in README.md for details.
+
+###version 1.0.0 - 26-Mar-2015
+
+- Ruby Support: Ruby 1.9+ is now required by LruRedux.  If you need to use LruRedux in Ruby 1.8, please specify gem version 0.8.4 in your Gemfile.  v0.8.4 is the last 1.8 compatible release and included a number of fixes and performance improvements for the Ruby 1.8 implementation. @Seberius
+- Perf: improve performance in Ruby 2.1+ on the MRI @Seberius
 
-###version 0.8.4 - 20-Feb-2014
+###version 0.8.4 - 20-Feb-2015
 
-- Fix: regression of ThreadSafeCache under JRuby 1.7 @Sevrius
+- Fix: regression of ThreadSafeCache under JRuby 1.7 @Seberius
 
-###version 0.8.3 - 20-Feb-2014
+###version 0.8.3 - 20-Feb-2015
 
-- Perf: improve ThreadSafeCache performance @Sevrius
+- Perf: improve ThreadSafeCache performance @Seberius
 
-###version 0.8.2 - 16-Feb-2014
+###version 0.8.2 - 16-Feb-2015
 
-- Perf: use #size instead of #count when checking length @Sebrius
-- Fix: Cache could grow beyond its size in Ruby 1.8 @Sebrius
-- Fix: #each could deadlock in Ruby 1.8 @Sebrius
+- Perf: use #size instead of #count when checking length @Seberius
+- Fix: Cache could grow beyond its size in Ruby 1.8 @Seberius
+- Fix: #each could deadlock in Ruby 1.8 @Seberius
 
 
 ###version 0.8.1 - 7-Sep-2013

data/Rakefile

@@ -3,5 +3,5 @@ require "bundler/gem_tasks"
 require 'rake/testtask'
 
 Rake::TestTask.new do |t|
-  t.pattern = "test/*_test.rb"
+  t.pattern = "test/**/*_test.rb"
 end

data/bench/bench.rb

@@ -1,45 +1,43 @@
-require 'rubygems'
-require 'lru'
+require 'bundler'
 require 'benchmark'
+require 'lru'
 require 'lru_cache'
 require 'threadsafe-lru'
-$LOAD_PATH.unshift File.expand_path '../lib'
-require File.expand_path('../../lib/lru_redux', __FILE__)
 
+Bundler.require
+
+# Lru
 lru = Cache::LRU.new(max_elements: 1_000)
+
+# LruCache
 lru_cache = LRUCache.new(1_000)
 
-lru_redux = LruRedux::Cache.new(1_000)
-lru_redux_thread_safe = LruRedux::ThreadSafeCache.new(1_000)
+# ThreadSafeLru
 thread_safe_lru = ThreadSafeLru::LruCache.new(1_000)
 
-bm = Benchmark.bmbm do |bm|
+# LruRedux
+redux = LruRedux::Cache.new(1_000)
+redux_thread_safe = LruRedux::ThreadSafeCache.new(1_000)
+
+puts "** LRU Benchmarks **"
+Benchmark.bmbm do |bm|
+  bm.report 'ThreadSafeLru' do
+    1_000_000.times { thread_safe_lru.get(rand(2_000)) { :value } }
+  end
+
+  bm.report 'LRU' do
+    1_000_000.times { lru[rand(2_000)] ||= :value }
+  end
 
-  bm.report "thread safe lru" do
-    1_000_000.times do
-      thread_safe_lru.get(rand(2_000)){ :value }
-    end
+  bm.report 'LRUCache' do
+    1_000_000.times { lru_cache[rand(2_000)] ||= :value }
   end
 
-  [
-    [lru, "lru gem"],
-    [lru_cache, "lru_cache gem"],
-  ].each do |cache, name|
-    bm.report name do
-      1_000_000.times do
-        cache[rand(2_000)] ||= :value
-      end
-    end
+  bm.report 'LruRedux::Cache' do
+    1_000_000.times { redux.getset(rand(2_000)) { :value } }
   end
 
-  [
-      [lru_redux, "lru_redux gem"],
-      [lru_redux_thread_safe, "lru_redux thread safe"]
-  ].each do |cache, name|
-    bm.report name do
-      1_000_000.times do
-        cache.getset(rand(2_000)) { :value }
-      end
-    end
+  bm.report 'LruRedux::ThreadSafeCache' do
+    1_000_000.times { redux_thread_safe.getset(rand(2_000)) { :value } }
   end
 end

data/bench/bench_ttl.rb

@@ -0,0 +1,33 @@
+require 'bundler'
+require 'benchmark'
+require 'fast_cache'
+
+Bundler.require
+
+# FastCache
+fast_cache = FastCache::Cache.new(1_000, 5 * 60)
+
+# LruRedux
+redux_ttl = LruRedux::TTL::Cache.new(1_000, 5 * 60)
+redux_ttl_thread_safe = LruRedux::TTL::ThreadSafeCache.new(1_000, 5 * 60)
+redux_ttl_disabled = LruRedux::TTL::Cache.new(1_000, :none)
+
+puts
+puts "** TTL Benchmarks **"
+Benchmark.bmbm do |bm|
+  bm.report 'FastCache' do
+    1_000_000.times { fast_cache.fetch(rand(2_000)) { :value } }
+  end
+
+  bm.report 'LruRedux::TTL::Cache' do
+    1_000_000.times { redux_ttl.getset(rand(2_000)) { :value } }
+  end
+
+  bm.report 'LruRedux::TTL::ThreadSafeCache' do
+    1_000_000.times { redux_ttl_thread_safe.getset(rand(2_000)) { :value } }
+  end
+
+  bm.report 'LruRedux::TTL::Cache (TTL disabled)' do
+    1_000_000.times { redux_ttl_disabled.getset(rand(2_000)) { :value } }
+  end
+end

data/lib/lru_redux.rb

@@ -1,16 +1,11 @@
-module LruRedux
-  def self.is_19?
-    major,minor = RUBY_VERSION.split(".").map{|a| a.to_i}
-    major > 1 || (major == 1 && minor > 8)
-  end
-end
+require "lru_redux/util"
+
+require "lru_redux/cache"
+require "lru_redux/cache_legacy" if
+    RUBY_ENGINE == "ruby" && RUBY_VERSION < "2.1.0"
 
-require "lru_redux/version"
-if LruRedux.is_19?
-  require "lru_redux/cache19"
-else
-  require "lru_redux/cache"
-end
 require "lru_redux/thread_safe_cache"
-require "lru_redux/thread_safe_cache_jruby" if
-    RUBY_PLATFORM == 'java' && JRUBY_VERSION < '9.0'
+
+require "lru_redux/ttl"
+
+require "lru_redux/version"

data/lib/lru_redux/cache.rb

@@ -1,163 +1,108 @@
-
-
+# Ruby 1.9 makes our life easier, Hash is already ordered
+#
+# This is an ultra efficient 1.9 freindly implementation
 class LruRedux::Cache
+  def initialize(*args)
+    max_size, _ = args
 
-  # for high efficiency nodes in double linked list are stored in arrays
-  # [prev,key,val,next]
-  #
-  # This makes this much more annoying to code, but gives us a 5-10% edge
+    raise ArgumentError.new(:max_size) if max_size < 1
 
-  def initialize(max_size)
     @max_size = max_size
     @data = {}
-    @head = nil
-    @tail = nil
   end
 
-  def max_size=(size)
-    raise ArgumentError.new(:max_size) if @max_size < 1
-    @max_size = size
-    while pop_tail
-      # no op
-    end
+  def max_size=(max_size)
+    max_size ||= @max_size
+
+    raise ArgumentError.new(:max_size) if max_size < 1
+
+    @max_size = max_size
+
+    @data.shift while @data.size > @max_size
+  end
+
+  def ttl=(_)
+    nil
   end
 
   def getset(key)
-    node = @data[key]
-    if node
-      move_to_head(node)
-      node[2]
+    found = true
+    value = @data.delete(key){ found = false }
+    if found
+      @data[key] = value
     else
-      self[key] = yield
+      result = @data[key] = yield
+      @data.shift if @data.length > @max_size
+      result
     end
   end
 
   def fetch(key)
-    node = @data[key]
-    if node
-      move_to_head(node)
-      node[2]
+    found = true
+    value = @data.delete(key){ found = false }
+    if found
+      @data[key] = value
     else
       yield if block_given?
     end
   end
 
   def [](key)
-    node = @data[key]
-    if node
-      move_to_head(node)
-      node[2]
+    found = true
+    value = @data.delete(key){ found = false }
+    if found
+      @data[key] = value
+    else
+      nil
     end
   end
 
   def []=(key,val)
-    node = @data[key]
-    if node
-      move_to_head(node)
-      node[2] = val
-    else
-      @data[key] = add_to_head(key,val)
-      pop_tail
-    end
+    @data.delete(key)
+    @data[key] = val
+    @data.shift if @data.length > @max_size
     val
   end
 
   def each
-    a = to_a
-    a.each do |pair|
+    array = @data.to_a
+    array.reverse!.each do |pair|
       yield pair
     end
   end
 
-  def each_unsafe
-    n = @head
-    if n
-      while n
-        yield [n[1], n[2]]
-        n = n[0]
-      end
-    end
-  end
+  # used further up the chain, non thread safe each
+  alias_method :each_unsafe, :each
 
   def to_a
-    a = []
-    self.each_unsafe do |k,v|
-      a << [k,v]
-    end
-    a
+    array = @data.to_a
+    array.reverse!
   end
 
   def delete(key)
-    node = @data.delete(key)
-
-    return unless node
-
-    prev = node[0]
-    nex = node[3]
+    @data.delete(key)
+  end
 
-    nex  ? nex[0] = prev : @head = prev
-    prev ? prev[3] = nex : @tail = nex
+  alias_method :evict, :delete
 
-    node[2]
+  def key?(key)
+    @data.key?(key)
   end
 
+  alias_method :has_key?, :key?
+
   def clear
     @data.clear
-    @head = @tail = nil
   end
 
   def count
     @data.size
   end
 
-  # for cache validation only, ensures all is sound
-  def valid?
-    count = 0
-    self.each_unsafe do |k,v|
-      return false if @data[k][2] != v
-      count += 1
-    end
-    count == @data.size
-  end
-
   protected
 
-  def add_to_head(key,val)
-    if @head.nil?
-      @tail = @head = [nil,key,val,nil]
-    else
-      node = [@head,key,val,nil]
-      @head = @head[3] = node
-    end
-  end
-
-  def move_to_head(node)
-    return unless @head && node[1] != @head[1]
-
-    prev = node[0]
-    nex = node[3]
-
-    if prev
-      prev[3] = nex
-    else
-      @tail = nex
-    end
-
-    if nex
-      nex[0] = prev
-    end
-
-    @head[3] = node
-    node[0] = @head
-    @head = node
-  end
-
-  def pop_tail
-    if @data.length > @max_size
-      @data.delete(@tail[1])
-      @tail = @tail[3]
-      @tail[0] = nil
-      true
-    end
+  # for cache validation only, ensures all is sound
+  def valid?
+    true
   end
 end