barking_iguana-cache_bucket 0.4.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: c90c21ce4ef8a040fa432ce3f00a5359388039da
-  data.tar.gz: 499b20e6a2c0bd512fc110a8fb6e2f61491d1008
+  metadata.gz: 37fb5d68814bf9fd29d3dfbe8edb21ae5ec08399
+  data.tar.gz: 44ae25e4af0c0e80625eec93b6737f8ca9e0fa7a
 SHA512:
-  metadata.gz: 8ee6d900f6a57a301115a604ddd4fd6cb0c23ef10e9bd9621491fa7b6677e0fd7de73c79c188019f21b8ec8446ea0837d6aa82fad094bdd3620df9d03294fa80
-  data.tar.gz: 17faf5648ae72761f58156c506b55965d50c40e170ed508db8827af80b57d680541a6077ee674d3bcb106b522e5b4819b32907d8eececb718441087174df2e92
+  metadata.gz: 80a3dca076566a9c5d3327b5e693769b6e77bd0f52f955744796c7aec502f3230ca5f136257116adeee4299050f984f539c820f5d0c2349f4c238ea79e3804a4
+  data.tar.gz: 819e4aa1809b29eb301556e78f63d17f90e99b21a6afc232e169496c1db1183ca0f3e230aaa28d15b261bb416d4fc4188078422feccf0e438d612e7232dc601f

data/README.md

@@ -1,8 +1,9 @@
 # BarkingIguana::CacheBucket
 
-Welcome to your new gem! In this directory, you'll find the files you need to be able to package up your Ruby library into a gem. Put your Ruby code in the file `lib/barking_iguana/cache_bucket`. To experiment with that code, run `bin/console` for an interactive prompt.
+Provides a naive but easy to set up cache with time based expiry.
 
-TODO: Delete this and the text above, and describe your gem
+Time based expiry in implemented as a maximum age that the cached objects _may_
+reach. It's not a guarantee that the objects _will_ live that long.
 
 ## Installation
 
@@ -22,7 +23,86 @@ Or install it yourself as:
 
 ## Usage
 
-TODO: Write usage instructions here
+Most likely you'll want to use the DSL in your class:
+
+```ruby
+require 'barking_iguana/cache_bucket'
+
+class Thing
+  include BarkingIguana::CacheBucket::DSL
+
+  def expensive_operation
+    cache_bucket.get 'expensive_operation' do
+      object_id
+    end
+  end
+end
+```
+
+**BEWARE!** The cache will persist across instances of the class:
+
+```ruby
+# Create two new instances of the class
+t1 = Thing.new
+t2 = Thing.new
+
+# These have different object ids:
+t1.object_id #=> 70248246472260
+t2.object_id #=> 70248259056820
+
+# But the same value is returned from both:
+t1.expensive_operation #=> 70248246472260
+t2.expensive_operation #=> 70248246472260
+```
+
+If you need `CacheBucket`s that are scoped to instances you should use a
+`prefix`:
+
+```ruby
+class ScopedThing
+  include BarkingIguana::CacheBucket::DSL
+
+  def expensive_operation
+    cache_bucket.get 'expensive_operation', prefix: "instance_#{id}" do
+      object_id
+    end
+  end
+end
+
+# Create two new instances of the class
+s1 = ScopedThing.new
+s2 = ScopedThing.new
+
+# These have different object ids:
+s1.object_id #=> 70248246472260
+s2.object_id #=> 70248259056820
+
+# Now a different value is returned from both:
+s1.expensive_operation #=> 70248246472260
+s2.expensive_operation #=> 70248259056820
+```
+
+### Configuration
+
+You may configure a few things about the behaviour of the `CacheBucket`s.
+
+#### Logging
+
+```ruby
+BarkingIguana::CacheBucket.logger = Logger.new($stdout)
+```
+
+It logs at `Logger::DEBUG`, so you won't see very much unless you crank the log
+level of your logger _way_ up.
+
+#### Cache Horizon
+
+The default is 3600 seconds - one hour. You can set it to any number of seconds
+though. Please note that I only support integer numbers of seconds.
+
+```ruby
+BarkingIguana::CacheBucket.maximum_age = 7200
+```
 
 ## Development
 
@@ -32,5 +112,5 @@ To install this gem onto your local machine, run `bundle exec rake install`. To
 
 ## Contributing
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/[USERNAME]/barking_iguana-cache_bucket.
+Bug reports and pull requests are welcome on GitHub at https://github.com/barking_iguana/cache_bucket.
 

data/barking_iguana-cache_bucket.gemspec

@@ -27,6 +27,7 @@ Gem::Specification.new do |spec|
   spec.require_paths = ["lib"]
 
   spec.add_dependency "null_logger"
+  spec.add_dependency "barking_iguana-otk", "~> 0.1.0"
   spec.add_development_dependency "bundler", "~> 1.11"
   spec.add_development_dependency "rake", "~> 10.0"
   spec.add_development_dependency "rspec", "~> 3.0"

data/lib/barking_iguana/cache_bucket.rb

@@ -1,18 +1,13 @@
+require "barking_iguana/otk/defaults"
 require "barking_iguana/cache_bucket/version"
 require "barking_iguana/cache_bucket/cache_bucket"
 require "barking_iguana/cache_bucket/dsl"
 
 module BarkingIguana
   module CacheBucket
-    class << self
-      attr_accessor :logger
-    end
-    self.logger = NullLogger.instance
-
-    class << self
-      attr_accessor :maximum_age
-    end
-    self.maximum_age = 3600
+    include Otk::Defaults
+    defaults logger: NullLogger.instance,
+             maximum_age: 3600
 
     def self.get name, options = {}
       buckets[name] ||= create_bucket name, options
@@ -29,5 +24,6 @@ module BarkingIguana
       o[:maximum_age] ||= maximum_age
       CacheBucket.new o
     end
+    private_class_method :create_bucket
   end
 end

data/lib/barking_iguana/cache_bucket/cache_bucket.rb

@@ -3,7 +3,9 @@ require 'null_logger'
 module BarkingIguana
   module CacheBucket
     class CacheBucket
+      SHARED_PREFIX = '##shared##'.freeze
       KEY_DIVIDER = '__'.freeze
+      MAXIMUM_AGE = 3600
 
       attr_accessor :maximum_age
       private :maximum_age=, :maximum_age
@@ -17,16 +19,16 @@ module BarkingIguana
       attr_accessor :cache
       private :cache=, :cache
 
-      def initialize maximum_age: 3600, logger: nil
+      def initialize maximum_age: MAXIMUM_AGE, logger: nil
         self.maximum_age = maximum_age.to_i
         self.logger = logger || NullLogger.instance
         self.cache = {}
       end
 
-      def get key
-        logger.debug { "Getting #{key}" }
+      def get key, prefix: SHARED_PREFIX
         evict_expired_keys
-        k = generation_key(key)
+        k = generation_key(key, prefix)
+        logger.debug { "Getting #{k.inspect} (key: #{key.inspect}, prefix: #{prefix.inspect})" }
         if cache.key? k
           logger.debug { "Key #{k.inspect} found in the cache" }
           cache[k].tap do |v|
@@ -43,10 +45,10 @@ module BarkingIguana
         end
       end
 
-      def set key, value
+      def set key, value, prefix: SHARED_PREFIX
         evict_expired_keys
-        k = generation_key(key)
-        logger.debug { "Setting value to #{value.inspect}" }
+        k = generation_key(key, prefix)
+        logger.debug { "Setting #{k.inspect} (key: #{key.inspect}, prefix: #{prefix.inspect}) to #{value.inspect}" }
         cache[k] = value
       end
 
@@ -68,10 +70,8 @@ module BarkingIguana
         Time.now.to_i / maximum_age
       end
 
-      def generation_key key
-        [ generation_id, key ].join(KEY_DIVIDER).tap do |k|
-          logger.debug { "Current generation key for #{key.inspect} is #{k.inspect}" }
-        end
+      def generation_key key, prefix
+        [ generation_id, prefix, key ].join(KEY_DIVIDER)
       end
     end
   end

data/lib/barking_iguana/cache_bucket/dsl.rb

@@ -1,5 +1,31 @@
 module BarkingIguana
   module CacheBucket
+    # Include this DSL in classes where you'd like to easily access a
+    # `CacheBucket` instance named after the class it's being included into.
+    #
+    # In each class and instance of that class you'll get access to a
+    # `cache_bucket` method to provide access to a `CacheBucket`.
+    #
+    #
+    #    class Example
+    #      def self.class_method
+    #        cache_bucket.get 'foo' do
+    #          'bar_set_in_class_method'
+    #        end
+    #      end
+    #
+    #      def instance_method
+    #        puts cache_bucket.get 'foo'
+    #      end
+    #    end
+    #
+    # Given the above class definition, here's some example output:
+    #
+    #    Example.class_method
+    #    Example.new.instance_method #=> 'bar_set_in_class_method'
+    #
+    # It's hard to imagine a place where you'll actually want to use the
+    # instance variable of this, and it may be removed in future releases.
     module DSL
       def self.included into
         into.extend ClassMethods
@@ -7,13 +33,15 @@ module BarkingIguana
       end
 
       module InstanceMethods
-        def class_cache options = {}
+        # Access the Cache Bucket for thisinstances class.
+        def cache_bucket options = {}
           BarkingIguana::CacheBucket.get self.class.name, options
         end
       end
 
       module ClassMethods
-        def class_cache options = {}
+        # Access the Cache Bucket for this class.
+        def cache_bucket options = {}
           BarkingIguana::CacheBucket.get name, options
         end
       end

data/lib/barking_iguana/cache_bucket/version.rb

@@ -1,5 +1,5 @@
 module BarkingIguana
   module CacheBucket
-    VERSION = "0.4.0"
+    VERSION = "0.5.0"
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: barking_iguana-cache_bucket
 version: !ruby/object:Gem::Version
-  version: 0.4.0
+  version: 0.5.0
 platform: ruby
 authors:
 - Craig R Webster
@@ -24,6 +24,20 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
+- !ruby/object:Gem::Dependency
+  name: barking_iguana-otk
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.1.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.1.0
 - !ruby/object:Gem::Dependency
   name: bundler
   requirement: !ruby/object:Gem::Requirement