lock_and_cache 2.0.2 → 2.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 3a7645f81f4e7ee4980cdb47c841b853a9fdbe6b
-  data.tar.gz: 3c5288088f4f243f7713255676985214bea7db49
+  metadata.gz: 8b4c2d0489b674d6efd75d4a368fda53ffc7f869
+  data.tar.gz: ededebda48c306638c3d19c2047f1fff49dc00fc
 SHA512:
-  metadata.gz: 82aa1f3555638e500820ffabc1cc6d668928acc692c8e720f20d68962e9b9d0c7182d34cd787def3cc14c69feefea8c60e8d9b36deae2d1f3946122a252c009f
-  data.tar.gz: 84c281f244ca8b551fd57ba9e48e8193882274e0c3d7abfc12b2a973d3d02bbb109e711cd3446db631f142aa21778be18c7889ff4de0725a53eec824f98a0907
+  metadata.gz: 4837ba9ea728c9b330e489aebd0cd0d0f13ddbb7d99259ccfd958edbb9bafb4f58ac1e7f2dd37f3686d03be9d823b6a970df21b313306fff88f75a6b6c0b2a82
+  data.tar.gz: 2f07f2ec076d96bc6f6eb7febb2538daf1e3af305ba2947c227a1da6ff586d8cd7cfc56fb86418f6b3b353e518712d86a6dfe00496c759d46f3c864b40a2437e

data/CHANGELOG

@@ -1,3 +1,11 @@
+2.1.0 / 2015-10-26
+
+* Enhancements
+
+  * Better documentation
+  * Standalone mode (LockAndCache.lock_and_cache([...]) {})
+  * Nulls can be set to expire sooner than non-null return values (`nil_expires`)
+
 2.0.2 / 2015-10-16
 
 * Bug fixes (?)

data/README.md

@@ -30,7 +30,7 @@ As you can see, most caching libraries only take care of (1) and (4).
 
 ## Practice
 
-### Locking (antirez's Redlock)
+### Locking
 
 Based on [antirez's Redlock algorithm](http://redis.io/topics/distlock).
 
@@ -42,36 +42,104 @@ LockAndCache.storage = Redis.new
 
 It will use this redis for both locking and storing cached values.
 
-### Caching (block inside of a method)
+### Caching
 
 (be sure to set up storage as above)
 
-You put a block inside of a method:
+#### Standalone mode
 
 ```ruby
-class Blog
-  def click(arg1, arg2)
-    lock_and_cache(arg1, arg2, expires: 5) do
+LockAndCache.lock_and_cache('stock_price') do
+  # get yer stock quote
+end
+```
+
+But that's probably not very useful without parameters
+
+```ruby
+LockAndCache.lock_and_cache('stock_price', company: 'MSFT', date: '2015-05-05') do
+  # get yer stock quote
+end
+```
+
+And you probably want an expiry
+
+```ruby
+LockAndCache.lock_and_cache('stock_price', {company: 'MSFT', date: '2015-05-05'}, expires: 10) do
+  # get yer stock quote
+end
+```
+
+Note how we separated options (`{expires: 10}`) from a hash that is part of the cache key (`{company: 'MSFT', date: '2015-05-05'}`).
+
+You can clear a cache:
+
+```ruby
+LockAndCache.lock_and_cache('stock_price', company: 'MSFT', date: '2015-05-05')
+```
+
+One other crazy thing: let's say you want to check more often if the external stock price service returned nil
+
+```ruby
+LockAndCache.lock_and_cache('stock_price', {company: 'MSFT', date: '2015-05-05'}, expires: 10, nil_expires: 1) do
+  # get yer stock quote
+end
+```
+
+#### Context mode
+
+"Context mode" simply adds the class name, method name, and context key (the results of `#id` or `#lock_and_cache_key`) of the caller to the cache key.
+
+(This gem evolved from https://github.com/seamusabshere/cache_method, where you always cached a method call...)
+
+```ruby
+class Stock
+  include LockAndCache
+
+  def initialize(ticker_symbol)
+    [...]
+  end
+
+  def price(date)
+    lock_and_cache(date, expires: 10) do # <------ see how the cache key depends on the method args?
       # do the work
     end
   end
+
+  def lock_and_cache_key # <---------- if you don't define this, it will try to call #id
+    ticker_symbol
+  end
 end
 ```
 
-The key will be `{ Blog, :click, $id, $arg1, $arg2 }`. In other words, it auto-detects the class, method, object id ... and you add other args if you want.
+The key will be `{ StockQuote, :get, $id, $date, }`. In other words, it auto-detects the class, method, context key ... and you add other args if you want.
 
-You can change the object id easily:
+Here's how to clear a cache in context mode:
 
 ```ruby
-class Blog
-  # [...]
-  # if you don't define this, it will try to call #id
-  def lock_and_cache_key
-    [author, title]
-  end
-end
+blog.lock_and_cache_clear(:get, date)
 ```
 
+## Special features
+
+### Locking of course!
+
+Most caching libraries don't do locking, meaning that >1 process can be calculating a cached value at the same time. Since you presumably cache things because they cost CPU, database reads, or money, doesn't it make sense to lock while caching?
+
+### Heartbeat
+
+If the process holding the lock dies, we automatically remove the lock so somebody else can do it (using heartbeats and redlock extends).
+
+### Context mode
+
+This pulls information about the context of a lock_and_cache block from the surrounding class, method, and object... so that you don't have to!
+
+Standalone mode is cool too, tho.
+
+### nil_expires
+
+You can expire nil values with a different timeout (`nil_expires`) than other values (`expires`).
+
 ## Tunables
 
 * `LockAndCache.storage=[redis]`
@@ -83,6 +151,13 @@ end
 * [redis](https://github.com/redis/redis-rb)
 * [redlock](https://github.com/leandromoreira/redlock-rb)
 
+## Wishlist
+
+* Convert most tests to use standalone mode, which is easier to understand
+* Check options
+* Lengthen heartbeat so it's not so sensitive
+* Clarify which options are seconds or milliseconds
+
 ## Contributing
 
 1. Fork it ( https://github.com/[my-github-username]/lock_and_cache/fork )

data/lib/lock_and_cache.rb

@@ -1,4 +1,3 @@
-require 'lock_and_cache/version'
 require 'timeout'
 require 'digest/sha1'
 require 'base64'
@@ -7,6 +6,10 @@ require 'redlock'
 require 'active_support'
 require 'active_support/core_ext'
 
+require_relative 'lock_and_cache/version'
+require_relative 'lock_and_cache/action'
+require_relative 'lock_and_cache/key'
+
 # Lock and cache methods using redis!
 #
 # I bet you're caching, but are you locking?
@@ -33,13 +36,37 @@ module LockAndCache
     @storage
   end
 
-  # Flush LockAndCache's storage
+  # Flush LockAndCache's storage.
   #
   # @note If you are sharing a redis database, it will clear it...
+  #
+  # @note If you want to clear a single key, try `LockAndCache.clear(key)` (standalone mode) or `#lock_and_cache_clear(method_id, *key_parts)` in context mode.
   def LockAndCache.flush
     storage.flushdb
   end
 
+  # Lock and cache based on a key.
+  #
+  # @param key_parts [*] Parts that should be used to construct a key.
+  #
+  # @note Standalone mode. See also "context mode," where you mix LockAndCache into a class and call it from within its methods.
+  #
+  # @note A single hash arg is treated as a cached key. `LockAndCache.lock_and_cache(foo: :bar, expires: 100)` will be treated as a cache key of `foo: :bar, expires: 100` (which is probably wrong!!!). `LockAndCache.lock_and_cache({foo: :bar}, expires: 100)` will be treated as a cache key of `foo: :bar` and options `expires: 100`. This is the opposite of context mode and is true because we don't have any context to set the cache key from otherwise.
+  def LockAndCache.lock_and_cache(*key_parts_and_options, &blk)
+    options = (key_parts_and_options.last.is_a?(Hash) && key_parts_and_options.length > 1) ? key_parts_and_options.pop : {}
+    key = LockAndCache::Key.new key_parts_and_options
+    action = LockAndCache::Action.new key, options, blk
+    action.perform
+  end
+
+  # Clear a single key
+  #
+  # @note Standalone mode. See also "context mode," where you mix LockAndCache into a class and call it from within its methods.
+  def LockAndCache.clear(*key_parts)
+    key = LockAndCache::Key.new key_parts
+    key.clear
+  end
+
   # @param seconds [Numeric] Maximum wait time to get a lock
   #
   # @note Can be overridden by putting `max_lock_wait:` in your call to `#lock_and_cache`
@@ -57,133 +84,37 @@ module LockAndCache
     @lock_manager
   end
 
-  # @private
-  class Key
-    attr_reader :obj
-    attr_reader :method_id
-
-    def initialize(obj, method_id, parts)
-      @obj = obj
-      @method_id = method_id.to_sym
-      @_parts = parts
-    end
-
-    # A (non-cryptographic) digest of the key parts for use as the cache key
-    def digest
-      @digest ||= ::Digest::SHA1.hexdigest ::Marshal.dump(key)
-    end
-
-    # A (non-cryptographic) digest of the key parts for use as the lock key
-    def lock_digest
-      @lock_digest ||= 'lock/' + digest
-    end
-
-    # A human-readable representation of the key parts
-    def key
-      @key ||= [obj_class_name, method_id, parts]
-    end
-
-    alias debug key
-
-    # An array of the parts we use for the key
-    def parts
-      @parts ||= @_parts.map do |v|
-        case v
-        when ::String, ::Symbol, ::Hash, ::Array
-          v
-        else
-          v.respond_to?(:lock_and_cache_key) ? v.lock_and_cache_key : v.id
-        end
-      end
-    end
-
-    # An object (or its class's) name
-    def obj_class_name
-      @obj_class_name ||= (obj.class == ::Class) ? obj.name : obj.class.name
-    end
-
-  end
-
+  # Check if a method is locked on an object.
+  #
+  # @note Subject mode - this is expected to be called on an object that has LockAndCache mixed in. See also standalone mode.
   def lock_and_cache_locked?(method_id, *key_parts)
-    debug = (ENV['LOCK_AND_CACHE_DEBUG'] == 'true')
-    key = LockAndCache::Key.new self, method_id, key_parts
-    LockAndCache.storage.exists key.lock_digest
+    key = LockAndCache::Key.new key_parts, context: self, method_id: method_id
+    key.locked?
   end
 
   # Clear a lock and cache given exactly the method and exactly the same arguments
+  #
+  # @note Subject mode - this is expected to be called on an object that has LockAndCache mixed in. See also standalone mode.
   def lock_and_cache_clear(method_id, *key_parts)
-    debug = (ENV['LOCK_AND_CACHE_DEBUG'] == 'true')
-    key = LockAndCache::Key.new self, method_id, key_parts
-    Thread.exclusive { $stderr.puts "[lock_and_cache] clear #{key.debug} #{Base64.encode64(key.digest).strip} #{Digest::SHA1.hexdigest key.digest}" } if debug
-    LockAndCache.storage.del key.digest
-    LockAndCache.storage.del key.lock_digest
+    key = LockAndCache::Key.new key_parts, context: self, method_id: method_id
+    key.clear
   end
 
   # Lock and cache a method given key parts.
   #
-  # @param key_parts [*] Parts that you want to include in the lock and cache key
+  # This is the defining characteristic of context mode: the cache key will automatically include the class name of the object calling it (the context!) and the name of the method it is called from.
+  #
+  # @param key_parts_and_options [*] Parts that you want to include in the lock and cache key. If the last element is a Hash, it will be treated as options.
   #
   # @return The cached value (possibly newly calculated).
-  def lock_and_cache(*key_parts)
-    raise "need a block" unless block_given?
-    debug = (ENV['LOCK_AND_CACHE_DEBUG'] == 'true')
-    caller[0] =~ /in `([^']+)'/
-    method_id = $1 or raise "couldn't get method_id from #{caller[0]}"
-    options = key_parts.last.is_a?(Hash) ? key_parts.pop.stringify_keys : {}
-    expires = options['expires']
-    max_lock_wait = options.fetch 'max_lock_wait', LockAndCache.max_lock_wait
-    key = LockAndCache::Key.new self, method_id, key_parts
-    digest = key.digest
-    storage = LockAndCache.storage or raise("must set LockAndCache.storage=[Redis]")
-    Thread.exclusive { $stderr.puts "[lock_and_cache] A1 #{key.debug} #{Base64.encode64(digest).strip} #{Digest::SHA1.hexdigest digest}" } if debug
-    if storage.exists(digest) and (existing = storage.get(digest)).is_a?(String)
-      return ::Marshal.load(existing)
-    end
-    Thread.exclusive { $stderr.puts "[lock_and_cache] B1 #{key.debug} #{Base64.encode64(digest).strip} #{Digest::SHA1.hexdigest digest}" } if debug
-    retval = nil
-    lock_manager = LockAndCache.lock_manager
-    lock_digest = key.lock_digest
-    lock_info = nil
-    begin
-      Timeout.timeout(max_lock_wait, TimeoutWaitingForLock) do
-        until lock_info = lock_manager.lock(lock_digest, LockAndCache::LOCK_HEARTBEAT_EXPIRES*1000)
-          Thread.exclusive { $stderr.puts "[lock_and_cache] C1 #{key.debug} #{Base64.encode64(digest).strip} #{Digest::SHA1.hexdigest digest}" } if debug
-          sleep rand
-        end
-      end
-      Thread.exclusive { $stderr.puts "[lock_and_cache] D1 #{key.debug} #{Base64.encode64(digest).strip} #{Digest::SHA1.hexdigest digest}" } if debug
-      if storage.exists(digest) and (existing = storage.get(digest)).is_a?(String)
-        Thread.exclusive { $stderr.puts "[lock_and_cache] E1 #{key.debug} #{Base64.encode64(digest).strip} #{Digest::SHA1.hexdigest digest}" } if debug
-        retval = ::Marshal.load existing
-      end
-      unless retval
-        Thread.exclusive { $stderr.puts "[lock_and_cache] F1 #{key.debug} #{Base64.encode64(digest).strip} #{Digest::SHA1.hexdigest digest}" } if debug
-        done = false
-        begin
-          lock_extender = Thread.new do
-            loop do
-              Thread.exclusive { $stderr.puts "[lock_and_cache] heartbeat1 #{key.debug} #{Base64.encode64(digest).strip} #{Digest::SHA1.hexdigest digest}" } if debug
-              break if done
-              sleep LockAndCache::LOCK_HEARTBEAT_PERIOD
-              break if done
-              Thread.exclusive { $stderr.puts "[lock_and_cache] heartbeat2 #{key.debug} #{Base64.encode64(digest).strip} #{Digest::SHA1.hexdigest digest}" } if debug
-              lock_manager.lock lock_digest, LockAndCache::LOCK_HEARTBEAT_EXPIRES*1000, extend: lock_info
-            end
-          end
-          retval = yield
-          if expires
-            storage.setex digest, expires, ::Marshal.dump(retval)
-          else
-            storage.set digest, ::Marshal.dump(retval)
-          end
-        ensure
-          done = true
-          lock_extender.join if lock_extender.status.nil?
-        end
-      end
-    ensure
-      lock_manager.unlock lock_info if lock_info
-    end
-    retval
+  #
+  # @note Subject mode - this is expected to be called on an object that has LockAndCache mixed in. See also standalone mode.
+  #
+  # @note A single hash arg is treated as an options hash. `lock_and_cache(expires: 100)` will be treated as options `expires: 100`. This is the opposite of standalone mode and true because we want to support people constructing cache keys from the context (context) PLUS an arbitrary hash of stuff.
+  def lock_and_cache(*key_parts_and_options, &blk)
+    options = key_parts_and_options.last.is_a?(Hash) ? key_parts_and_options.pop : {}
+    key = LockAndCache::Key.new key_parts_and_options, context: self, caller: caller
+    action = LockAndCache::Action.new key, options, blk
+    action.perform
   end
 end

data/lib/lock_and_cache/action.rb

@@ -0,0 +1,105 @@
+module LockAndCache
+  # @private
+  class Action
+    attr_reader :key
+    attr_reader :options
+    attr_reader :blk
+
+    def initialize(key, options, blk)
+      raise "need a block" unless blk
+      @key = key
+      @options = options.stringify_keys
+      @blk = blk
+    end
+
+    def expires
+      options['expires']
+    end
+
+    def nil_expires
+      options['nil_expires']
+    end
+
+    def digest
+      @digest ||= key.digest
+    end
+
+    def lock_digest
+      @lock_digest ||= key.lock_digest
+    end
+
+    def storage
+      @storage ||= LockAndCache.storage or raise("must set LockAndCache.storage=[Redis]")
+    end
+
+    def perform
+      debug = (ENV['LOCK_AND_CACHE_DEBUG'] == 'true')
+      max_lock_wait = options.fetch 'max_lock_wait', LockAndCache.max_lock_wait
+      Thread.exclusive { $stderr.puts "[lock_and_cache] A1 #{key.debug} #{Base64.encode64(digest).strip} #{Digest::SHA1.hexdigest digest}" } if debug
+      if storage.exists(digest) and (existing = storage.get(digest)).is_a?(String)
+        return ::Marshal.load(existing)
+      end
+      Thread.exclusive { $stderr.puts "[lock_and_cache] B1 #{key.debug} #{Base64.encode64(digest).strip} #{Digest::SHA1.hexdigest digest}" } if debug
+      retval = nil
+      lock_manager = LockAndCache.lock_manager
+      lock_info = nil
+      begin
+        Timeout.timeout(max_lock_wait, TimeoutWaitingForLock) do
+          until lock_info = lock_manager.lock(lock_digest, LockAndCache::LOCK_HEARTBEAT_EXPIRES*1000)
+            Thread.exclusive { $stderr.puts "[lock_and_cache] C1 #{key.debug} #{Base64.encode64(digest).strip} #{Digest::SHA1.hexdigest digest}" } if debug
+            sleep rand
+          end
+        end
+        Thread.exclusive { $stderr.puts "[lock_and_cache] D1 #{key.debug} #{Base64.encode64(digest).strip} #{Digest::SHA1.hexdigest digest}" } if debug
+        if storage.exists(digest) and (existing = storage.get(digest)).is_a?(String)
+          Thread.exclusive { $stderr.puts "[lock_and_cache] E1 #{key.debug} #{Base64.encode64(digest).strip} #{Digest::SHA1.hexdigest digest}" } if debug
+          retval = ::Marshal.load existing
+        end
+        unless retval
+          Thread.exclusive { $stderr.puts "[lock_and_cache] F1 #{key.debug} #{Base64.encode64(digest).strip} #{Digest::SHA1.hexdigest digest}" } if debug
+          done = false
+          begin
+            lock_extender = Thread.new do
+              loop do
+                Thread.exclusive { $stderr.puts "[lock_and_cache] heartbeat1 #{key.debug} #{Base64.encode64(digest).strip} #{Digest::SHA1.hexdigest digest}" } if debug
+                break if done
+                sleep LockAndCache::LOCK_HEARTBEAT_PERIOD
+                break if done
+                Thread.exclusive { $stderr.puts "[lock_and_cache] heartbeat2 #{key.debug} #{Base64.encode64(digest).strip} #{Digest::SHA1.hexdigest digest}" } if debug
+                lock_manager.lock lock_digest, LockAndCache::LOCK_HEARTBEAT_EXPIRES*1000, extend: lock_info
+              end
+            end
+            retval = blk.call
+            retval.nil? ? set_nil : set_non_nil(retval)
+          ensure
+            done = true
+            lock_extender.join if lock_extender.status.nil?
+          end
+        end
+      ensure
+        lock_manager.unlock lock_info if lock_info
+      end
+      retval
+    end
+
+    NIL = Marshal.dump nil
+    def set_nil
+      if nil_expires
+        storage.setex digest, nil_expires, NIL
+      elsif expires
+        storage.setex digest, expires, NIL
+      else
+        storage.set digest, NIL
+      end
+    end
+
+    def set_non_nil(retval)
+      raise "expected not null #{retval.inspect}" if retval.nil?
+      if expires
+        storage.setex digest, expires, ::Marshal.dump(retval)
+      else
+        storage.set digest, ::Marshal.dump(retval)
+      end
+    end
+  end
+end

data/lib/lock_and_cache/key.rb

@@ -0,0 +1,81 @@
+module LockAndCache
+  # @private
+  class Key
+    class << self
+      # @private
+      #
+      # Extract the method id from a method's caller array.
+      def extract_method_id_from_caller(kaller)
+        kaller[0] =~ METHOD_NAME_IN_CALLER
+        raise "couldn't get method_id from #{kaller[0]}" unless $1
+        $1.to_sym
+      end
+
+      # @private
+      #
+      # Get a context object's class name, which is its own name if it's an object.
+      def extract_class_name(context)
+        (self.class == ::Class) ? self.name : self.class.name
+      end
+    end
+
+    METHOD_NAME_IN_CALLER = /in `([^']+)'/
+
+    attr_reader :method_id
+    attr_reader :class_name
+
+    def initialize(parts, options = {})
+      @_parts = parts
+      @method_id = if options.has_key?(:method_id)
+        options[:method_id]
+      elsif options.has_key?(:caller)
+        Key.extract_method_id_from_caller options[:caller]
+      end
+      @class_name = Key.extract_class_name options[:context] if options.has_key?(:context)
+    end
+
+    # A (non-cryptographic) digest of the key parts for use as the cache key
+    def digest
+      @digest ||= ::Digest::SHA1.hexdigest ::Marshal.dump(key)
+    end
+
+    # A (non-cryptographic) digest of the key parts for use as the lock key
+    def lock_digest
+      @lock_digest ||= 'lock/' + digest
+    end
+
+    # A human-readable representation of the key parts
+    def key
+      @key ||= if method_id
+        [class_name, method_id, parts]
+      else
+        parts
+      end
+    end
+
+    def locked?
+      LockAndCache.storage.exists lock_digest
+    end
+
+    def clear
+      Thread.exclusive { $stderr.puts "[lock_and_cache] clear #{debug} #{Base64.encode64(digest).strip} #{Digest::SHA1.hexdigest digest}" } if ENV['LOCK_AND_CACHE_DEBUG'] == 'true'
+      storage = LockAndCache.storage
+      storage.del digest
+      storage.del lock_digest
+    end
+
+    alias debug key
+
+    # An array of the parts we use for the key
+    def parts
+      @parts ||= @_parts.map do |v|
+        case v
+        when ::String, ::Symbol, ::Hash, ::Array
+          v
+        else
+          v.respond_to?(:lock_and_cache_key) ? v.lock_and_cache_key : v.id
+        end
+      end
+    end
+  end
+end

data/lib/lock_and_cache/version.rb

@@ -1,3 +1,3 @@
 module LockAndCache
-  VERSION = '2.0.2'
+  VERSION = '2.1.0'
 end

data/spec/lock_and_cache_spec.rb

@@ -7,6 +7,8 @@ class Foo
     @id = id
     @count = 0
     @count_exp = 0
+    @click_single_hash_arg_as_options = 0
+    @click_last_hash_as_options = 0
   end
 
   def click
@@ -22,11 +24,25 @@ class Foo
   end
 
   def click_exp
-    lock_and_cache(expires: 1, foo: :bar) do
+    lock_and_cache(expires: 1) do
       @count_exp += 1
     end
   end
 
+  # foo will be treated as option, so this is cacheable
+  def click_single_hash_arg_as_options
+    lock_and_cache(foo: rand, expires: 1) do
+      @click_single_hash_arg_as_options += 1
+    end
+  end
+
+  # foo will be treated as part of cache key, so this is uncacheable
+  def click_last_hash_as_options
+    lock_and_cache({foo: rand}, expires: 1) do
+      @click_last_hash_as_options += 1
+    end
+  end
+
   def lock_and_cache_key
     @id
   end
@@ -114,7 +130,7 @@ describe LockAndCache do
     it "can be expired" do
       expect(foo.click_exp).to eq(1)
       expect(foo.click_exp).to eq(1)
-      sleep 2
+      sleep 1.5
       expect(foo.click_exp).to eq(2)
     end
 
@@ -122,6 +138,20 @@ describe LockAndCache do
       expect(foo.click_null).to eq(nil)
       expect(foo.click_null).to eq(nil)
     end
+
+    it "treats single hash arg as options" do
+      expect(foo.click_single_hash_arg_as_options).to eq(1)
+      expect(foo.click_single_hash_arg_as_options).to eq(1)
+      sleep 1.1
+      expect(foo.click_single_hash_arg_as_options).to eq(2)
+    end
+
+    it "treats last hash as options" do
+      expect(foo.click_last_hash_as_options).to eq(1)
+      expect(foo.click_last_hash_as_options).to eq(2) # it's uncacheable to prove we're not using as part of options
+      expect(foo.click_last_hash_as_options).to eq(3)
+    end
+
   end
 
   describe "locking" do
@@ -237,17 +267,100 @@ describe LockAndCache do
 
   end
 
-  describe 'keying' do
-    it "doesn't conflate symbol and string args" do
-      symbol = LockAndCache::Key.new(Foo.new(:me), :click, a: 1)
-      string = LockAndCache::Key.new(Foo.new(:me), :click, 'a' => 1)
-      expect(symbol.digest).not_to eq(string.digest)
+  describe 'standalone' do
+    it 'works like you expect' do
+      count = 0
+      expect(LockAndCache.lock_and_cache('hello') { count += 1 }).to eq(1)
+      expect(count).to eq(1)
+      expect(LockAndCache.lock_and_cache('hello') { count += 1 }).to eq(1)
+      expect(count).to eq(1)
+    end
+
+    it 'allows expiry' do
+      count = 0
+      expect(LockAndCache.lock_and_cache('hello', expires: 1) { count += 1 }).to eq(1)
+      expect(count).to eq(1)
+      expect(LockAndCache.lock_and_cache('hello') { count += 1 }).to eq(1)
+      expect(count).to eq(1)
+      sleep 1.1
+      expect(LockAndCache.lock_and_cache('hello') { count += 1 }).to eq(2)
+      expect(count).to eq(2)
+    end
+
+    it 'allows clearing' do
+      count = 0
+      expect(LockAndCache.lock_and_cache('hello') { count += 1 }).to eq(1)
+      expect(count).to eq(1)
+      LockAndCache.clear('hello')
+      expect(LockAndCache.lock_and_cache('hello') { count += 1 }).to eq(2)
+      expect(count).to eq(2)
+    end
+
+    it 'allows multi-part keys' do
+      count = 0
+      expect(LockAndCache.lock_and_cache(['hello', 1, { target: 'world' }]) { count += 1 }).to eq(1)
+      expect(count).to eq(1)
+      expect(LockAndCache.lock_and_cache(['hello', 1, { target: 'world' }]) { count += 1 }).to eq(1)
+      expect(count).to eq(1)
+    end
+    
+    it 'treats a single hash arg as a cache key (not as options)' do
+      count = 0
+      LockAndCache.lock_and_cache(hello: 'world', expires: 100) { count += 1 }
+      expect(count).to eq(1)
+      LockAndCache.lock_and_cache(hello: 'world', expires: 100) { count += 1 }
+      expect(count).to eq(1)
+      LockAndCache.lock_and_cache(hello: 'world', expires: 200) { count += 1 } # expires is being treated as part of cache key
+      expect(count).to eq(2)
+    end
+
+    it "correctly identifies options hash" do
+      count = 0
+      LockAndCache.lock_and_cache({ hello: 'world' }, expires: 1, ignored: rand) { count += 1 }
+      expect(count).to eq(1)
+      LockAndCache.lock_and_cache({ hello: 'world' }, expires: 1, ignored: rand) { count += 1 } # expires is not being treated as part of cache key
+      expect(count).to eq(1)
+      sleep 1.1
+      LockAndCache.lock_and_cache({ hello: 'world' }) { count += 1 }
+      expect(count).to eq(2)
+    end
+  end
+
+  describe "shorter expiry for null results" do
+    it "optionally caches null for less time" do
+      count = 0
+      LockAndCache.lock_and_cache('hello', nil_expires: 1, expires: 2) { count += 1; nil }
+      expect(count).to eq(1)
+      LockAndCache.lock_and_cache('hello', nil_expires: 1, expires: 2) { count += 1; nil }
+      expect(count).to eq(1)
+      sleep 1.1 # this is enough to expire
+      LockAndCache.lock_and_cache('hello', nil_expires: 1, expires: 2) { count += 1; nil }
+      expect(count).to eq(2)
     end
 
-    it "cares about order" do
-      symbol = LockAndCache::Key.new(Foo.new(:me), :click, {a: 1, b: 2})
-      string = LockAndCache::Key.new(Foo.new(:me), :click, {b: 2, a: 1})
-      expect(symbol.digest).not_to eq(string.digest)
+    it "normally caches null for the same amount of time" do
+      count = 0
+      expect(LockAndCache.lock_and_cache('hello', expires: 1) { count += 1; nil }).to be_nil
+      expect(count).to eq(1)
+      expect(LockAndCache.lock_and_cache('hello', expires: 1) { count += 1; nil }).to be_nil
+      expect(count).to eq(1)
+      sleep 1.1
+      expect(LockAndCache.lock_and_cache('hello', expires: 1) { count += 1; nil }).to be_nil
+      expect(count).to eq(2)
+    end
+
+    it "caches non-null for normal time" do
+      count = 0
+      LockAndCache.lock_and_cache('hello', nil_expires: 1, expires: 2) { count += 1; true }
+      expect(count).to eq(1)
+      LockAndCache.lock_and_cache('hello', nil_expires: 1, expires: 2) { count += 1; true }
+      expect(count).to eq(1)
+      sleep 1.1
+      LockAndCache.lock_and_cache('hello', nil_expires: 1, expires: 2) { count += 1; true }
+      expect(count).to eq(1)
+      sleep 1
+      LockAndCache.lock_and_cache('hello', nil_expires: 1, expires: 2) { count += 1; true }
+      expect(count).to eq(2)
     end
   end
 

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: lock_and_cache
 version: !ruby/object:Gem::Version
-  version: 2.0.2
+  version: 2.1.0
 platform: ruby
 authors:
 - Seamus Abshere
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2015-10-16 00:00:00.000000000 Z
+date: 2015-10-26 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport
@@ -168,6 +168,8 @@ files:
 - README.md
 - Rakefile
 - lib/lock_and_cache.rb
+- lib/lock_and_cache/action.rb
+- lib/lock_and_cache/key.rb
 - lib/lock_and_cache/version.rb
 - lock_and_cache.gemspec
 - spec/lock_and_cache_spec.rb