ring_cache 1.0.1 → 1.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 19d4ddc995312c013a62b2634e04ab59c94ddd64
+  data.tar.gz: 8a1e8b35a96a5354136eaff89d2ecc7e8e937a53
+SHA512:
+  metadata.gz: d8eeba522cb421e174bbb2e64b551bc2794102b3d6a1d17dd8f377bb94ce582c21432aaa3ad4ef334cadd60cf467795570a3a5b0f40df5e5f87c65317d96badd
+  data.tar.gz: 81fe4a6ab3590fdeb59074fe46893d51cb8b77d895a3c088502b3975130f5de13ac44fb44b3e34c8996c96b581392bea249af04a0db7aae30a9f400c684bad7a

data/README.md

@@ -2,11 +2,11 @@
 
 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.
+As a ring buffer, it can work with a limited capacity. In addition, it allows the possibility of specifying a target hit rate, above which it will evict the elements that have not been accessed the longest. 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—read [Pareto principle](https://en.wikipedia.org/wiki/Pareto_principle).
 
 ## Installation
 
-RingCache does not have any dependency apart from Ruby.
+RingCache does not have any dependency apart from Ruby Standard Library.
 
 To install with Bundle, add the following line to the Gemfile:
 
@@ -22,9 +22,7 @@ Otherwise, it can be installed with Rubygems as follows:
 
 ## Cache Initialization
 
-All options accepted by RingCache are set when initializing the cache.
-
-The options related to the cache size are:
+RingCache accepts the following options to configure the size of the cache:
 
 * `capacity`: The maximum number of elements that the cache will hold. By default, the capacity is unlimited.
 
@@ -58,6 +56,8 @@ test = cache.read(:example)
 
 Both keys and values can be any data type.
 
+The `read` method returns `nil` by default when the cache does not contain the requested key. Alternatively, `read!` raises a `RingCache::KeyNotFoundError` exception when the requested element is not in the cache.
+
 Use `fetch` as a shortcut to provide missing, more-costly-to-load data in a block:
 
 ```ruby
@@ -67,6 +67,30 @@ end
 # => "Lorem ipsum"
 ```
 
+By default, `fetch` will cache anything returned from the block. The option `cache_nil` allows specifying whether `nil` values should also be cache, and defaults to `true`:
+
+```ruby
+cache.fetch(:example, cache_nil: false) do
+  nil
+end
+# => nil
+
+cache.has_key?(:example)
+# => false
+```
+
+If already within the block it is determined that the returned content should not be cached, it is possible to throw a `:dont_cache` symbol. Optionally, the symbol can be accompanied by the value that should be returned from the block—while not cached:
+
+```ruby
+cache_fetch(:example) do
+  throw :dont_cache, true
+end
+# => true
+
+cache.has_key?(:example)
+# => false
+```
+
 Use `evict` to remove an element from the cache:
 
 ```ruby

data/Rakefile

@@ -6,3 +6,15 @@ Rake::TestTask.new do |t|
   t.test_files = FileList['test/test*.rb']
   t.verbose = true
 end
+
+task :environment do
+  require_relative 'lib/ring_cache'
+end
+
+desc 'Start a console with library loaded'
+task :console => :environment do
+  require 'irb'
+  require 'irb/completion'
+  ARGV.clear
+  IRB.start
+end

data/lib/ring_cache/key_not_found_error.rb

@@ -0,0 +1,2 @@
+class RingCache::KeyNotFoundError < RuntimeError
+end

data/lib/ring_cache/version.rb

@@ -1,3 +1,3 @@
 class RingCache
-  VERSION = '1.0.1'
+  VERSION = '1.1'
 end

data/lib/ring_cache.rb

@@ -1,7 +1,5 @@
-lib = File.dirname(__FILE__)
-$LOAD_PATH.unshift(lib) if File.directory?(lib) && !$LOAD_PATH.include?(lib)
-
-require 'ring_cache/version'
+require_relative 'ring_cache/key_not_found_error'
+require_relative 'ring_cache/version'
 require 'set'
 
 class RingCache
@@ -33,10 +31,15 @@ class RingCache
     end
   end
 
-  def fetch(key, &block)
+  def fetch(key, options = {}, &block)
+    cache_nil = options.fetch(:cache_nil, true)
+
     unless (data = read(key))
-      data = block.call
-      write(key, data)
+      data = catch(:dont_cache) do
+        data_to_cache = block.call
+        write(key, data_to_cache) unless data_to_cache.nil? and !cache_nil
+        data_to_cache
+      end
     end
     data
   end
@@ -53,7 +56,7 @@ class RingCache
     has_key?(key) ? @cache[key][:last_accessed_at] : nil
   end
 
-  def read(key)
+  def read!(key)
     @access_count += 1
 
     if @cache.has_key?(key)
@@ -82,10 +85,16 @@ class RingCache
 
       data
     else
-      nil
+      fail KeyNotFoundError, "Cache does not have content indexed by #{key}"
     end
   end
 
+  def read(key)
+    read!(key)
+  rescue KeyNotFoundError
+    return nil
+  end
+
   def reset
     @cache = {}
     @access_time_index = SortedSet.new

data/ring_cache.gemspec

@@ -20,4 +20,6 @@ Gem::Specification.new do |spec|
 
   spec.add_development_dependency 'bundler', '~> 1.6'
   spec.add_development_dependency 'rake'
+  spec.add_development_dependency 'minitest'
+  spec.add_development_dependency 'minitest-reporters'
 end

data/test/test_helper.rb

@@ -1,7 +1,4 @@
-lib = File.expand_path('../lib', File.dirname(__FILE__))
-$LOAD_PATH.unshift(lib) if File.directory?(lib) && !$LOAD_PATH.include?(lib)
-
-require 'ring_cache'
+require_relative '../lib/ring_cache'
 require 'minitest'
 require 'minitest/autorun'
 require 'minitest/reporters'

data/test/test_ring_cache.rb

@@ -72,6 +72,45 @@ class TestRingCache < Minitest::Test
     assert_equal 0.0, c.hit_rate
   end
 
+  def test_dont_cache_throw
+    cache = RingCache.new
+
+    value = cache.fetch(:a) do
+      throw :dont_cache, [1, 2, 3]
+    end
+    assert_equal [1, 2, 3], value
+    refute cache.has_key?(:a)
+
+    value = cache.fetch(:a) do
+      throw :dont_cache
+    end
+    assert_nil value
+    refute cache.has_key?(:a)
+
+    value = cache.fetch(:a) do
+      [1, 2, 3]
+    end
+    assert cache.has_key?(:a)
+    assert_equal [1, 2, 3], value
+    assert_equal [1, 2, 3], cache.read(:a)
+  end
+
+  def test_read_excl
+    c = RingCache.new
+    assert_raises RingCache::KeyNotFoundError do
+      c.read!(:nope)
+    end
+
+    c.write(:nope, 1)
+    begin
+      c.read!(:nope)
+    rescue RingCache::KeyNotFoundError
+      assert false, 'RingCache::KeyNotFoundError exception raised'
+    end
+
+    assert_equal 1, c.read!(:nope)
+  end
+
   def test_execute_method_on_retrieve
     test_class = Class.new
     test_class.class_eval do
@@ -180,8 +219,23 @@ class TestRingCache < Minitest::Test
       duplicate_on_retrieve: true,
       execute_on_retrieve: :reload
     )
-    data = nil
-    cache.write(:d, data)
+
+    cache.write(:d, nil)
+    assert cache.has_key?(:d)
     assert_nil cache.read(:d)
+
+    data = cache.fetch(:e) { nil }
+    assert_nil data
+    assert cache.has_key?(:e)
+    assert_nil cache.read(:e)
+
+    data = cache.fetch(:f, cache_nil: true) { nil }
+    assert_nil data
+    assert cache.has_key?(:f)
+    assert_nil cache.read(:f)
+
+    data = cache.fetch(:g, cache_nil: false) { nil }
+    assert_nil data
+    refute cache.has_key?(:g)
   end
 end

metadata

@@ -1,46 +1,69 @@
 --- !ruby/object:Gem::Specification
 name: ring_cache
 version: !ruby/object:Gem::Version
-  version: 1.0.1
-  prerelease: 
+  version: '1.1'
 platform: ruby
 authors:
 - Alvaro Redondo
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2014-10-20 00:00:00.000000000 Z
+date: 2015-06-20 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'
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: minitest-reporters
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
       - !ruby/object:Gem::Version
         version: '0'
 description: RingCache is an in-memory cache that emulates a ring buffer, in which
@@ -51,12 +74,13 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
-- .gitignore
+- ".gitignore"
 - Gemfile
 - LICENSE.txt
 - README.md
 - Rakefile
 - lib/ring_cache.rb
+- lib/ring_cache/key_not_found_error.rb
 - lib/ring_cache/version.rb
 - ring_cache.gemspec
 - test/random_data_generator.rb
@@ -67,27 +91,26 @@ files:
 homepage: https://github.com/aredondo/ring_cache
 licenses:
 - MIT
+metadata: {}
 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
+rubygems_version: 2.4.5
 signing_key: 
-specification_version: 3
+specification_version: 4
 summary: In-memory cache that emulates a ring buffer.
 test_files:
 - test/random_data_generator.rb