cache_lib 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 49951bebe666d8d905c8cb74e5b1324f95f460da
+  data.tar.gz: eb58345e35655ea65121a69d22f6d936c9eae506
+SHA512:
+  metadata.gz: 51a1d55a39dbacf762ab5b1b58275de0018fb968d7b200e7dbddbed4f159e1f3691ebd96232999a484fcffc355f9703922f3bc3f43017dd66076a0ce5c48bd28
+  data.tar.gz: f38f39b35db8a674c052184ba4ee32e8b7c640d06f56574ef5d528f9c4e1356ae38610949b4329d55cf48cc370b00e5007296aeab4826f3df09a1d4ba6a45607

data/Gemfile

@@ -0,0 +1,3 @@
+source 'https://rubygems.org'
+
+gemspec

data/LICENSE.txt

@@ -0,0 +1,19 @@
+Copyright (c) 2015 Kaijah Hougham
+
+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/README.md

@@ -0,0 +1,122 @@
+# CacheLib
+#### A Ruby caching library implementing Basic, FIFO, LRU and LIRS caches.
+
+##### CacheLib is young library and breaking api changes are still possible.  Please read the release notes before upgrading.
+CacheLib currently implements basic, FIFO, LRU and LIRS caches along with offering thread safe implementations of each.  Originally a LIRS cache feature fork of [LruRedux](https://github.com/SamSaffron/lru_redux), CacheLib was built to provide a clean base for implementing the LIRS cache in Ruby, along with offering user friendly api.
+
+##### Basic:
+The basic cache is the simplest cache available and forms the base for the others.  It does NOT have an eviction strategy and will store however much it is given.
+
+##### FIFO:
+The FIFO cache adds to the basic cache with a simple First In First Our eviction strategy to limit the cache size to a user set limit.
+
+##### LRU:
+The LRU cache further adds to the previous caches with a Least Recently Used eviction strategy.  The primary difference between FIFO and LRU is that LRU will refresh currently cached items if they are requested again.
+
+##### LIRS:
+The LIRS cache implements the Low Inter-Reference Recency Set Replacement Policy developed by Song Jiang and Xiaodong Zhang.  Please reference the [original paper](http://citeseer.ist.psu.edu/viewdoc/summary?doi=10.1.1.116.2184) for more information.
+
+##### CacheLib is Ruby >= 1.9.3 only.
+If you are looking for a LRU cache that supports an earlier version or just want an alternative LRU cache, please take a look at [LruRedux](https://github.com/SamSaffron/lru_redux).
+
+## Usage
+### Creating a cache
+```ruby
+require 'cache_lib'
+
+# Basic
+cache = CacheLib.create :basic
+
+# FIFO with a limit of 100
+cache = CacheLib.create :fifo, 100
+
+# LRU with a limit of 100
+cache = CacheLib.create :lru, 100
+
+# LIRS with a cache limit of 100, made up of a S limit of 95 and a Q limit of 5.
+cache = CacheLib.create :lirs, 95, 5
+```
+
+### Using the cache
+```ruby
+# Cache methods remain the same across all variations
+cache = CacheLib.create :lru, 100
+
+# .get is the primary method for accessing the cache.  It requires a key and block that will generate the value that is stored if the key is not cached.
+cache.get(:a) { 'Apple' }
+# => 'Apple'
+cache.get(:b) { 'Beethoven' }
+# => 'Beethoven'
+cache.get(:a) { 'Apricot' }
+# => 'Apple'
+
+# .store takes a key and value and implements the functionality of Hash#store. Will refresh the key in LRU and LIRS caches.
+cache.store(:c, 'Chopin')
+# => 'Chopin'
+cache.store(:a, 'Mozart')
+# => 'Mozart'
+
+# []= is equivalent to .store.
+cache[:d] = 'Denmark'
+# => 'Denmark'
+
+# .lookup takes a key and returns either the value if the key is cached or nil if it is not.
+cache.lookup(:c)
+# => 'Chopin'
+cache.lookup(:t)
+# => nil
+
+# [] is equivalent to .lookup.
+cache[:a]
+# => 'Mozart'
+
+# .fetch is similar to .lookup, but takes an optional block that will execute if the key is not cached.
+cache.fetch(:c)
+# => 'Chopin'
+cache.fetch(:r) { 21 * 2 }
+# => 42
+
+# .evict takes a key and will remove the key from the cache and return the associated value.  Returns nil is the key is not cached.
+cache.evict(:d)
+# => 'Denmark'
+cache.evict(:r)
+# => nil
+
+# .each takes each key value pair and applies the given block to them.
+cache.each { |_, value| puts value }
+# => 'Chopin'
+# => 'Mozart'
+# => 'Beethoven'
+
+# .key? takes a key and returns true if it is cached and false if it is not.
+cache.key?(:a)
+# => true
+cache.key?(:g)
+# => false
+
+# .to_a returns an array of arrays of key value pairs that are cached.  Basic, FIFO and LIRS are insertion ordered while LRU is recency ordered, starting with newest.
+cache.to_a
+# => [[:c, 'Chopin'], [:a, 'Mozart'], [:b, 'Beethoven']]
+
+# .keys returns an array of the keys that are cached.
+cache.keys
+# => [:c, :a, :b]
+
+# .values returns an array of the values that are cached.
+cache.values
+# => ['Chopin', 'Mozart', 'Beethoven']
+
+# .size returns the current number of items that are cached.
+cache.size
+# => 3
+
+# .clear removes all items from the cache.
+cache.clear
+# => nil
+```
+
+## Copyright
+
+Copyright (c) 2015 Kaijah Hougham
+
+See [LICENSE.txt](LICENSE.txt) for details.

data/Rakefile

@@ -0,0 +1,8 @@
+require 'bundler/gem_tasks'
+require 'rake/testtask'
+
+Rake::TestTask.new do |t|
+  t.libs << 'test'
+  t.test_files = FileList['test/cache_lib/test*.rb']
+  t.verbose = true
+end

data/cache_lib.gemspec

@@ -0,0 +1,25 @@
+# -*- encoding: utf-8 -*-
+
+require File.expand_path('../lib/cache_lib/version', __FILE__)
+
+Gem::Specification.new do |gem|
+  gem.name          = 'cache_lib'
+  gem.version       = CacheLib::VERSION
+  gem.summary       = 'A Ruby Caching Library'
+  gem.description   = 'A Ruby caching library implementing Basic, FIFO, LRU and LIRS caching strategies.'
+  gem.license       = 'MIT'
+  gem.authors       = 'Kaijah Hougham'
+  gem.email         = 'github@seberius.com'
+  gem.homepage      = 'https://github.com/seberius/cache_lib'
+
+  gem.required_ruby_version = '>= 1.9.3'
+
+  gem.files         = `git ls-files`.split($RS)
+  gem.executables   = gem.files.grep(/bin/).map { |f| File.basename(f) }
+  gem.test_files    = gem.files.grep(/test/)
+  gem.require_paths = ['lib']
+
+  gem.add_development_dependency 'bundler', '~> 1.7'
+  gem.add_development_dependency 'rake', '~> 10'
+  gem.add_development_dependency 'minitest', '~> 5.0'
+end

data/lib/cache_lib/basic_cache.rb

@@ -0,0 +1,109 @@
+module CacheLib
+  class BasicCache
+    attr_reader :limit
+
+    def initialize
+      @limit = nil
+
+      @cache = UtilHash.new
+    end
+
+    def initialize_copy(source)
+      source_raw = source.raw
+
+      @limit = source_raw[:limit]
+
+      @cache = source_raw[:cache]
+    end
+
+    def limit=(_)
+      @limit = nil
+    end
+
+    def get(key)
+      value = hit(key)
+
+      if value
+        value
+      else
+        miss(key, yield)
+      end
+    end
+
+    def store(key, value)
+      miss(key, value)
+    end
+
+    def lookup(key)
+      @cache[key]
+    end
+
+    def fetch(key)
+      has_key = true
+      value = @cache.fetch(key) { has_key = false }
+
+      if has_key
+        value
+      else
+        yield if block_given?
+      end
+    end
+
+    def evict(key)
+      @cache.delete(key)
+    end
+
+    def clear
+      @cache.clear
+      nil
+    end
+
+    def each
+      @cache.each do |pair|
+        yield pair
+      end
+    end
+
+    def key?(key)
+      @cache.key?(key)
+    end
+
+    def to_a
+      @cache.to_a.reverse!
+    end
+
+    def keys
+      @cache.keys.reverse!
+    end
+
+    def values
+      @cache.values.reverse!
+    end
+
+    def size
+      @cache.size
+    end
+
+    def raw
+      { limit: @limit,
+        cache: @cache.clone }
+    end
+
+    def inspect
+      "#{self.class} currently caching #{@cache.size} items."
+    end
+
+    alias_method :[], :lookup
+    alias_method :[]=, :store
+
+    protected
+
+    def hit(key)
+      @cache[key]
+    end
+
+    def miss(key, value)
+      @cache[key] = value
+    end
+  end
+end

data/lib/cache_lib/fifo_cache.rb

@@ -0,0 +1,46 @@
+module CacheLib
+  class FifoCache < BasicCache
+    def initialize(*args)
+      limit, _ = args
+
+      fail ArgumentError "Cache Limit must be 1 or greater: #{limit}" if
+          limit.nil? || limit < 1
+
+      @limit = limit
+
+      @cache = UtilHash.new
+    end
+
+    def limit=(args)
+      limit, _ = args
+      fail ArgumentError "Cache Limit must be 1 or greater: #{limit}" if
+          limit.nil? || limit < 1
+
+      @limit = limit
+
+      resize
+    end
+
+    def inspect
+      "#{self.class} with a limit of #{@limit} "\
+      "currently caching #{@cache.size} items."
+    end
+
+    alias_method :[], :lookup
+    alias_method :[]=, :store
+
+    protected
+
+    def resize
+      @cache.delete(@cache.tail) while @cache.size > @limit
+    end
+
+    def miss(key, value)
+      @cache[key] = value
+
+      @cache.pop_tail if @cache.size > @limit
+
+      value
+    end
+  end
+end

data/lib/cache_lib/lirs_cache.rb

@@ -0,0 +1,214 @@
+module CacheLib
+  class LirsCache < BasicCache
+    def initialize(*args)
+      s_limit, q_limit = args
+
+      fail ArgumentError 'S Limit must be 1 or greater.' if
+          s_limit.nil? || s_limit < 1
+      fail ArgumentError 'Q Limit must be 1 or greater.' if
+          q_limit.nil? || q_limit < 1
+
+      @s_limit = s_limit
+      @q_limit = q_limit
+      @limit = s_limit + q_limit
+
+      @cache = UtilHash.new
+      @stack = UtilHash.new
+      @queue = UtilHash.new
+    end
+
+    def initialize_copy(source)
+      source_raw = source.raw
+
+      @limit = source_raw[:limit]
+      @s_limit = source_raw[:s_limit]
+      @q_limit = source_raw[:q_limit]
+
+      @cache = source_raw[:cache]
+      @stack = source_raw[:stack]
+      @queue = source_raw[:queue]
+    end
+
+    def limit=(args)
+      s_limit, q_limit = args
+
+      fail ArgumentError 'S Limit must be 1 or greater.' if
+          s_limit.nil? || s_limit < 1
+      fail ArgumentError 'Q Limit must be 1 or greater.' if
+          q_limit.nil? || q_limit < 1
+
+      @s_limit = s_limit
+      @q_limit = q_limit
+      @limit = s_limit + q_limit
+
+      resize
+    end
+
+    def get(key)
+      if @cache.key?(key)
+        hit(key)
+      else
+        miss(key, yield)
+      end
+    end
+
+    def store(key, value)
+      if @cache.key?(key)
+        @cache[key] = value
+        hit(key)
+      else
+        miss(key, value)
+      end
+    end
+
+    def lookup(key)
+      hit(key) if @cache.key?(key)
+    end
+
+    def fetch(key)
+      if @cache.key?(key)
+        hit(key)
+      else
+        yield if block_given?
+      end
+    end
+
+    def evict(key)
+      return unless @cache.key?(key)
+
+      value = @cache.delete(key)
+
+      if @queue.key?(key)
+        @queue.delete(key)
+      else
+        promote_hir if @queue.size > 0
+
+        trim_stack
+      end
+
+      value
+    end
+
+    def clear
+      @cache.clear
+      @stack.clear
+      @queue.clear
+      nil
+    end
+
+    def raw
+      { limit: @limit,
+        s_limit: @s_limit,
+        q_limit: @q_limit,
+        cache: @cache.clone,
+        stack: @stack.clone,
+        queue: @queue.clone }
+    end
+
+    def inspect
+      "#{self.class} with a limit of #{@limit}, "\
+      "s_limit of #{@s_limit} and q_limit of #{@q_limit} "\
+      "currently caching #{@cache.size} items."
+    end
+
+    alias_method :[], :lookup
+    alias_method :[]=, :store
+
+    protected
+
+    def trim_stack
+      s_tail = @stack.tail
+      while @queue.key?(s_tail) || !@cache.key?(s_tail)
+        @stack.delete(s_tail)
+        s_tail = @stack.tail
+      end
+    end
+
+    def promote_hir
+      key = @queue.head
+
+      @stack.set_tail(key, nil) unless @stack.key?(key)
+      @queue.delete(key)
+    end
+
+    def pop_tail
+      key = @queue.tail
+
+      @queue.delete(key)
+      @cache.delete(key)
+    end
+
+    def pop_stack
+      key = @stack.tail
+
+      @cache.delete(key)
+      trim_stack
+    end
+
+    def demote_lir
+      key = @stack.tail
+
+      @stack.delete(key)
+      @queue.set_head(key, nil)
+      trim_stack
+    end
+
+    def resize
+      s_size = 0
+
+      @stack.each do |key, _|
+        s_size += 1 if @cache.key?(key) && !@queue.key?(key)
+      end
+
+      promote_hir while (s_size < @s_limit && @queue.size > 0) && s_size += 1
+      pop_tail while @queue.size > 0 && @cache.size > @limit
+      pop_stack while @cache.size > @limit && s_size -= 1
+      demote_lir while s_size > @s_limit && s_size -= 1
+    end
+
+    def hit(key)
+      value = @cache[key]
+
+      if @stack.key?(key)
+        if @queue.key?(key)
+          @stack.refresh(key)
+          @queue.delete(key)
+
+          demote_lir
+        else
+          s_tail_key = @stack.tail
+          @stack.refresh(key)
+
+          trim_stack if s_tail_key == key
+        end
+      else
+        @stack.set_head(key, nil)
+        @queue.refresh(key)
+      end
+
+      value
+    end
+
+    def miss(key, value)
+      if @cache.size < @s_limit
+        @cache[key] = value
+        @stack.set_head(key, nil)
+      else
+        pop_tail if @queue.size >= @q_limit
+
+        @cache[key] = value
+
+        if @stack.key?(key)
+          @stack.refresh(key)
+
+          demote_lir
+        else
+          @stack.set_head(key, nil)
+          @queue.set_head(key, nil)
+        end
+      end
+
+      value
+    end
+  end
+end

data/lib/cache_lib/lru_cache.rb

@@ -0,0 +1,82 @@
+module CacheLib
+  class LruCache < BasicCache
+    def initialize(*args)
+      limit, _ = args
+
+      fail ArgumentError "Cache Limit must be 1 or greater: #{limit}" if
+          limit.nil? || limit < 1
+
+      @limit = limit
+
+      @cache = UtilHash.new
+    end
+
+    def limit=(args)
+      limit, _ = args
+
+      fail ArgumentError "Cache Limit must be 1 or greater: #{limit}" if
+          limit.nil? || limit < 1
+
+      @limit = limit
+
+      resize
+    end
+
+    def get(key)
+      has_key = true
+      value = @cache.delete(key) { has_key = false }
+      if has_key
+        @cache[key] = value
+      else
+        miss(key, yield)
+      end
+    end
+
+    def store(key, value)
+      @cache.delete(key)
+      miss(key, value)
+    end
+
+    def lookup(key)
+      has_key = true
+      value = @cache.delete(key) { has_key = false }
+      @cache[key] = value if has_key
+    end
+
+    def fetch(key)
+      has_key = true
+      value = @cache.delete(key) { has_key = false }
+      if has_key
+        @cache[key] = value
+      else
+        yield if block_given?
+      end
+    end
+
+    def inspect
+      "#{self.class} with a limit of #{@limit} "\
+      "currently caching #{@cache.size} items."
+    end
+
+    alias_method :[], :lookup
+    alias_method :[]=, :store
+
+    protected
+
+    def resize
+      @cache.pop_tail while @cache.size > @limit
+    end
+
+    def hit(key)
+      @cache.refresh(key)
+    end
+
+    def miss(key, value)
+      @cache[key] = value
+
+      @cache.pop_tail if @cache.size > @limit
+
+      value
+    end
+  end
+end

data/lib/cache_lib/safe_basic_cache.rb

@@ -0,0 +1,7 @@
+require_relative 'safe_sync'
+
+module CacheLib
+  class SafeBasicCache < BasicCache
+    include SafeSync
+  end
+end

data/lib/cache_lib/safe_fifo_cache.rb

@@ -0,0 +1,7 @@
+require_relative 'safe_sync'
+
+module CacheLib
+  class SafeFifoCache < FifoCache
+    include SafeSync
+  end
+end

data/lib/cache_lib/safe_lirs_cache.rb

@@ -0,0 +1,7 @@
+require_relative 'safe_sync'
+
+module CacheLib
+  class SafeLirsCache < LirsCache
+    include SafeSync
+  end
+end

data/lib/cache_lib/safe_lru_cache.rb

@@ -0,0 +1,7 @@
+require_relative 'safe_sync'
+
+module CacheLib
+  class SafeLruCache < LruCache
+    include SafeSync
+  end
+end