redis-mutex 1.3.5 → 2.0.0

data/README.md

@@ -13,7 +13,7 @@ Synopsis
 In the following example, only one thread / process / server can enter the locked block at one time.
 
 ```ruby
-Redis::Mutex.lock(:your_lock_name)
+Redis::Mutex.with_lock(:your_lock_name) do
   # do something exclusively
 end
 ```
@@ -26,7 +26,7 @@ if mutex.lock
   # do something exclusively
   mutex.unlock
 else
-  puts "failed to obtain lock!"
+  puts "failed to acquire lock!"
 end
 ```
 
@@ -37,6 +37,13 @@ that you can configure any of these timing values, as explained later.
 
 Or if you want to immediately receive `false` on an unsuccessful locking attempt, you can change the mutex mode to **non-blocking**.
 
+Changes in v2.0
+---------------
+
+* **Exception-based control flow**: Added `lock!` and `unlock!`, which raises an exception when fails to acquire a lock. Raises `Redis::Mutex::LockError` and `Redis::Mutex::UnlockError` respectively.
+* **INCOMPATIBLE CHANGE**: `#lock` no longer accepts a block. Use `#with_lock` instead, which uses `lock!` internally and returns the value of block.
+* `unlock` returns boolean values for success / failure, for consistency with `lock`.
+
 Install
 -------
 
@@ -48,7 +55,7 @@ Usage
 In Gemfile:
 
 ```ruby
-gem "redis-mutex"
+gem 'redis-mutex'
 ```
 
 Register the Redis server: (e.g. in `config/initializers/redis_mutex.rb` for Rails)
@@ -59,15 +66,19 @@ Redis::Classy.db = Redis.new(:host => 'localhost')
 
 Note that Redis Mutex uses the `redis-classy` gem internally to organize keys in an isolated namespace.
 
-There are four methods - `new`, `lock`, `unlock` and `sweep`:
+There are a number of methods:
 
 ```ruby
 mutex = Redis::Mutex.new(key, options)    # Configure a mutex lock
-mutex.lock                                # Try to obtain the lock
-mutex.unlock                              # Release the lock if it's not expired
-Redis::Mutex.sweep                        # Forcibly remove all locks
-
-Redis::Mutex.lock(key, options)           # Shortcut to new + lock
+mutex.lock                                # Try to acquire the lock
+mutex.unlock                              # Try to release the lock
+mutex.lock!                               # Try to acquire the lock, raises exception when failed
+mutex.unlock!                             # Try to release the lock, raises exception when failed
+mutex.with_lock                           # Try to acquire the lock, execute the block, then return the value of the block.
+                                          # Raises exception when failed to acquire the lock.
+
+Redis::Mutex.sweep                        # Remove all expired locks
+Redis::Mutex.with_lock(key, options)      # Shortcut to new + with_lock
 ```
 
 The key argument can be symbol, string, or any Ruby objects that respond to `id` method, where the key is automatically set as
@@ -81,12 +92,12 @@ The initialize method takes several options.
 :block  => 1    # Specify in seconds how long you want to wait for the lock to be released.
                 # Speficy 0 if you need non-blocking sematics and return false immediately. (default: 1)
 :sleep  => 0.1  # Specify in seconds how long the polling interval should be when :block is given.
-                # It is recommended that you do NOT go below 0.01. (default: 0.1)
-:expire => 10   # Specify in seconds when the lock should forcibly be removed when something went wrong
-                # with the one who held the lock. (default: 10)
+                # It is NOT recommended to go below 0.01. (default: 0.1)
+:expire => 10   # Specify in seconds when the lock should be considered stale when something went wrong
+                # with the one who held the lock and failed to unlock. (default: 10)
 ```
 
-The lock method returns `true` when the lock has been successfully obtained, or returns `false` when the attempts failed after
+The lock method returns `true` when the lock has been successfully acquired, or returns `false` when the attempts failed after
 the seconds specified with **:block**. When 0 is given to **:block**, it is set to **non-blocking** mode and immediately returns `false`.
 
 In the following Rails example, only one request can enter to a given room.
@@ -96,29 +107,31 @@ class RoomController < ApplicationController
   before_filter { @room = Room.find(params[:id]) }
   
   def enter
-    success = Redis::Mutex.lock(@room) do    # key => "Room:123"
+    Redis::Mutex.with_lock(@room) do    # key => "Room:123"
       # do something exclusively
     end
-    render :text => success ? 'success!' : 'failed to obtain lock!'
+    render text: 'success!'
+  rescue Redis::Mutex::LockError
+    render text: 'failed to acquire lock!'
   end
 end
 ```
 
-Note that you need to explicitly call the unlock method when you don't use the block syntax, and it is recommended to
-put the `unlock` method in the `ensure` clause unless you're sure your code won't raise any exception.
+Note that you need to explicitly call the `unlock` method when you don't use `with_lock` and its block syntax. Also it is recommended to
+put the `unlock` method in the `ensure` clause.
 
 ```ruby
 def enter
-  mutex = Redis::Mutex.new('non-blocking', :block => 0, :expire => 10.minutes)
+  mutex = Redis::Mutex.new('non-blocking', block: 0, expire: 10.minutes)
   if mutex.lock
     begin
       # do something exclusively
     ensure
       mutex.unlock
     end
-    render :text => 'success!'
+    render text: 'success!'
   else
-    render :text => 'failed to obtain lock!'
+    render text: 'failed to acquire lock!'
   end
 end
 ```
@@ -134,11 +147,11 @@ If you give a proc object to the `after_failure` option, it will get called afte
 ```ruby
 class JobController < ApplicationController
   include Redis::Mutex::Macro
-  auto_mutex :run, :block => 0, :after_failure => lambda { render :text => "failed to obtain lock!" }
-  
+  auto_mutex :run, block: 0, after_failure: lambda { render text: 'failed to acquire lock!' }
+
   def run
     # do something exclusively
-    render :text => "success!"
+    render text: 'success!'
   end
 end
 ```

data/lib/redis/mutex.rb

@@ -12,8 +12,10 @@ class Redis
   class Mutex < Redis::Classy
     autoload :Macro, 'redis/mutex/macro'
 
-    attr_reader :locking
     DEFAULT_EXPIRE = 10
+    LockError = Class.new(StandardError)
+    UnlockError = Class.new(StandardError)
+    AssertionError = Class.new(StandardError)
 
     def initialize(object, options={})
       super(object.is_a?(String) || object.is_a?(Symbol) ? object : "#{object.class.name}:#{object.id}")
@@ -23,6 +25,7 @@ class Redis
     end
 
     def lock
+      self.class.raise_assertion_error if block_given?
       @locking = false
 
       if @block > 0
@@ -30,66 +33,92 @@ class Redis
         start_at = Time.now
         while Time.now - start_at < @block
           @locking = true and break if try_lock
-          Kernel.sleep @sleep
+          sleep @sleep
         end
       else
         # Non-blocking mode
         @locking = try_lock
       end
-      success = @locking # Backup
+      @locking
+    end
+
+    def try_lock
+      now = Time.now.to_f
+      @expires_at = now + @expire                       # Extend in each blocking loop
+      return true   if setnx(@expires_at)               # Success, the lock has been acquired
+      return false  if get.to_f > now                   # Check if the lock is still effective
+
+      # The lock has expired but wasn't released... BAD!
+      return true   if getset(@expires_at).to_f <= now   # Success, we acquired the previously expired lock
+      return false  # Dammit, it seems that someone else was even faster than us to remove the expired lock!
+    end
+
+    def unlock(force = false)
+      # Since it's possible that the operations in the critical section took a long time,
+      # we can't just simply release the lock. The unlock method checks if @expires_at
+      # remains the same, and do not release when the lock timestamp was overwritten.
+
+      if get == @expires_at.to_s or force
+        # Redis#del with a single key returns '1' or nil
+        !!del
+      else
+        false
+      end
+    end
 
-      if block_given? and @locking
+    def with_lock
+      if lock!
         begin
-          yield
+          @result = yield
         ensure
-          # Since it's possible that the yielded operation took a long time, we can't just simply
-          # Release the lock. The unlock method checks if the expires_at remains the same that you
-          # set, and do not release it when the lock timestamp was overwritten.
           unlock
         end
       end
-
-      success
+      @result
     end
 
-    def try_lock
-      now = Time.now.to_f
-      @expires_at = now + @expire                             # Extend in each blocking loop
-      return true   if self.setnx(@expires_at)                # Success, the lock has been acquired
-      return false  if self.get.to_f > now                    # Check if the lock is still effective
-
-      # The lock has expired but wasn't released... BAD!
-      return true   if self.getset(@expires_at).to_f <= now   # Success, we acquired the previously expired lock
-      return false  # Dammit, it seems that someone else was even faster than us to remove the expired lock!
+    def lock!
+      lock or raise LockError, "failed to acquire lock #{key.inspect}"
     end
 
-    def unlock(force=false)
-      @locking = false
-      self.del if self.get == @expires_at.to_s or force       # Release the lock if it seems to be yours
+    def unlock!(force = false)
+      unlock(force) or raise UnlockError, "failed to release lock #{key.inspect}"
     end
 
     class << self
       def sweep
-        return 0 if (all_keys = self.keys).empty?
+        return 0 if (all_keys = keys).empty?
 
         now = Time.now.to_f
-        values = self.mget(*all_keys)
+        values = mget(*all_keys)
 
-        expired_keys = [].tap do |array|
-          all_keys.each_with_index do |key, i|
-            array << key if !values[i].nil? and values[i].to_f <= now
-          end
+        expired_keys = all_keys.zip(values).select do |key, time|
+          time && time.to_f <= now
         end
 
-        expired_keys.each do |key|
-          self.del(key) if self.getset(key, now + DEFAULT_EXPIRE).to_f <= now # Make extra sure that anyone haven't extended the lock
+        expired_keys.each do |key, _|
+          # Make extra sure that anyone haven't extended the lock
+          del(key) if getset(key, now + DEFAULT_EXPIRE).to_f <= now
         end
 
         expired_keys.size
       end
 
-      def lock(object, options={}, &block)
-        new(object, options).lock(&block)
+      def lock(object, options = {})
+        raise_assertion_error if block_given?
+        new(object, options).lock
+      end
+
+      def lock!(object, options = {})
+        new(object, options).lock!
+      end
+
+      def with_lock(object, options = {}, &block)
+        new(object, options).with_lock(&block)
+      end
+
+      def raise_assertion_error
+        raise AssertionError, 'block syntax has been removed from #lock, use #with_lock instead'
       end
     end
   end

data/lib/redis/mutex/macro.rb

@@ -31,17 +31,14 @@ class Redis
 
           define_method(with_method) do |*args|
             key = self.class.name << '#' << target.to_s
-            response = nil
 
-            success = Redis::Mutex.lock(key, options) do
-              response = send(without_method, *args)
+            begin
+              Redis::Mutex.with_lock(key, options) do
+                send(without_method, *args)
+              end
+            rescue Redis::Mutex::LockError
+              send(after_method, *args) if respond_to?(after_method)
             end
-
-            if !success and respond_to?(after_method)
-              response = send(after_method, *args)
-            end
-
-            response
           end
 
           alias_method without_method, target

data/redis-mutex.gemspec

@@ -12,9 +12,9 @@ Gem::Specification.new do |gem|
   gem.test_files    = gem.files.grep(%r{^(test|spec|features)/})
   gem.name          = "redis-mutex"
   gem.require_paths = ["lib"]
-  gem.version       = '1.3.5' # retrieve this value by: Gem.loaded_specs['redis-mutex'].version.to_s
+  gem.version       = '2.0.0' # retrieve this value by: Gem.loaded_specs['redis-mutex'].version.to_s
 
-  gem.add_runtime_dependency "redis-classy", "~> 1.0"
+  gem.add_runtime_dependency "redis-classy", "~> 1.2"
   gem.add_development_dependency "rspec"
   gem.add_development_dependency "bundler"
 

data/spec/redis_mutex_spec.rb

@@ -1,49 +1,79 @@
-require File.expand_path(File.dirname(__FILE__) + '/spec_helper')
+require 'spec_helper'
+
+SHORT_MUTEX_OPTIONS = { :block => 0.1, :sleep => 0.02 }
+
+class C
+  include Redis::Mutex::Macro
+  auto_mutex :run_singularly, :block => 0, :after_failure => lambda {|id| return "failure: #{id}" }
+
+  def run_singularly(id)
+    sleep 0.1
+    return "success: #{id}"
+  end
+end
 
 describe Redis::Mutex do
   before do
     Redis::Classy.flushdb
-    @short_mutex_options = { :block => 0.1, :sleep => 0.02 }
   end
 
-  after do
+  after :all do
     Redis::Classy.flushdb
+    Redis::Classy.quit
   end
 
-  it "should set the value to the expiration" do
+  it 'locks the universe' do
+    mutex1 = Redis::Mutex.new(:test_lock, SHORT_MUTEX_OPTIONS)
+    mutex1.lock.should be_true
+
+    mutex2 = Redis::Mutex.new(:test_lock, SHORT_MUTEX_OPTIONS)
+    mutex2.lock.should be_false
+  end
+
+  it 'fails to lock when the lock is taken' do
+    mutex1 = Redis::Mutex.new(:test_lock, SHORT_MUTEX_OPTIONS)
+
+    mutex2 = Redis::Mutex.new(:test_lock, SHORT_MUTEX_OPTIONS)
+    mutex2.lock.should be_true    # mutex2 beats us to it
+
+    mutex1.lock.should be_false   # fail
+  end
+
+  it 'unlocks only once' do
+    mutex = Redis::Mutex.new(:test_lock, SHORT_MUTEX_OPTIONS)
+    mutex.lock.should be_true
+
+    mutex.unlock.should be_true   # successfully released the lock
+    mutex.unlock.should be_false  # the lock no longer exists
+  end
+
+  it 'prevents accidental unlock from outside' do
+    mutex1 = Redis::Mutex.new(:test_lock, SHORT_MUTEX_OPTIONS)
+    mutex1.lock.should be_true
+
+    mutex2 = Redis::Mutex.new(:test_lock, SHORT_MUTEX_OPTIONS)
+    mutex2.unlock.should be_false
+  end
+
+  it 'sets expiration' do
     start = Time.now
     expires_in = 10
     mutex = Redis::Mutex.new(:test_lock, :expire => expires_in)
-    mutex.lock do
+    mutex.with_lock do
       mutex.get.to_f.should be_within(1.0).of((start + expires_in).to_f)
     end
-    # key should have been cleaned up
-    mutex.get.should be_nil
+    mutex.get.should be_nil   # key should have been cleaned up
   end
 
-  it "should get a lock when existing lock is expired" do
-    mutex = Redis::Mutex.new(:test_lock)
-    # locked in the far past
+  it 'overwrites a lock when existing lock is expired' do
+    # stale lock from the far past
     Redis::Mutex.set(:test_lock, Time.now - 60)
 
+    mutex = Redis::Mutex.new(:test_lock)
     mutex.lock.should be_true
-    mutex.get.should_not be_nil
-    mutex.unlock
-    mutex.get.should be_nil
-  end
-
-  it "should not get a lock when existing lock is still effective" do
-    mutex = Redis::Mutex.new(:test_lock, @short_mutex_options)
-
-    # someone beats us to it
-    mutex2 = Redis::Mutex.new(:test_lock, @short_mutex_options)
-    mutex2.lock
-
-    mutex.lock.should be_false    # should not have the lock
-    mutex.get.should_not be_nil   # lock value should still be set
   end
 
-  it "should not remove the key if lock is held past expiration" do
+  it 'fails to unlock the key if it took too long past expiration' do
     mutex = Redis::Mutex.new(:test_lock, :expire => 0.1, :block => 0)
     mutex.lock.should be_true
     sleep 0.2   # lock expired
@@ -56,38 +86,67 @@ describe Redis::Mutex do
     mutex.get.should_not be_nil   # lock should still be there
   end
 
-  it "should ensure unlock when something goes wrong in the block" do
+  it 'ensures unlocking when something goes wrong in the block' do
     mutex = Redis::Mutex.new(:test_lock)
     begin
-      mutex.lock do
+      mutex.with_lock do
         raise "Something went wrong!"
       end
-    rescue
-      mutex.locking.should be_false
+    rescue RuntimeError
+      mutex.get.should be_nil
     end
   end
 
-  it "should reset locking state on reuse" do
-    mutex = Redis::Mutex.new(:test_lock, @short_mutex_options)
+  it 'resets locking state on reuse' do
+    mutex = Redis::Mutex.new(:test_lock, SHORT_MUTEX_OPTIONS)
     mutex.lock.should be_true
     mutex.lock.should be_false
   end
 
-  describe Redis::Mutex::Macro do
-    it "should add auto_mutex" do
+  it 'returns value of block' do
+    Redis::Mutex.with_lock(:test_lock) { :test_result }.should == :test_result
+  end
 
-      class C
-        include Redis::Mutex::Macro
-        auto_mutex :run_singularly, :block => 0, :after_failure => lambda {|id| return "failure: #{id}" }
+  it 'requires block for #with_lock' do
+    expect { Redis::Mutex.with_lock(:test_lock) }.to raise_error(LocalJumpError) #=> no block given (yield)
+  end
 
-        def run_singularly(id)
-          sleep 0.1
-          return "success: #{id}"
-        end
-      end
+  it 'raises LockError if lock not obtained' do
+    expect { Redis::Mutex.lock!(:test_lock, SHORT_MUTEX_OPTIONS) }.to_not raise_error
+    expect { Redis::Mutex.lock!(:test_lock, SHORT_MUTEX_OPTIONS) }.to raise_error(Redis::Mutex::LockError)
+  end
 
+  it 'raises UnlockError if lock not obtained' do
+    mutex = Redis::Mutex.new(:test_lock)
+    mutex.lock.should be_true
+    mutex.unlock.should be_true
+    expect { mutex.unlock! }.to raise_error(Redis::Mutex::UnlockError)
+  end
+
+  it 'raises AssertionError when block is given to #lock' do
+    # instance method
+    mutex = Redis::Mutex.new(:test_lock)
+    expect { mutex.lock {} }.to raise_error(Redis::Mutex::AssertionError)
+
+    # class method
+    expect { Redis::Mutex.lock(:test_lock) {} }.to raise_error(Redis::Mutex::AssertionError)
+  end
+
+  it 'sweeps expired locks' do
+    Redis::Mutex.set(:past, Time.now.to_f - 60)
+    Redis::Mutex.set(:present, Time.now.to_f)
+    Redis::Mutex.set(:future, Time.now.to_f + 60)
+    Redis::Mutex.keys.size.should == 3
+    Redis::Mutex.sweep.should == 2
+    Redis::Mutex.keys.size.should == 1
+  end
+
+  describe Redis::Mutex::Macro do
+    it 'adds auto_mutex' do
       t1 = Thread.new { C.new.run_singularly(1).should == "success: 1" }
-      sleep 0.01 # In most cases t1 wins, but make sure to give it a head start, not exceeding the sleep inside the method
+      # In most cases t1 wins, but make sure to give it a head start,
+      # not exceeding the sleep inside the method.
+      sleep 0.01
       t2 = Thread.new { C.new.run_singularly(2).should == "failure: 2" }
       t1.join
       t2.join

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: redis-mutex
 version: !ruby/object:Gem::Version
-  version: 1.3.5
+  version: 2.0.0
   prerelease: 
 platform: ruby
 authors:
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2012-05-26 00:00:00.000000000 Z
+date: 2012-10-12 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: redis-classy
@@ -18,7 +18,7 @@ dependencies:
     requirements:
     - - ~>
       - !ruby/object:Gem::Version
-        version: '1.0'
+        version: '1.2'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
@@ -26,7 +26,7 @@ dependencies:
     requirements:
     - - ~>
       - !ruby/object:Gem::Version
-        version: '1.0'
+        version: '1.2'
 - !ruby/object:Gem::Dependency
   name: rspec
   requirement: !ruby/object:Gem::Requirement
@@ -107,19 +107,24 @@ required_ruby_version: !ruby/object:Gem::Requirement
   - - ! '>='
     - !ruby/object:Gem::Version
       version: '0'
+      segments:
+      - 0
+      hash: -331406254001747474
 required_rubygems_version: !ruby/object:Gem::Requirement
   none: false
   requirements:
   - - ! '>='
     - !ruby/object:Gem::Version
       version: '0'
+      segments:
+      - 0
+      hash: -331406254001747474
 requirements: []
 rubyforge_project: 
-rubygems_version: 1.8.19
+rubygems_version: 1.8.24
 signing_key: 
 specification_version: 3
 summary: Distrubuted mutex using Redis
 test_files:
 - spec/redis_mutex_spec.rb
 - spec/spec_helper.rb
-has_rdoc: