cache 0.1.3 → 0.2.0

data/.gitignore

@@ -4,3 +4,4 @@ Gemfile.lock
 pkg/*
 secret.sh
 rdoc/*
+.yardoc

data/BENCHMARKS

@@ -1,3 +1,101 @@
+# sabshere 3/4/11 v0.2.0
+
+vidalia:~/github/cache (master) $ ruby test/profile/benchmark.rb 
+Darwin vidalia 9.8.0 Darwin Kernel Version 9.8.0: Wed Jul 15 16:55:01 PDT 2009; root:xnu-1228.15.4~1/RELEASE_I386 i386
+ruby 1.8.7 (2010-05-25 patchlevel 266) [i686-darwin9.8.0]
+RUBY_VERSION=ruby-1.8.7-head
+Ruby 1.8.7p266
+Loaded memcached 1.2
+Loaded remix-stash 1.1.3
+Loaded memcache-client 1.8.5
+Loaded cache 0.1.2 # i just hadn't released the gem yet
+Loaded kgio 2.3.2
+Loaded dalli 1.0.2
+Loops is 20000
+Stack depth is 0
+Small value size is: 13 bytes
+Large value size is: 4158 bytes
+No matching processes belonging to you were found
+                                          user     system      total        real
+set: cache:dalli:bin                  5.720000   1.860000   7.580000 ( 10.301808)
+set: cache:libm:bin                   1.250000   1.270000   2.520000 (  5.892224)
+set: dalli:bin                        5.430000   1.860000   7.290000 (  9.966409)
+set: libm:ascii                       0.760000   1.330000   2.090000 (  5.348975)
+set: libm:ascii:pipeline              0.280000   0.010000   0.290000 (  0.297230)
+set: libm:ascii:udp                   0.650000   0.710000   1.360000 (  3.593454)
+set: libm:bin                         0.640000   1.360000   2.000000 (  5.285160)
+set: libm:bin:buffer                  0.270000   0.160000   0.430000 (  1.234561)
+set: mclient:ascii                   11.330000   3.780000  15.110000 ( 16.174666)
+set: stash:bin                        3.420000   1.330000   4.750000 (  8.016146)
+
+get: cache:dalli:bin                  5.870000   1.950000   7.820000 ( 10.644558)
+get: cache:libm:bin                   1.370000   1.200000   2.570000 (  5.946502)
+get: dalli:bin                        5.580000   2.070000   7.650000 ( 10.361689)
+get: libm:ascii                       0.980000   1.300000   2.280000 (  5.455222)
+get: libm:ascii:pipeline              1.030000   1.590000   2.620000 (  5.875592)
+get: libm:ascii:udp                   0.820000   0.730000   1.550000 (  3.515632)
+get: libm:bin                         0.830000   1.330000   2.160000 (  5.381290)
+get: libm:bin:buffer                  0.900000   1.630000   2.530000 (  5.761412)
+get: mclient:ascii                   13.630000   3.870000  17.500000 ( 17.912800)
+get: stash:bin                        3.100000   1.340000   4.440000 (  7.667182)
+
+delete: cache:dalli:bin               6.270000   2.390000   8.660000 ( 11.313843)
+delete: cache:libm:bin                2.190000   1.560000   3.750000 (  7.459292)
+delete: dalli:bin                     5.660000   2.340000   8.000000 ( 10.374507)
+delete: libm:ascii                    1.850000   1.570000   3.420000 (  6.922356)
+delete: libm:ascii:pipeline           0.230000   0.010000   0.240000 (  0.242642)
+delete: libm:ascii:udp                1.690000   0.930000   2.620000 (  4.749489)
+delete: libm:bin                      1.780000   1.530000   3.310000 (  6.768449)
+delete: libm:bin:buffer               1.890000   1.880000   3.770000 (  7.149319)
+delete: mclient:ascii                11.940000   4.040000  15.980000 ( 16.423645)
+delete:stash:bin => #<NoMethodError: undefined method `delete' for #<Remix::Stash:0x1249824>>
+
+get-missing: cache:dalli:bin          5.530000   2.140000   7.670000 ( 10.187561)
+get-missing: cache:libm:bin           2.200000   1.510000   3.710000 (  6.953625)
+get-missing: dalli:bin                5.230000   2.160000   7.390000 (  9.891539)
+get-missing: libm:ascii               1.960000   1.420000   3.380000 (  6.459433)
+get-missing: libm:ascii:pipeline      2.080000   1.860000   3.940000 (  6.984890)
+get-missing: libm:ascii:udp           1.730000   0.910000   2.640000 (  4.582510)
+get-missing: libm:bin                 1.950000   1.470000   3.420000 (  6.854775)
+get-missing: libm:bin:buffer          2.060000   1.900000   3.960000 (  7.180759)
+get-missing: mclient:ascii           12.350000   4.100000  16.450000 ( 16.986064)
+get-missing: stash:bin                3.110000   1.410000   4.520000 (  7.908972)
+
+set-large: cache:dalli:bin            8.650000   2.110000  10.760000 ( 13.864690)
+set-large: cache:libm:bin             2.600000   1.450000   4.050000 (  7.811509)
+set-large: dalli:bin                  8.250000   2.100000  10.350000 ( 13.370233)
+set-large: libm:ascii                 0.890000   1.460000   2.350000 (  6.069504)
+set-large: libm:ascii:pipeline        0.570000   0.450000   1.020000 (  1.232906)
+set-large: libm:ascii:udp             0.730000   0.850000   1.580000 (  4.174216)
+set-large: libm:bin                   0.760000   1.510000   2.270000 (  5.966586)
+set-large: libm:bin:buffer            0.530000   0.700000   1.230000 (  2.419153)
+set-large: mclient:ascii             13.540000   4.250000  17.790000 ( 18.447711)
+set-large: stash:bin                  6.100000   1.500000   7.600000 ( 11.216811)
+
+get-large: cache:dalli:bin            8.000000   2.480000  10.480000 ( 13.450322)
+get-large: cache:libm:bin             6.820000   1.490000   8.310000 ( 12.331486)
+get-large: dalli:bin                  7.670000   2.490000  10.160000 ( 13.148162)
+get-large: libm:ascii                 1.740000   1.540000   3.280000 (  7.256110)
+get-large: libm:ascii:pipeline        1.870000   1.960000   3.830000 (  7.723493)
+get-large: libm:ascii:udp             1.560000   0.980000   2.540000 (  4.823281)
+get-large: libm:bin                   1.590000   1.590000   3.180000 (  7.018376)
+get-large: libm:bin:buffer            1.730000   1.960000   3.690000 (  7.365047)
+get-large: mclient:ascii             17.160000   4.890000  22.050000 ( 22.647077)
+get-large: stash:bin                  3.290000   1.440000   4.730000 (  7.950154)
+
+hash:jenkins                          0.550000   0.000000   0.550000 (  0.561738)
+hash:default                          0.550000   0.000000   0.550000 (  0.553209)
+hash:crc                              0.660000   0.000000   0.660000 (  0.657155)
+hash:fnv1_32                          0.530000   0.010000   0.540000 (  0.529303)
+hash:hsieh                            0.280000   0.000000   0.280000 (  0.281685)
+hash:fnv1_64                          1.160000   0.000000   1.160000 (  1.169524)
+hash:none                             0.310000   0.000000   0.310000 (  0.313095)
+hash:murmur                           0.450000   0.000000   0.450000 (  0.454460)
+hash:md5                              0.950000   0.010000   0.960000 (  0.949226)
+hash:fnv1a_64                         0.590000   0.000000   0.590000 (  0.590362)
+hash:fnv1a_32                         0.590000   0.000000   0.590000 (  0.599005)
+
+
 # sabshere 2/22/11 v0.0.3
 
 vidalia:~/github/cache (master) $ ruby test/profile/benchmark.rb 

data/README.md

@@ -0,0 +1,153 @@
+# cache
+
+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
+
+It will translate these methods to whatever Redis, Memcached, etc. client you're using:
+
+    @cache.get 'hello'
+    @cache.set 'hello', 'world', 5.minutes
+    @cache.delete 'hello'
+    @cache.flush
+    @cache.exist? 'hello'
+    @cache.reset
+    @cache.fetch 'hello' { 'world' }
+    @cache.cas 'hello' { |current| 'world' }
+    @cache.increment 'high-fives'
+    @cache.decrement 'high-fives'
+
+Also provided for Rails compatibility:
+
+    @cache.write 'hello', 'world', :expires_in => 5.minutes
+    @cache.read 'hello'
+    @cache.clear
+    @cache.compare_and_swap
+    @cache.read_multi 'hello', 'privyet', 'hallo'
+
+## 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
+
+## How you might use it
+
+<table>
+  <tr>
+    <th>&nbsp;</th>
+    <th><a href="https://github.com/fauna/memcached">Super-fast memcached</a></th>
+    <th><a href="https://github.com/mperham/dalli">Pure Ruby memcached</a> (works on <a href="http://devcenter.heroku.com/articles/memcache">Heroku</a>)</th>
+    <th><a href="https://redistogo.com/">Redis</a></th>
+  </tr>
+  <tr>
+    <td><a href="http://guides.rubyonrails.org/caching_with_rails.html#cache-stores">Rails</a></td>
+    <td><pre>config.cache_store = Cache.wrap(Memcached.new)</pre></td>
+    <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>
+<pre>
+# Accept any client, let Cache take care of it
+def cache=(raw_client)
+  @cache = Cache.wrap(raw_client)
+end
+</pre>
+    </td>
+    <td>
+<pre>
+# Accept any client, let Cache take care of it
+def cache=(raw_client)
+  @cache = Cache.wrap(raw_client)
+end
+</pre>
+    </td>
+    <td>
+<pre>
+# Accept any client, let Cache take care of it
+def cache=(raw_client)
+  @cache = Cache.wrap(raw_client)
+end
+</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:
+
+    @cache = Cache.new
+    @cache.set 'hello'
+    @cache.get 'hello', 'world'
+
+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
+    @cache = Cache.wrap(raw_client)
+
+or
+
+    require 'dalli'     # the dalli memcached client used by heroku
+    require 'cache'     # this gem, which provides a standard interface
+    raw_client = Dalli::Client.new
+    @cache = Cache.wrap(raw_client)
+
+Don't know why you would ever want to do this:
+
+    # 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/Rakefile

@@ -11,12 +11,31 @@ end
 
 task :default => :test
 
-require 'rake/rdoctask'
-Rake::RDocTask.new do |rdoc|
-  version = File.exist?('VERSION') ? File.read('VERSION') : ""
+# http://stackoverflow.com/questions/2138427/can-i-get-my-readme-textile-into-my-rdoc-with-proper-formatting
+desc "Generate RDoc"
+task :rdoc => ['doc:generate']
+namespace :doc do
+  project_root = File.expand_path(File.dirname(__FILE__))
+  doc_destination = File.join(project_root, 'rdoc')
+  files = Dir.glob(File.join(project_root, 'lib', '**', '*.rb')) + [ File.join(project_root, 'README.md') ]
+  begin
+    require 'yard'
+    require 'yard/rake/yardoc_task'
+
+    YARD::Rake::YardocTask.new(:generate) do |yt|
+      yt.files   = files
+      yt.options = ['--output-dir', doc_destination, '--readme', 'README.md']
+    end
+  rescue LoadError
+    desc "Generate YARD Documentation"
+    task :generate do
+      abort "Please install the YARD gem to generate rdoc."
+    end
+  end
+
+  desc "Remove generated documenation"
+  task :clean do
+    rm_r doc_dir if File.exists?(doc_destination)
+  end
 
-  rdoc.rdoc_dir = 'rdoc'
-  rdoc.title = "cache #{version}"
-  rdoc.rdoc_files.include('README*')
-  rdoc.rdoc_files.include('lib/**/*.rb')
 end

data/cache.gemspec

@@ -21,6 +21,7 @@ Gem::Specification.new do |s|
   
   s.add_dependency 'activesupport', '>=2.3.11' # for default memory store
   s.add_dependency 'i18n' # activesupport
+  s.add_development_dependency 'yard'
   s.add_development_dependency 'test-unit'
   s.add_development_dependency 'redis'
   s.add_development_dependency 'dalli'

data/lib/cache.rb

@@ -3,9 +3,9 @@ class Cache
   autoload :Config, 'cache/config'
   autoload :Storage, 'cache/storage'
 
-  # Create a new Cache object by passing it a client of your choice.
+  # Create a new Cache instance by wrapping a client of your choice.
   #
-  # Defaults to an in-process memory store, but you probably don't want that.
+  # Defaults to an in-process memory store.
   #
   # Supported memcached clients:
   # * memcached[https://github.com/fauna/memcached] (either a Memcached or a Memcached::Rails)
@@ -17,8 +17,12 @@ class Cache
   #
   # Example:
   #     raw_client = Memcached.new('127.0.0.1:11211')
-  #     cache = Cache.new raw_client
-  def initialize(client = nil)
+  #     cache = Cache.wrap raw_client
+  def self.wrap(client = nil)
+    new client
+  end
+  
+  def initialize(client = nil) #:nodoc:
     config.client = client
   end
 
@@ -34,7 +38,7 @@ class Cache
   #
   # Example:
   #     cache.get 'hello'
-  def get(k)
+  def get(k, ignored_options = nil)
     storage.get k
   end
   
@@ -43,7 +47,7 @@ class Cache
   # Example:
   #     cache.set 'hello', 'world'
   #     cache.set 'hello', 'world', 80 # seconds til it expires
-  def set(k, v, ttl = nil)
+  def set(k, v, ttl = nil, ignored_options = nil)
     storage.set k, v, ttl
   end
   
@@ -51,7 +55,7 @@ class Cache
   #
   # Example:
   #     cache.delete 'hello'
-  def delete(k)
+  def delete(k, ignored_options = nil)
     storage.delete k
   end
   
@@ -62,4 +66,73 @@ class Cache
   def flush
     storage.flush
   end
+  
+  alias :clear :flush
+
+  # Check if something exists.
+  #
+  # Example:
+  #     cache.exist? 'hello'
+  def exist?(k, ignored_options = nil)
+    storage.exist? k
+  end
+  
+  # Increment a value.
+  #
+  # Example:
+  #     cache.increment 'high-fives'
+  def increment(k, amount = 1, ignored_options = nil)
+    storage.increment k, amount
+  end
+
+  # Decrement a value.
+  #
+  # Example:
+  #     cache.decrement 'high-fives'
+  def decrement(k, amount = 1, ignored_options = nil)
+    storage.decrement k, amount
+  end
+  
+  # Reset the cache connection. You shouldn't really use this, because it happens automatically on forking/threading.
+  def reset
+    storage.reset
+  end
+
+  # Try to get a value and if it doesn't exist, set it to the result of the block.
+  #
+  # 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
+  end
+  
+  # Get the current value (if any), pass it into a block, and set the result.
+  #
+  # Example:
+  #     cache.cas 'hello' { |current| 'world' }
+  def cas(k, ttl = nil, &blk)
+    storage.cas k, ttl, &blk
+  end
+  
+  alias :compare_and_swap :cas
+  
+  # Get stats.
+  #
+  # Example:
+  #     cache.stats
+  def stats
+    storage.stats
+  end
+  
+  def write(k, v, options_ignored_except_expires_in = {}) #:nodoc:
+    storage.set k, v, options_ignored_except_expires_in[:expires_in]
+  end
+  
+  def read(k, ignored_options = nil) #:nodoc:
+    storage.get k
+  end
+  
+  def read_multi(*ks) #:nodoc:
+    ks.map { |k| storage.get k }
+  end
 end

data/lib/cache/storage.rb

@@ -12,17 +12,17 @@ class Cache
     def get(k)
       reset_if_forked_or_threaded
       if memcached?
-        begin; bare_client.get(k); rescue ::Memcached::NotFound; nil; end
+        begin; bare.get(k); rescue ::Memcached::NotFound; nil; end
       elsif dalli? or memcached_rails? or mem_cache?
-        bare_client.get k
+        bare.get k
       elsif redis?
-        if cached_v = bare_client.get(k) and cached_v.is_a?(::String)
+        if cached_v = bare.get(k) and cached_v.is_a?(::String)
           ::Marshal.load cached_v
         end
       elsif active_support_store?
-        bare_client.read k
+        bare.read k
       else
-        raise "Don't know how to GET with #{bare_client.inspect}"
+        raise "Don't know how to GET with #{bare.inspect}"
       end
     end
         
@@ -31,51 +31,130 @@ class Cache
       ttl = ttl.to_i
       reset_if_forked_or_threaded
       if memcached? or dalli? or memcached_rails? or mem_cache?
-        bare_client.set k, v, ttl
+        bare.set k, v, ttl
       elsif redis?
         if ttl == 0
-          bare_client.set k, ::Marshal.dump(v)
+          bare.set k, ::Marshal.dump(v)
         else
-          bare_client.setex k, ttl, ::Marshal.dump(v)
+          bare.setex k, ttl, ::Marshal.dump(v)
         end
       elsif active_support_store?
         if ttl == 0
-          bare_client.write k, v # never expire
+          bare.write k, v # never expire
         else
-          bare_client.write k, v, :expires_in => ttl
+          bare.write k, v, :expires_in => ttl
         end
       else
-        raise "Don't know how to SET with #{bare_client.inspect}"
+        raise "Don't know how to SET with #{bare.inspect}"
       end
     end
     
     def delete(k)
       reset_if_forked_or_threaded
       if memcached?
-        begin; bare_client.delete(k); rescue ::Memcached::NotFound; nil; end
+        begin; bare.delete(k); rescue ::Memcached::NotFound; nil; end
       elsif redis?
-        bare_client.del k
+        bare.del k
       elsif dalli? or memcached_rails? or mem_cache? or active_support_store?
-        bare_client.delete k
+        bare.delete k
       else
-        raise "Don't know how to DELETE with #{bare_client.inspect}"
+        raise "Don't know how to DELETE with #{bare.inspect}"
       end
     end
     
     def flush
       reset_if_forked_or_threaded
-      bare_client.send %w{ flush flushdb flush_all clear }.detect { |flush_cmd| bare_client.respond_to? flush_cmd }
+      bare.send %w{ flush flushdb flush_all clear }.detect { |flush_cmd| bare.respond_to? flush_cmd }
+    end
+    
+    # TODO detect nils
+    def exist?(k)
+      reset_if_forked_or_threaded
+      if memcached?
+        begin; bare.get(k); true; rescue ::Memcached::NotFound; false; end
+      elsif redis?
+        bare.exists k
+      elsif bare.respond_to?(:exist?)
+        # slow because we're looking it up
+        bare.exist? k
+      else
+        # weak because it doesn't detect keys that equal nil
+        !get(k).nil?
+      end
+    end
+    
+    # TODO use native memcached increment if available
+    # TODO don't reset the timer!
+    def increment(k, amount)
+      # reset_if_forked_or_threaded - uses get
+      new_v = get(k).to_i + amount
+      set k, new_v, 0
+      new_v
+    end
+    
+    def decrement(k, amount)
+      # reset_if_forked_or_threaded - uses increment, which uses get
+      increment k, -amount
+    end
+    
+    # TODO don't resort to trickery like this
+    def reset
+      @pid = nil
+    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
+      elsif active_support_store?
+        bare.fetch k, { :expires_in => ttl }, &blk
+      else
+        if exist? k
+          get k
+        elsif blk
+          v = blk.call
+          set k, v, ttl
+          v
+        end
+      end
+    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
+      elsif dalli? or memcached_rails?
+        bare.cas k, ttl, &blk
+      elsif blk and exist?(k)
+        old_v = get k
+        new_v = blk.call old_v
+        set k, new_v, ttl
+        new_v
+      end
+    end
+    
+    def stats
+      reset_if_forked_or_threaded
+      if bare.respond_to?(:stats)
+        bare.stats
+      else
+        {}
+      end
     end
     
     private
     
-    def bare_client
-      @bare_client ||= parent.config.client
+    def bare
+      @bare ||= parent.config.client
     end
     
     def reset_if_forked_or_threaded
       if fork_detected?
-        $stderr.puts "fork detected" if ENV['CACHE_DEBUG'] == 'true'
+        # $stderr.puts "fork detected" if ENV['CACHE_DEBUG'] == 'true'
         if dalli?
           parent.config.client.close
         elsif dalli_store?
@@ -83,18 +162,18 @@ class Cache
         elsif memcached? or memcached_rails?
           cloned_client = parent.config.client.clone
           parent.config.client = cloned_client
-          @bare_client = parent.config.client
+          @bare = parent.config.client
         elsif redis?
           parent.config.client.client.connect
         elsif mem_cache?
           parent.config.client.reset
         end
       elsif new_thread_detected?
-        $stderr.puts "new thread detected" if ENV['CACHE_DEBUG'] == 'true'
+        # $stderr.puts "new thread detected" if ENV['CACHE_DEBUG'] == 'true'
         if memcached? or memcached_rails?
           cloned_client = parent.config.client.clone
           parent.config.client = cloned_client
-          @bare_client = parent.config.client
+          @bare = parent.config.client
         end
       end
     end
@@ -113,56 +192,56 @@ class Cache
         
     def dalli?
       return @dalli_query[0] if @dalli_query.is_a?(::Array)
-      answer = (defined?(::Dalli) and bare_client.is_a?(::Dalli::Client))
+      answer = (defined?(::Dalli) and bare.is_a?(::Dalli::Client))
       @dalli_query = [answer]
       answer
     end
     
     def active_support_store?
       return @active_support_store_query[0] if @active_support_store_query.is_a?(::Array)
-      answer = (defined?(::ActiveSupport::Cache) and bare_client.is_a?(::ActiveSupport::Cache::Store))
+      answer = (defined?(::ActiveSupport::Cache) and bare.is_a?(::ActiveSupport::Cache::Store))
       @active_support_store_query = [answer]
       answer
     end
     
     def dalli_store?
       return @dalli_store_query[0] if @dalli_store_query.is_a?(::Array)
-      answer = (defined?(::ActiveSupport::Cache::DalliStore) and bare_client.is_a?(::ActiveSupport::Cache::DalliStore))
+      answer = (defined?(::ActiveSupport::Cache::DalliStore) and bare.is_a?(::ActiveSupport::Cache::DalliStore))
       @dalli_store_query = [answer]
       answer
     end
     
     def memory_store?
       return @memory_store_query[0] if @memory_store_query.is_a?(::Array)
-      answer = (defined?(::ActiveSupport::Cache::MemoryStore) and bare_client.is_a?(::ActiveSupport::Cache::MemoryStore))
+      answer = (defined?(::ActiveSupport::Cache::MemoryStore) and bare.is_a?(::ActiveSupport::Cache::MemoryStore))
       @memory_store_query = [answer]
       answer
     end
     
     def mem_cache?
       return @mem_cache_query[0] if @mem_cache_query.is_a?(::Array)
-      answer = (defined?(::MemCache) and bare_client.is_a?(::MemCache))
+      answer = (defined?(::MemCache) and bare.is_a?(::MemCache))
       @mem_cache_query = [answer]
       answer
     end
 
     def memcached?
       return @memcached_query[0] if @memcached_query.is_a?(::Array)
-      answer = (defined?(::Memcached) and bare_client.is_a?(::Memcached))
+      answer = (defined?(::Memcached) and bare.is_a?(::Memcached) and not bare.is_a?(::Memcached::Rails))
       @memcached_query = [answer]
       answer
     end
     
     def memcached_rails?
       return @memcached_rails_query[0] if @memcached_rails_query.is_a?(::Array)
-      answer = (defined?(::Memcached) and bare_client.is_a?(::Memcached::Rails))
+      answer = (defined?(::Memcached) and bare.is_a?(::Memcached::Rails))
       @memcached_rails_query = [answer]
       answer
     end
     
     def redis?
       return @redis_query[0] if @redis_query.is_a?(::Array)
-      answer = (defined?(::Redis) and bare_client.is_a?(::Redis))
+      answer = (defined?(::Redis) and bare.is_a?(::Redis))
       @redis_query = [answer]
       answer
     end

data/lib/cache/version.rb

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

data/test/helper.rb

@@ -10,7 +10,7 @@ require 'shared_tests'
 
 class Test::Unit::TestCase
   def setup
-    @cache = Cache.new raw_client
+    @cache = Cache.wrap raw_client
     @cache.flush
   end
 end

data/test/profile/benchmark.rb

@@ -53,14 +53,14 @@ class Dalli::ClientCompat < Dalli::Client
   end  
 end
 
-class Cache::Compat < Cache
-  def set(*args)
-    super(*args[0..2])
-  end
-  def get(*args)
-    super(args.first)
-  end
-end
+# class Cache::Compat < Cache
+#   def set(*args)
+#     super(*args[0..2])
+#   end
+#   def get(*args)
+#     super(args.first)
+#   end
+# end
 
 class Bench
 
@@ -108,8 +108,8 @@ class Bench
   
   def reset_clients
     @clients = {
-       "cache:libm:bin" => Cache::Compat.new(Memcached.new(['127.0.0.1:43042', '127.0.0.1:43043'], :buffer_requests => false, :no_block => false, :namespace => "namespace", :binary_protocol => true)),
-       "cache:dalli:bin" => Cache::Compat.new(Dalli::Client.new(['127.0.0.1:43042', '127.0.0.1:43043'], :marshal => false, :threadsafe => false)),
+       "cache:libm:bin" => Cache.wrap(Memcached.new(['127.0.0.1:43042', '127.0.0.1:43043'], :buffer_requests => false, :no_block => false, :namespace => "namespace", :binary_protocol => true)),
+       "cache:dalli:bin" => Cache.wrap(Dalli::Client.new(['127.0.0.1:43042', '127.0.0.1:43043'], :marshal => false, :threadsafe => false)),
        "libm:ascii" => Memcached::Rails.new(
          ['127.0.0.1:43042', '127.0.0.1:43043'],
          :buffer_requests => false, :no_block => false, :namespace => "namespace"),

data/test/shared_tests.rb

@@ -34,8 +34,97 @@ module SharedTests
   
   def test_flush
     @cache.set 'hello', 'world'
-    assert_equal 'world', @cache.get('hello')
+    assert @cache.exist?('hello')
     @cache.flush
+    assert !@cache.exist?('hello')
+  end
+  
+  def test_exist
+    assert !@cache.exist?('hello')
+    @cache.set 'hello', 'world'
+    assert @cache.exist?('hello')
+  end
+  
+  def test_exist_key_with_nil_value
+    assert !@cache.exist?('hello')
+    @cache.set 'hello', nil
+    assert @cache.exist?('hello')
+  end
+
+  def test_stats
+    assert_nothing_raised do
+      @cache.stats
+    end
+  end
+
+  def test_reset
+    @cache.set 'hello', 'world'
+    assert @cache.exist?('hello')
+    @cache.reset
+    # still there!
+    assert @cache.exist?('hello')
+  end
+  
+  def test_fetch
+    assert_equal nil, @cache.fetch('hello')
+    assert_equal 'world', @cache.fetch('hello') { 'world' }
+  end
+  
+  def test_cas
+    toggle = lambda do |current|
+      current == 'on' ? 'off' : 'on'
+    end
+    
+    @cache.set 'lights', 'on'
+    assert_equal 'on', @cache.get('lights')
+    @cache.cas 'lights', &toggle
+    assert_equal 'off', @cache.get('lights')
+    @cache.cas 'lights', &toggle
+    assert_equal 'on', @cache.get('lights')
+    @cache.cas 'lights', &toggle
+    assert_equal 'off', @cache.get('lights')
+  end
+  
+  def test_write
+    @cache.write 'hello', 'world'
+    assert_equal 'world', @cache.get('hello')
+  end
+  
+  def test_write_with_expires_in
+    @cache.write 'hello', 'world', :expires_in => 1
+    assert_equal 'world', @cache.get('hello')
+    sleep 2
     assert_equal nil, @cache.get('hello')
   end
+  
+  def test_read
+    @cache.set 'hello', 'world'
+    assert_equal 'world', @cache.read('hello')
+  end
+  
+  def test_increment
+    assert !@cache.exist?('high-fives')
+    @cache.increment 'high-fives'
+    assert_equal 1, @cache.get('high-fives')
+    @cache.increment 'high-fives'
+    assert_equal 2, @cache.get('high-fives')
+  end
+  
+  def test_decrement
+    assert !@cache.exist?('high-fives')
+    @cache.decrement 'high-fives'
+    assert_equal -1, @cache.get('high-fives')
+    @cache.decrement 'high-fives'
+    assert_equal -2, @cache.get('high-fives')
+  end
+  
+  def test_read_multi
+    @cache.set 'hello', 'world'
+    @cache.set 'privyet', 'mir'
+    assert_equal %w{world mir}, @cache.read_multi('hello', 'privyet')
+  end
+  
+  alias :test_clear :test_flush
+  
+  alias :test_compare_and_swap :test_cas
 end

data/test/test_memcached_rails_storage.rb

@@ -4,13 +4,13 @@ require 'memcached'
 
 class TestMemcachedRailsStorage < Test::Unit::TestCase
   def raw_client
-    Memcached::Rails.new 'localhost:11211'
+    Memcached::Rails.new 'localhost:11211', :support_cas => true
   end
     
   include SharedTests
   
-  def get_bare_client_id
-    @cache.storage.send(:bare_client).object_id
+  def get_bare_id
+    @cache.storage.send(:bare).object_id
   end
   
   def test_treats_as_not_thread_safe
@@ -18,17 +18,17 @@ class TestMemcachedRailsStorage < Test::Unit::TestCase
     @cache.get 'hi'
     
     # get the main thread's bare client
-    main_thread_bare_client_id = get_bare_client_id
+    main_thread_bare_id = get_bare_id
     
     # sanity check that it's not changing every time
     @cache.get 'hi'
-    assert_equal main_thread_bare_client_id, get_bare_client_id
+    assert_equal main_thread_bare_id, get_bare_id
     
     # create a new thread and get its bare client
-    new_thread_bare_client_id = Thread.new { @cache.get 'hi'; get_bare_client_id }.value
+    new_thread_bare_id = Thread.new { @cache.get 'hi'; get_bare_id }.value
     
     # make sure the bare client was reinitialized
-    assert(main_thread_bare_client_id != new_thread_bare_client_id)
+    assert(main_thread_bare_id != new_thread_bare_id)
   end
   
   def test_treats_as_not_fork_safe
@@ -36,16 +36,16 @@ class TestMemcachedRailsStorage < Test::Unit::TestCase
     @cache.get 'hi'
     
     # get the main process's bare client
-    parent_process_bare_client_id = get_bare_client_id
+    parent_process_bare_id = get_bare_id
     
     # sanity check that it's not changing every time
     @cache.get 'hi'
-    assert_equal parent_process_bare_client_id, get_bare_client_id
+    assert_equal parent_process_bare_id, get_bare_id
     
     # fork a new process
     pid = Kernel.fork do
       @cache.get 'hi'
-      raise "Didn't split!" if parent_process_bare_client_id == get_bare_client_id
+      raise "Didn't split!" if parent_process_bare_id == get_bare_id
     end
     Process.wait pid
     

data/test/test_memcached_storage.rb

@@ -4,13 +4,13 @@ require 'memcached'
 
 class TestMemcachedStorage < Test::Unit::TestCase
   def raw_client
-    Memcached.new 'localhost:11211'
+    Memcached.new 'localhost:11211', :support_cas => true
   end
     
   include SharedTests
   
-  def get_bare_client_id
-    @cache.storage.send(:bare_client).object_id
+  def get_bare_id
+    @cache.storage.send(:bare).object_id
   end
   
   def test_treats_as_not_thread_safe
@@ -18,17 +18,17 @@ class TestMemcachedStorage < Test::Unit::TestCase
     @cache.get 'hi'
     
     # get the main thread's bare client
-    main_thread_bare_client_id = get_bare_client_id
+    main_thread_bare_id = get_bare_id
     
     # sanity check that it's not changing every time
     @cache.get 'hi'
-    assert_equal main_thread_bare_client_id, get_bare_client_id
+    assert_equal main_thread_bare_id, get_bare_id
     
     # create a new thread and get its bare client
-    new_thread_bare_client_id = Thread.new { @cache.get 'hi'; get_bare_client_id }.value
+    new_thread_bare_id = Thread.new { @cache.get 'hi'; get_bare_id }.value
     
     # make sure the bare client was reinitialized
-    assert(main_thread_bare_client_id != new_thread_bare_client_id)
+    assert(main_thread_bare_id != new_thread_bare_id)
   end
   
   def test_treats_as_not_fork_safe
@@ -36,16 +36,16 @@ class TestMemcachedStorage < Test::Unit::TestCase
     @cache.get 'hi'
     
     # get the main process's bare client
-    parent_process_bare_client_id = get_bare_client_id
+    parent_process_bare_id = get_bare_id
     
     # sanity check that it's not changing every time
     @cache.get 'hi'
-    assert_equal parent_process_bare_client_id, get_bare_client_id
+    assert_equal parent_process_bare_id, get_bare_id
     
     # fork a new process
     pid = Kernel.fork do
       @cache.get 'hi'
-      raise "Didn't split!" if parent_process_bare_client_id == get_bare_client_id
+      raise "Didn't split!" if parent_process_bare_id == get_bare_id
     end
     Process.wait pid
     

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification 
 name: cache
 version: !ruby/object:Gem::Version 
-  hash: 29
+  hash: 23
   prerelease: false
   segments: 
   - 0
-  - 1
-  - 3
-  version: 0.1.3
+  - 2
+  - 0
+  version: 0.2.0
 platform: ruby
 authors: 
 - Seamus Abshere
@@ -15,7 +15,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2011-03-01 00:00:00 -06:00
+date: 2011-03-04 00:00:00 -06:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency 
@@ -49,7 +49,7 @@ dependencies:
   type: :runtime
   version_requirements: *id002
 - !ruby/object:Gem::Dependency 
-  name: test-unit
+  name: yard
   prerelease: false
   requirement: &id003 !ruby/object:Gem::Requirement 
     none: false
@@ -63,7 +63,7 @@ dependencies:
   type: :development
   version_requirements: *id003
 - !ruby/object:Gem::Dependency 
-  name: redis
+  name: test-unit
   prerelease: false
   requirement: &id004 !ruby/object:Gem::Requirement 
     none: false
@@ -77,7 +77,7 @@ dependencies:
   type: :development
   version_requirements: *id004
 - !ruby/object:Gem::Dependency 
-  name: dalli
+  name: redis
   prerelease: false
   requirement: &id005 !ruby/object:Gem::Requirement 
     none: false
@@ -91,7 +91,7 @@ dependencies:
   type: :development
   version_requirements: *id005
 - !ruby/object:Gem::Dependency 
-  name: memcached
+  name: dalli
   prerelease: false
   requirement: &id006 !ruby/object:Gem::Requirement 
     none: false
@@ -105,7 +105,7 @@ dependencies:
   type: :development
   version_requirements: *id006
 - !ruby/object:Gem::Dependency 
-  name: memcache-client
+  name: memcached
   prerelease: false
   requirement: &id007 !ruby/object:Gem::Requirement 
     none: false
@@ -118,6 +118,20 @@ dependencies:
         version: "0"
   type: :development
   version_requirements: *id007
+- !ruby/object:Gem::Dependency 
+  name: memcache-client
+  prerelease: false
+  requirement: &id008 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        hash: 3
+        segments: 
+        - 0
+        version: "0"
+  type: :development
+  version_requirements: *id008
 description: A unified cache handling interface for Ruby, inspired by (but simpler than) Perl's Cache::Cache
 email: 
 - seamus@abshere.net
@@ -131,7 +145,7 @@ files:
 - .gitignore
 - BENCHMARKS
 - Gemfile
-- README.rdoc
+- README.md
 - Rakefile
 - cache.gemspec
 - lib/cache.rb

data/README.rdoc

@@ -1,87 +0,0 @@
-= cache
-
-A unified cache handling interface, inspired (but simpler than) Perl's Cache::Cache[http://cpan.uwinnipeg.ca/module/Cache::Cache] and CHI[http://cpan.uwinnipeg.ca/module/CHI].
-
-Takes care of exceptions like Memcached::NotFound and also forking/threading.
-
-== Example
-
-It uses a (useless?) memory store by default:
-
-    cache = Cache.new
-    cache.set 'hello'
-    cache.get 'hello', 'world'
-
-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.new raw_client
-
-or
-
-    require 'redis'     # the redis key-value store
-    require 'cache'    # this gem, which provides a standard interface
-    raw_client = Redis.new
-    cache = Cache.new raw_client
-
-or
-
-    require 'dalli'     # the dalli memcached client used by heroku
-    require 'cache'    # this gem, which provides a standard interface
-    raw_client = Dalli::Client.new
-    cache = Cache.new raw_client
-
-Maybe this will even work:
-
-    # Piggyback off the default rails cache
-    cache = Cache.new Rails.cache
-
-== Methods
-
-    cache.get 'hello'
-    cache.set 'hello', 'world'
-    cache.delete 'hello'
-    cache.flush
-
-== Supported clients
-
-Supported memcached clients:
-
-* memcached[https://github.com/fauna/memcached] (either a Memcached or a Memcached::Rails)
-* dalli[https://github.com/mperham/dalli] (either a Dalli::Client or an ActiveSupport::Cache::DalliStore)
-* memcache-client[https://github.com/mperham/memcache-client] (MemCache, the one commonly used by Rails)
-
-Supported Redis clients:
-
-* redis[https://github.com/ezmobius/redis-rb]
-
-== TTL
-
-0 means don't expire.
-
-== 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>.
-
-== 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 am so tired of rescuing from Memcached::NotFound
-* I am so 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.
-
-== Currently unsupported
-
-* cas
-* fetch
-* incr
-
-== Copyright
-
-Copyright 2011 Seamus Abshere