garner 0.2.1 → 0.3.0

data/README.md

@@ -24,7 +24,7 @@ To cache a value, invoke `cache` from within your API. Without any parameters it
 ``` ruby
 get "/" do
   cache do
-    { :counter => 42 }
+    { counter: 42 }
   end
 end
 ```
@@ -34,7 +34,7 @@ To enable support for the date-based `If-Modified-Since` and the ETag-based `If-
 ``` ruby
 get "/" do
   cache_or_304 do
-    { :counter => 42 }
+    { counter: 42 }
   end
 end
 ```
@@ -43,7 +43,7 @@ The cached value can also be bound to other models. For example, if a user has a
 
 ``` ruby
 get "/me/address" do
-  cache_or_304({ :bind => [ User, current_user.id ] }) do
+  cache_or_304({ bind: [ User, current_user.id ] }) do
     current_user.address
   end
 end
@@ -144,6 +144,31 @@ Available Key Strategies
 * `Garner::Strategies::Keys::RequestGet` inserts the value of HTTP request's GET parameters into the cache key when `:request` is present in the context.
 * `Garner::Strategies::Keys::RequestPath` inserts the value of the HTTP request's path into the cache key when `:request` is present in the context.
 
+Fetching Objects Directly from Cache
+------------------------------------
+
+Garner supports fetching objects or collections of objects directly from cache by supplying a binding or an array of bindings.
+
+``` ruby
+object_id = ...
+Garner::Cache::ObjectIdentity.cache({ bind: [ Model, { id: object_id }] }) do
+  Model.find(object_id)
+end
+```
+
+Various cache stores, including Memcached, support bulk read operations. The [Dalli gem](https://github.com/mperham/dalli) exposes this via the `read_multi` method. When invoked with a collection of bindings, Garner will call `read_multi` if available. This may significantly reduce the number of network roundtrips to the cache servers.
+
+``` ruby
+object_ids = [ ... ]
+bindings = object_ids.map do |object_id|
+  { bind: [ Model, { id: object_id }]}
+end
+Garner::Cache::ObjectIdentity.cache_multi(bindings) do |binding|
+  # the object binding is passed into the block for every cache miss
+  Model.find(binding[:bind][1][:id])
+end
+```
+
 Configuration
 -------------
 

data/lib/garner/cache/object_identity.rb

@@ -31,7 +31,7 @@ module Garner
     # `bind: [{ klass: Artwork }, { klass: User, object: { id: current_user.id } }]`
     #
     module ObjectIdentity
-      
+
       IDENTITY_FIELDS = [ :id ]
 
       KEY_STRATEGIES = [
@@ -40,39 +40,45 @@ module Garner
         Garner::Strategies::Keys::RequestPath,
         Garner::Strategies::Keys::RequestGet
       ]
-      
+
       CACHE_STRATEGIES = [
         Garner::Strategies::Cache::Expiration
       ]
 
       ETAG_STRATEGY = Garner::Strategies::ETags::Grape
-      
+
       class << self
 
         # cache the result of an executable block
-        def cache(binding = nil, context = {})
-          # apply cache strategies
-          cache_options = cache_options(context)
-          CACHE_STRATEGIES.each do |strategy|
-            cache_options = strategy.apply(cache_options)
-          end
-          key = key(binding, key_context(context))
-          result = Garner.config.cache.fetch(key, cache_options) do
-            object = yield
-            reset_cache_metadata(key, object)
-            object
+        def cache(binding = nil, context = {}, &block)
+          cache_options = apply_cache_options(context)
+          ctx = key_context(context)
+          fetch(key(binding, ctx), nil, cache_options, &block)
+        end
+
+        # cache a collection of results
+        def cache_multi(bindings, context = {}, &block)
+          cache_options = apply_cache_options(context)
+          ctx = key_context(context)
+          keys = bindings.map do |binding|
+            key(binding, ctx)
+          end
+          # attempt to do a read_multi if the cache supports it
+          local_cache = keys.size > 1 && Garner.config.cache.respond_to?(:read_multi) ? Garner.config.cache.read_multi(keys) : {}
+          # fetch all missing values
+          bindings.each_with_index.map do |binding, index|
+            key = keys[index]
+            local_cache[key] || fetch(key, binding, cache_options, &block)
           end
-          Garner.config.cache.delete(key) unless result
-          result
         end
-                
+
         # invalidate an object that has been cached
         def invalidate(* args)
           options = index(*args)
           reset_key_prefix_for(options[:klass], options[:object])
           reset_key_prefix_for(options[:klass]) if options[:object]
         end
-        
+
         # metadata for cached objects:
         #   :etag - Unique hash of object content
         #   :last_modified - Timestamp of last modification event
@@ -80,14 +86,28 @@ module Garner
           key = key(binding, key_context(context))
           Garner.config.cache.read(meta(key))
         end
-        
+
         private
 
+          def fetch(key, binding, cache_options = {}, &block)
+            result = Garner.config.cache.fetch(key, cache_options) do
+              object = binding ? yield(binding) : yield
+              reset_cache_metadata key, object
+              object
+            end
+            Garner.config.cache.delete(key) unless result
+            result
+          end
+
           # applied cache options
-          def cache_options(context)
-            context[:cache_options] || {}
+          def apply_cache_options(context)
+            cache_options = context[:cache_options] || {}
+            CACHE_STRATEGIES.each do |strategy|
+              cache_options = strategy.apply(cache_options)
+            end
+            cache_options
           end
-        
+
           # applied key context
           def key_context(context)
             new_context = {}
@@ -111,11 +131,11 @@ module Garner
             meta_key = meta(key)
             Garner.config.cache.write(meta_key, metadata)
           end
-  
+
           def new_key_prefix_for(klass, object = nil)
             Digest::MD5.hexdigest("#{klass}/#{object || "*"}:#{new_key_postfix}")
           end
-           
+
           # Generate a key in the Klass/id format.
           # @example Widget/id=1,Gadget/slug=forty-two,Fudget/*
           def key(binding = nil, context = {})
@@ -131,7 +151,7 @@ module Garner
               KEY_STRATEGIES.map { |strategy| context[strategy.field] }.compact.join("\n")
             )
           end
-        
+
           # Generate an index key from args
           def index(* args)
             case args[0]
@@ -150,7 +170,7 @@ module Garner
               raise ArgumentError, "invalid args, must be (klass, identifier) or hash (#{args})"
             end
           end
-               
+
           def find_or_create_key_prefix_for(klass, object = nil)
             Garner.config.cache.fetch(index_string_for(klass, object), {}) do
               new_key_prefix_for(klass, object)
@@ -160,7 +180,7 @@ module Garner
           def new_key_prefix_for(klass, object = nil)
             Digest::MD5.hexdigest("#{klass}/#{object || "*"}:#{new_key_postfix}")
           end
-          
+
           def new_key_postfix
             SecureRandom.respond_to?(:uuid) ? SecureRandom.uuid : (0...16).map{ ('a'..'z').to_a[rand(26)] }.join
           end
@@ -175,7 +195,7 @@ module Garner
               nil
             end
           end
-          
+
           # Generate a metadata key.
           def meta(key)
             "#{key}:meta"
@@ -195,7 +215,7 @@ module Garner
               raise ArgumentError, "invalid argument type #{ary[0].class} in :bind (#{ary[0]})"
             end
           end
-          
+
           def index_string_for(klass, object = nil)
             prefix = "INDEX"
             IDENTITY_FIELDS.each do |field|
@@ -205,7 +225,7 @@ module Garner
             end
             "#{prefix}:#{klass}/*"
           end
-          
+
       end
     end
   end

data/lib/garner/version.rb

@@ -1,3 +1,3 @@
 module Garner
-  VERSION = '0.2.1'
+  VERSION = '0.3.0'
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: garner
 version: !ruby/object:Gem::Version
-  version: 0.2.1
+  version: 0.3.0
   prerelease: 
 platform: ruby
 authors:
@@ -10,7 +10,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2013-01-22 00:00:00.000000000 Z
+date: 2013-01-24 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rack
@@ -172,6 +172,22 @@ dependencies:
     - - ~>
       - !ruby/object:Gem::Version
         version: '3.0'
+- !ruby/object:Gem::Dependency
+  name: dalli
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '2.6'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '2.6'
 - !ruby/object:Gem::Dependency
   name: yard
   requirement: !ruby/object:Gem::Requirement
@@ -263,7 +279,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
       version: '0'
       segments:
       - 0
-      hash: 889347935123245080
+      hash: 4499796191639143111
 required_rubygems_version: !ruby/object:Gem::Requirement
   none: false
   requirements: