cache 0.2.0 → 0.2.1

data/README.md

@@ -2,7 +2,52 @@
 
 A unified cache handling interface, inspired by libraries like [ActiveSupport::Cache::Store](http://api.rubyonrails.org/classes/ActiveSupport/Cache/Store.html), Perl's [Cache::Cache](http://cpan.uwinnipeg.ca/module/Cache::Cache), and [CHI](http://cpan.uwinnipeg.ca/module/CHI).
 
-## Supported methods
+## Quick example
+
+    require 'memcached' # a really fast memcached client gem
+    require 'cache'     # this gem, which wraps the client to provide a standard interface
+    raw_client = Memcached.new('127.0.0.1:11211')
+    @cache = Cache.wrap(raw_client)
+    
+    # don't worry, even though it's memcached gem, this won't raise Memcached::NotFound
+    @cache.get('hello')
+    
+    # fetch is not provided by the memcached gem, the wrapper adds it
+    @cache.fetch('hello') { 'world' }
+    
+    # don't worry, the wrapper will automatically clone the Memcached object after forking
+    Kernel.fork { @cache.get('hello') }
+
+## Rationale
+
+I wanted a common interface to a bunch of great Ruby cache clients so I can develop gems (lock_method, cache_method) that accept any of them.
+
+* I'm tired of rescuing from Memcached::NotFound
+* I'm tired of forgetting whether it's :expires_in or :ttl
+* I don't know why we ever started using read/write instead of get/set.
+* I don't like how you have to manually handle after_fork for Redis, Memcached, etc.
+* I don't know why Memcached::Rails isn't implemented as an ActiveRecord::Cache::Store (Dalli did it just fine!)
+* Why are you asking me about :raw or whatever? Just marshal it
+
+## Features
+
+### Forking/threading
+
+When you use a Cache object to wrap Memcached or Redis, you don't have to worry about forking or threading.
+
+For example, you don't have to set up unicorn or PhusionPassenger's <tt>after_fork</tt>.
+
+### TTL
+
+0 means don't expire.
+
+The default ttl is 60 seconds.
+
+### Marshalling
+
+Everything gets marshalled. No option to turn it into "raw" mode. If you need that kind of control, please submit a patch or just use one of the other gems directly.
+
+### Supported methods
 
 It will translate these methods to whatever Redis, Memcached, etc. client you're using:
 
@@ -16,6 +61,7 @@ It will translate these methods to whatever Redis, Memcached, etc. client you're
     @cache.cas 'hello' { |current| 'world' }
     @cache.increment 'high-fives'
     @cache.decrement 'high-fives'
+    @cache.get_multi 'hello', 'privyet', 'hallo'
 
 Also provided for Rails compatibility:
 
@@ -25,16 +71,17 @@ Also provided for Rails compatibility:
     @cache.compare_and_swap
     @cache.read_multi 'hello', 'privyet', 'hallo'
 
-## Rationale
+### Supported clients
 
-I wanted a common interface to a bunch of great Ruby cache clients so I can develop gems (lock_method, cache_method) that accept any of them.
+Supported memcached clients:
 
-* I'm tired of rescuing from Memcached::NotFound
-* I'm tired of forgetting whether it's :expires_in or :ttl
-* I don't know why we ever started using read/write instead of get/set.
-* I don't like how you have to manually handle after_fork for Redis, Memcached, etc.
-* I don't know why Memcached::Rails isn't implemented as an ActiveRecord::Cache::Store (Dalli did it just fine!)
-* Why are you asking me about :raw or whatever? Just marshal it
+* [memcached](https://github.com/fauna/memcached) (native C extensions, super fast!)
+* [dalli](https://github.com/mperham/dalli) (pure ruby, recommended if you're on heroku)
+* [memcache-client](https://github.com/mperham/memcache-client) (not recommended. the one that comes with Rails.)
+
+Supported Redis clients:
+
+* [redis](https://github.com/ezmobius/redis-rb)
 
 ## How you might use it
 
@@ -51,18 +98,6 @@ I wanted a common interface to a bunch of great Ruby cache clients so I can deve
     <td><pre>config.cache_store = Cache.wrap(Dalli::Client.new)</pre></td>
     <td><pre>config.cache_store = Cache.wrap(Redis.new)</pre></td>
   </tr>
-  <tr>
-    <td><a href="https://github.com/seamusabshere/cache_method">CacheMethod</a> (already uses Cache internally)</td>
-    <td><pre>CacheMethod.config.storage = Memcached.new</pre></td>
-    <td><pre>CacheMethod.config.storage = Dalli::Client.new</pre></td>
-    <td><pre>CacheMethod.config.storage = Redis.new</pre></td>
-  </tr>
-  <tr>
-    <td><a href="https://github.com/seamusabshere/lock_method">LockMethod</a> (already uses Cache internally)</td>
-    <td><pre>LockMethod.config.storage = Memcached.new</pre></td>
-    <td><pre>LockMethod.config.storage = Dalli::Client.new</pre></td>
-    <td><pre>LockMethod.config.storage = Redis.new</pre></td>
-  </tr>
   <tr>
     <td>Your own library</td>
     <td>
@@ -90,18 +125,20 @@ end
 </pre>
     </td>
   </tr>
+  <tr>
+    <td><a href="https://github.com/seamusabshere/cache_method">CacheMethod</a> (already uses Cache internally)</td>
+    <td><pre>CacheMethod.config.storage = Memcached.new</pre></td>
+    <td><pre>CacheMethod.config.storage = Dalli::Client.new</pre></td>
+    <td><pre>CacheMethod.config.storage = Redis.new</pre></td>
+  </tr>
+  <tr>
+    <td><a href="https://github.com/seamusabshere/lock_method">LockMethod</a> (already uses Cache internally)</td>
+    <td><pre>LockMethod.config.storage = Memcached.new</pre></td>
+    <td><pre>LockMethod.config.storage = Dalli::Client.new</pre></td>
+    <td><pre>LockMethod.config.storage = Redis.new</pre></td>
+  </tr>
 </table>
 
-## Forking/threading
-
-When you use a Cache object to wrap Memcached or Redis, you don't have to worry about forking or threading.
-
-For example, you don't have to set up unicorn or PhusionPassenger's <tt>after_fork</tt>.
-
-## TTL
-
-0 means don't expire.
-
 ## Other examples
 
 It defaults to an in-process memory store:
@@ -112,13 +149,6 @@ It defaults to an in-process memory store:
 
 You can specify a more useful cache client:
 
-    require 'memcached' # a really fast memcached client gem
-    require 'cache'     # this gem, which provides a standard interface
-    raw_client = Memcached.new '127.0.0.1:11211'
-    @cache = Cache.wrap(raw_client)
-
-or
-
     require 'redis'     # the redis key-value store
     require 'cache'     # this gem, which provides a standard interface
     raw_client = Redis.new
@@ -131,23 +161,10 @@ or
     raw_client = Dalli::Client.new
     @cache = Cache.wrap(raw_client)
 
-Don't know why you would ever want to do this:
+Or you could piggyback off the default rails cache:
 
-    # Piggyback off the default rails cache
     @cache = Cache.wrap(Rails.cache)
 
-## Supported clients
-
-Supported memcached clients:
-
-* [memcached](https://github.com/fauna/memcached) (super fast!)
-* [dalli](https://github.com/mperham/dalli) (pure ruby, recommended if you're on heroku)
-* [memcache-client](https://github.com/mperham/memcache-client) (not recommended. the one that comes with Rails.)
-
-Supported Redis clients:
-
-* [redis](https://github.com/ezmobius/redis-rb)
-
 ## Copyright
 
 Copyright 2011 Seamus Abshere

data/lib/cache.rb

@@ -19,7 +19,11 @@ class Cache
   #     raw_client = Memcached.new('127.0.0.1:11211')
   #     cache = Cache.wrap raw_client
   def self.wrap(client = nil)
-    new client
+    if client.is_a?(::Cache)
+      client
+    else
+      new client
+    end
   end
   
   def initialize(client = nil) #:nodoc:
@@ -48,7 +52,7 @@ class Cache
   #     cache.set 'hello', 'world'
   #     cache.set 'hello', 'world', 80 # seconds til it expires
   def set(k, v, ttl = nil, ignored_options = nil)
-    storage.set k, v, ttl
+    storage.set k, v, extract_ttl(ttl)
   end
   
   # Delete a value.
@@ -100,10 +104,12 @@ class Cache
 
   # Try to get a value and if it doesn't exist, set it to the result of the block.
   #
+  # Accepts :expires_in for compatibility with Rails.
+  #
   # Example:
   #     cache.fetch 'hello' { 'world' }
-  def fetch(k, options_ignored_except_expires_in = {}, &blk)
-    storage.fetch k, options_ignored_except_expires_in[:expires_in], &blk
+  def fetch(k, ttl = nil, &blk)
+    storage.fetch k, extract_ttl(ttl), &blk
   end
   
   # Get the current value (if any), pass it into a block, and set the result.
@@ -111,7 +117,7 @@ class Cache
   # Example:
   #     cache.cas 'hello' { |current| 'world' }
   def cas(k, ttl = nil, &blk)
-    storage.cas k, ttl, &blk
+    storage.cas k, extract_ttl(ttl), &blk
   end
   
   alias :compare_and_swap :cas
@@ -123,16 +129,39 @@ class Cache
   def stats
     storage.stats
   end
+
+  # Get multiple cache entries.
+  #
+  # Example:
+  #     cache.get_multi 'hello', 'privyet'
+  def get_multi(*ks)
+    storage.get_multi ks
+  end
   
-  def write(k, v, options_ignored_except_expires_in = {}) #:nodoc:
-    storage.set k, v, options_ignored_except_expires_in[:expires_in]
+  # Like get, but accepts :expires_in for compatibility with Rails.
+  #
+  # In general, you should use get instead.
+  #
+  # Example:
+  #     cache.write 'hello', 'world', :expires_in => 5.minutes
+  def write(k, v, ttl = nil)
+    storage.set k, v, extract_ttl(ttl)
   end
   
   def read(k, ignored_options = nil) #:nodoc:
     storage.get k
   end
   
-  def read_multi(*ks) #:nodoc:
-    ks.map { |k| storage.get k }
+  private
+  
+  def extract_ttl(ttl)
+    case ttl
+    when ::Hash
+      ttl[:expires_in]
+    when ::NilClass
+      config.default_ttl
+    else
+      ttl.to_i
+    end
   end
 end

data/lib/cache/storage.rb

@@ -25,10 +25,24 @@ class Cache
         raise "Don't know how to GET with #{bare.inspect}"
       end
     end
+    
+    def get_multi(ks)
+      reset_if_forked_or_threaded
+      if memcached?
+        bare.get ks
+      elsif memcached_rails? or dalli? or mem_cache?
+        bare.get_multi ks
+      elsif active_support_store?
+        bare.read_multi *ks
+      else
+        ks.inject({}) do |memo, k|
+          memo[k] = get k if exist? k
+          memo
+        end
+      end
+    end
         
     def set(k, v, ttl)
-      ttl ||= parent.config.default_ttl
-      ttl = ttl.to_i
       reset_if_forked_or_threaded
       if memcached? or dalli? or memcached_rails? or mem_cache?
         bare.set k, v, ttl
@@ -103,8 +117,6 @@ class Cache
     end
     
     def fetch(k, ttl, &blk)
-      ttl ||= parent.config.default_ttl
-      ttl = ttl.to_i
       reset_if_forked_or_threaded
       if dalli? or mem_cache?
         bare.fetch k, ttl, &blk
@@ -122,8 +134,6 @@ class Cache
     end
     
     def cas(k, ttl, &blk)
-      ttl ||= parent.config.default_ttl
-      ttl = ttl.to_i
       reset_if_forked_or_threaded
       if memcached?
         begin; bare.cas(k, ttl, &blk); rescue ::Memcached::NotFound; nil; end

data/lib/cache/version.rb

@@ -1,3 +1,3 @@
 class Cache
-  VERSION = "0.2.0"
+  VERSION = "0.2.1"
 end

data/test/shared_tests.rb

@@ -70,6 +70,10 @@ module SharedTests
     assert_equal 'world', @cache.fetch('hello') { 'world' }
   end
   
+  def test_fetch_with_expires_in
+    assert_equal 'world', @cache.fetch('hello', :expires_in => 5) { 'world' }
+  end
+  
   def test_cas
     toggle = lambda do |current|
       current == 'on' ? 'off' : 'on'
@@ -118,13 +122,9 @@ module SharedTests
     assert_equal -2, @cache.get('high-fives')
   end
   
-  def test_read_multi
+  def test_get_multi
     @cache.set 'hello', 'world'
     @cache.set 'privyet', 'mir'
-    assert_equal %w{world mir}, @cache.read_multi('hello', 'privyet')
+    assert_equal({ 'hello' => 'world', 'privyet' => 'mir'}, @cache.get_multi('hello', 'privyet', 'yoyoyo'))
   end
-  
-  alias :test_clear :test_flush
-  
-  alias :test_compare_and_swap :test_cas
 end

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification 
 name: cache
 version: !ruby/object:Gem::Version 
-  hash: 23
+  hash: 21
   prerelease: false
   segments: 
   - 0
   - 2
-  - 0
-  version: 0.2.0
+  - 1
+  version: 0.2.1
 platform: ruby
 authors: 
 - Seamus Abshere
@@ -15,7 +15,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2011-03-04 00:00:00 -06:00
+date: 2011-03-07 00:00:00 -06:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency