ring_cache 1.0

data/.gitignore

@@ -0,0 +1,22 @@
+*.gem
+*.rbc
+.bundle
+.config
+.yardoc
+Gemfile.lock
+InstalledFiles
+_yardoc
+coverage
+doc/
+lib/bundler/man
+pkg
+rdoc
+spec/reports
+test/tmp
+test/version_tmp
+tmp
+*.bundle
+*.so
+*.o
+*.a
+mkmf.log

data/Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in ring_cache.gemspec
+gemspec

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2014 Alvaro Redondo
+
+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,88 @@
+# RingCache
+
+RingCache is an in-memory cache that emulates a ring buffer, in which older elements are evicted to make room for new ones. It is mostly useful in situations in which it is not worth it, or possible, to keep all accessed data in memory, and some elements are more frequently accessed than others.
+
+As a ring buffer, it can work with a fix capacity. In addition, it allows the possibility of specifying a target hit rate, above which it will evict the elements that were accessed last. This should make it easier to optimize the amount of memory used when the hit rate becomes insensitive to the capacity over a given threshold.
+
+## Installation
+
+RingCache does not have any dependency apart from Ruby.
+
+To install with Bundle, add the following line to the Gemfile:
+
+    gem 'ring_cache'
+
+And then execute:
+
+    $ bundle
+
+Otherwise, it can be installed with Rubygems as follows:
+
+    $ gem install ring_cache
+
+## Cache Initialization
+
+All options accepted by RingCache are set when initializing the cache.
+
+The options related to the cache size are:
+
+* `capacity`: The maximum number of elements that the cache will hold. By default, the capacity is unlimited.
+
+* `target_hit_rate`: The cache will keep on growing in size until this target is achieved. Then, it will evict elements to make room for new ones to maintain its current size—as long as the hit rate is kept over this threshold. If the hit rate falls below the threshold, the cache will increase its size again. Size is always limited by the `capacity` option. By default, there is no target hit rate.
+
+The following options allow some control over the stored data:
+
+* `duplicate_on_store` : Store a duplicate of the element obtained with `dup` rather than the element provided to the cache.
+* `duplicate_on_retrieve`: Return a duplicate of the accessed data rather than the accessed data itself.
+* `execute_on_retrieve`: Method or array of methods that should be executed on accessed data before returning it. This could be used, for example, to ensure that returned data is fresh.
+
+Initialization example:
+
+```ruby
+cache = RingCache.new(
+  capacity: 2_000,
+  target_hit_rate: 0.9,
+  execute_on_retrieve: :reload
+)
+```
+
+## Usage
+
+To access data, use the `read` and `write` methods:
+
+```ruby
+cache.write(:example, 'Lorem ipsum')
+test = cache.read(:example)
+# => "Lorem ipsum"
+```
+
+Both keys and values can be any data type.
+
+Use `fetch` as a shortcut to provide missing, more-costly-to-load data in a block:
+
+```ruby
+cache.fetch(:example) do
+  'Lorem ipsum'
+end
+# => "Lorem ipsum"
+```
+
+Use `evict` to remove an element from the cache:
+
+```ruby
+cache.evict(:example)
+# => true
+```
+
+And `reset` to completely erase the cache contents—while maintaining initialization options.
+
+There are other methods that just return information:
+
+* `has_key?(key)`: Returns true if the cache contains an element indexed by this key. Otherwise, false.
+* `hit_rate`: Current hit rate of the cache. This is a number between 0 and 1.
+* `last_access(key)`: Time when the element indexed by this key was last accessed.
+* `size`: Number of elements currently stored in the cache.
+
+## Contributing
+
+Please, fork the repository, make your changes, and submit a pull request. Thanks!

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/test*.rb']
+  t.verbose = true
+end

data/lib/ring_cache/version.rb

@@ -0,0 +1,3 @@
+class RingCache
+  VERSION = '1.0'
+end

data/lib/ring_cache.rb

@@ -0,0 +1,120 @@
+lib = File.dirname(__FILE__)
+$LOAD_PATH.unshift(lib) if File.directory?(lib) && !$LOAD_PATH.include?(lib)
+
+require 'ring_cache/version'
+require 'set'
+
+class RingCache
+  attr_reader :capacity, :target_hit_rate
+
+  def initialize(options = {})
+    @duplicate_on_store = options.fetch(:duplicate_on_store, false)
+    @duplicate_on_retrieve = options.fetch(:duplicate_on_retrieve, false)
+
+    execute_on_retrieve = options.fetch(:execute_on_retrieve, [])
+    @execute_on_retrieve = execute_on_retrieve.kind_of?(Array) ? execute_on_retrieve : [execute_on_retrieve]
+
+    @capacity = options.fetch(:capacity, nil)
+    @target_hit_rate = options.fetch(:target_hit_rate, nil)
+    unless @target_hit_rate.nil? or (@target_hit_rate > 0.0 and @target_hit_rate < 1.0)
+      raise ArgumentError, 'Invalid target_hit_rate'
+    end
+
+    reset
+  end
+
+  def evict(key)
+    if @cache.has_key?(key)
+      @access_time_index.delete([@cache[key][:last_accessed_at], key])
+      @cache.delete(key)
+      true
+    else
+      false
+    end
+  end
+
+  def fetch(key, &block)
+    unless (data = read(key))
+      data = block.call
+      write(key, data)
+    end
+    data
+  end
+
+  def has_key?(key)
+    @cache.has_key?(key)
+  end
+
+  def hit_rate
+    (@access_count > 0) ? (@hit_count / @access_count.to_f) : 0.0
+  end
+
+  def last_access(key)
+    has_key?(key) ? @cache[key][:last_accessed_at] : nil
+  end
+
+  def read(key)
+    @access_count += 1
+
+    if @cache.has_key?(key)
+      access_time = Time.now
+      @access_time_index.delete([@cache[key][:last_accessed_at], key])
+      @access_time_index << [access_time, key]
+      @cache[key][:last_accessed_at] = access_time
+
+      @hit_count += 1
+
+      data = @cache[key][:data]
+      data = data.dup if @duplicate_on_retrieve and !data.nil?
+
+      unless @execute_on_retrieve.empty? or data.nil?
+        @execute_on_retrieve.each do |method|
+          method = method.to_sym
+          if data.respond_to?(method)
+            data.send(method)
+          elsif data.kind_of?(Enumerable) and data.all? { |d| d.respond_to?(method) }
+            data.each { |d| d.send(method) }
+          else
+            raise RuntimeError, "Retrieved data does not respond to #{method.inspect}"
+          end
+        end
+      end
+
+      data
+    else
+      nil
+    end
+  end
+
+  def reset
+    @cache = {}
+    @access_time_index = SortedSet.new
+    @access_count = 0
+    @hit_count = 0
+    true
+  end
+
+  def size
+    @cache.size
+  end
+
+  def write(key, data)
+    evict_oldest if must_evict?
+    data = data.dup if @duplicate_on_store and !data.nil?
+    access_time = Time.now
+    @cache[key] = { last_accessed_at: access_time, data: data }
+    @access_time_index << [access_time, key]
+  end
+
+  private
+
+  def evict_oldest
+    access_time_index_entry = @access_time_index.first
+    @cache.delete(access_time_index_entry[1])
+    @access_time_index.delete(access_time_index_entry)
+  end
+
+  def must_evict?
+    (capacity and size >= capacity) or (target_hit_rate and hit_rate >= target_hit_rate)
+  end
+end

data/ring_cache.gemspec

@@ -0,0 +1,23 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'ring_cache/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = 'ring_cache'
+  spec.version       = RingCache::VERSION
+  spec.authors       = ['Alvaro Redondo']
+  spec.email         = ['alvaro@redondo.name']
+  spec.summary       = %q{In-memory cache that emulates a ring buffer.}
+  spec.description   = %q{RingCache is an in-memory cache that emulates a ring buffer, in which older elements are evicted to make room for new ones.}
+  spec.homepage      = 'https://github.com/aredondo/ring_cache'
+  spec.license       = 'MIT'
+
+  spec.files         = `git ls-files -z`.split("\x0")
+  spec.executables   = spec.files.grep(%r{^bin/}) { |f| File.basename(f) }
+  spec.test_files    = spec.files.grep(%r{^(test|spec|features)/})
+  spec.require_paths = ['lib']
+
+  spec.add_development_dependency 'bundler', '~> 1.6'
+  spec.add_development_dependency 'rake'
+end

data/test/random_data_generator.rb

@@ -0,0 +1,16 @@
+module RandomDataGenerator
+  private
+
+  def random_data(element_count, key_length)
+    data = []
+    letters = ('a' .. 'z').to_a
+
+    while data.size < element_count
+      key = letters.sample(key_length).join
+      content = letters.sample(1)
+      data << { key: key, content: content }
+    end
+
+    data
+  end
+end

data/test/test_helper.rb

@@ -0,0 +1,10 @@
+lib = File.expand_path('../lib', File.dirname(__FILE__))
+$LOAD_PATH.unshift(lib) if File.directory?(lib) && !$LOAD_PATH.include?(lib)
+
+require 'ring_cache'
+require 'minitest'
+require 'minitest/autorun'
+require 'minitest/reporters'
+require File.expand_path('random_data_generator', File.dirname(__FILE__))
+
+Minitest::Reporters.use! Minitest::Reporters::SpecReporter.new

data/test/test_ring_cache.rb

@@ -0,0 +1,186 @@
+#!/usr/bin/env ruby
+
+require File.expand_path('test_helper', File.dirname(__FILE__))
+
+class TestRingCache < Minitest::Test
+  include RandomDataGenerator
+
+  def test_generic_checks
+    c = RingCache.new(capacity: 3)
+    c.write(:a, 1)
+    assert_equal 0.0, c.hit_rate
+    assert_equal 1, c.read(:a)
+    assert_equal 1.0, c.hit_rate
+    assert c.has_key?(:a)
+    assert_kind_of Time, c.last_access(:a)
+    assert_equal 1, c.size
+    assert_equal 1, c.instance_variable_get(:@access_time_index).size
+
+    c.write(:b, 2)
+    assert_equal 2, c.read(:b)
+    assert_equal 1.0, c.hit_rate
+    assert c.has_key?(:b)
+    assert_kind_of Time, c.last_access(:b)
+    assert_equal 2, c.size
+    assert_equal 2, c.instance_variable_get(:@access_time_index).size
+
+    c.write(:c, 3)
+    assert_equal 3, c.read(:c)
+    assert_equal 1.0, c.hit_rate
+    assert c.has_key?(:c)
+    assert_kind_of Time, c.last_access(:c)
+    assert_equal 3, c.size
+    assert_equal 3, c.instance_variable_get(:@access_time_index).size
+
+    c.write(:d, 4)
+    assert_equal 4, c.read(:d)
+    assert_equal 1.0, c.hit_rate
+    assert c.has_key?(:d)
+    assert_kind_of Time, c.last_access(:d)
+    assert_equal 3, c.size
+    assert_equal 3, c.instance_variable_get(:@access_time_index).size
+    refute c.has_key?(:a)
+
+    value = c.fetch(:b) do
+      4
+    end
+    assert_equal 2, value
+    assert_equal 1.0, c.hit_rate
+
+    value = c.fetch(:e) do
+      5
+    end
+    assert_equal 5, value
+    assert_equal 3, c.size
+    assert_equal 3, c.instance_variable_get(:@access_time_index).size
+    refute c.has_key?(:c)
+    assert_equal 5 / 6.0, c.hit_rate
+
+    assert c.last_access(:b) > c.last_access(:d)
+    assert c.last_access(:d) < c.last_access(:e)
+
+    c.evict(:d)
+    refute c.has_key?(:d)
+    assert_equal 2, c.size
+    assert_equal 2, c.instance_variable_get(:@access_time_index).size
+
+    value = c.read(:another)
+    assert_equal 5 / 7.0, c.hit_rate
+
+    c.reset
+    assert_equal 0, c.size
+    assert_equal 0.0, c.hit_rate
+  end
+
+  def test_execute_method_on_retrieve
+    test_class = Class.new
+    test_class.class_eval do
+      attr_reader :reloaded
+      define_method(:inititalize) { @reloaded = false }
+      define_method(:reload) { @reloaded = true }
+    end
+
+    cache = RingCache.new(execute_on_retrieve: :reload)
+
+    data = test_class.new
+    refute data.reloaded
+    cache.write(:d1, data)
+    retrieved_data = cache.read(:d1)
+    assert retrieved_data.reloaded, retrieved_data.reloaded.inspect
+
+    data = [
+      test_class.new,
+      test_class.new,
+      test_class.new
+    ]
+    refute data.any? { |d| d.reloaded }
+    cache.write(:d2, data)
+    retrieved_data = cache.read(:d2)
+    assert retrieved_data.all? { |e| e.reloaded }, retrieved_data.inspect
+
+    data = Object.new
+    refute_respond_to data, :reloaded
+    cache.write(:d3, data)
+    assert_raises RuntimeError do
+      retrieved_data = cache.read(:d3)
+    end
+  end
+
+  def test_object_duplication_on_retrieve
+    c = RingCache.new(duplicate_on_retrieve: true)
+    data = {a: 1, b: 2, c: 3}
+    c.write(:d, data)
+    assert c.has_key?(:d)
+    retrieved_data = c.read(:d)
+    assert data == retrieved_data
+    refute data.equal?(retrieved_data)
+  end
+
+  def test_object_duplication_on_store
+    c = RingCache.new(duplicate_on_store: true)
+    data = {a: 1, b: 2, c: 3}
+    c.write(:d, data)
+    assert c.has_key?(:d)
+    retrieved_data = c.read(:d)
+    assert data == retrieved_data
+    refute data.equal?(retrieved_data)
+  end
+
+  def test_random_data
+    cache = RingCache.new(capacity: 1_000)
+    data = random_data(2_000, 10)
+
+    data.each do |element|
+      cache.fetch(element[:key]) do
+        element[:content]
+      end
+    end
+
+    assert_equal 1_000, cache.size
+    access_time_index = cache.instance_variable_get(:@access_time_index)
+    cache_contents = cache.instance_variable_get(:@cache)
+    assert_equal cache_contents.size, access_time_index.size
+
+    access_time_index.each do |access_time_index_entry|
+      assert cache_contents.has_key?(access_time_index_entry[1])
+      assert_equal access_time_index_entry[0],
+        cache_contents[access_time_index_entry[1]][:last_accessed_at]
+    end
+  end
+
+  def test_target_hit_rate
+    cache = RingCache.new(capacity: 4, target_hit_rate: 0.5)
+
+    cache.fetch(:a) { 1 }
+    cache.fetch(:b) { 2 }
+    cache.read(:a)
+    cache.read(:b)
+
+    assert_equal 0.5, cache.hit_rate
+    assert_equal 2, cache.size
+
+    cache.read(:a)
+    cache.read(:b)
+    cache.fetch(:c) { 3 }
+
+    assert_equal 4 / 7.0, cache.hit_rate
+    assert_equal 2, cache.size
+    assert cache.has_key?(:c)
+
+    cache.fetch(:d) { 4 }
+    assert_equal 4 / 8.0, cache.hit_rate
+    assert_equal 2, cache.size
+    assert cache.has_key?(:d)
+  end
+
+  def test_works_with_nil
+    cache = RingCache.new(
+      duplicate_on_store: true,
+      duplicate_on_retrieve: true,
+      execute_on_retrieve: :reload
+    )
+    data = nil
+    cache.write(:d, data)
+    assert_nil cache.read(:d)
+  end
+end

data/test/test_ring_cache_performance.rb

@@ -0,0 +1,52 @@
+#!/usr/bin/env ruby
+
+require File.expand_path('test_helper', File.dirname(__FILE__))
+require 'minitest/benchmark'
+
+class TestRingCachePerformance < Minitest::Benchmark
+  include RandomDataGenerator
+
+  def self.bench_range
+    bench_exp(100, 100_000, 10)
+  end
+
+  def setup
+    @data = random_data(1_000, 10)
+  end
+
+  # Computer-dependant -- but should be a reasonable baseline
+  def bench_performance
+    if ENV['BENCH']
+      validation = lambda { |ranges, times|
+        count_per_second = ranges.last / times.last.to_f
+        assert count_per_second > 100_000, 'Count per second: %.2f' % count_per_second
+      }
+
+      assert_performance validation do |n|
+        run_cache(n)
+      end
+    end
+  end
+
+  def bench_performance_linear
+    if ENV['BENCH']
+      assert_performance_linear do |n|
+        run_cache(n)
+      end
+    end
+  end
+
+  private
+
+  def run_cache(times, capacity = 1_000)
+    cache = RingCache.new(capacity: capacity)
+    count = 0
+    while count < times
+      element = @data.sample
+      cache.fetch(element[:key]) do
+        element[:content]
+      end
+      count += 1
+    end
+  end
+end

metadata

@@ -0,0 +1,95 @@
+--- !ruby/object:Gem::Specification
+name: ring_cache
+version: !ruby/object:Gem::Version
+  version: '1.0'
+  prerelease: 
+platform: ruby
+authors:
+- Alvaro Redondo
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2014-10-18 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '1.6'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '1.6'
+- !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'
+description: RingCache is an in-memory cache that emulates a ring buffer, in which
+  older elements are evicted to make room for new ones.
+email:
+- alvaro@redondo.name
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- .gitignore
+- Gemfile
+- LICENSE.txt
+- README.md
+- Rakefile
+- lib/ring_cache.rb
+- lib/ring_cache/version.rb
+- ring_cache.gemspec
+- test/random_data_generator.rb
+- test/test_helper.rb
+- test/test_ring_cache.rb
+- test/test_ring_cache_performance.rb
+homepage: https://github.com/aredondo/ring_cache
+licenses:
+- MIT
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 1.8.29
+signing_key: 
+specification_version: 3
+summary: In-memory cache that emulates a ring buffer.
+test_files:
+- test/random_data_generator.rb
+- test/test_helper.rb
+- test/test_ring_cache.rb
+- test/test_ring_cache_performance.rb