redis-mutex 1.2.2 → 1.2.3

data/Gemfile.lock

@@ -9,9 +9,9 @@ GEM
       rake
     rake (0.9.2.2)
     redis (2.2.2)
-    redis-classy (1.0.0)
-      redis-namespace (~> 1.0.0)
-    redis-namespace (1.0.3)
+    redis-classy (1.0.1)
+      redis-namespace (~> 1.0)
+    redis-namespace (1.1.0)
       redis (< 3.0.0)
     rspec (2.7.0)
       rspec-core (~> 2.7.0)

data/README.md

@@ -10,17 +10,30 @@ 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)
+  # do something exclusively
+end
+```
+
+or
+
 ```ruby
 mutex = Redis::Mutex.new(:your_lock_name)
-mutex.lock do
+if mutex.lock
   # do something exclusively
+  mutex.unlock
+else
+  puts "failed to obtain lock!"
 end
 ```
 
-By default, when one is holding a lock, others wait **1 second** in total, polling **every 100ms** to see if the lock was released.
-When 1 second has passed, the lock method returns `false`.
+By default, while one is holding a lock, others wait **1 second** in total, polling **every 100ms** to see if the lock was released.
+When 1 second has passed, the lock method returns `false` and others give up. Note that if your job runs longer than **10 seconds**,
+the lock will be automatically removed to avoid a deadlock situation in case your job is dead before releasing the lock. Also note
+that you can configure any of these timing values, as explained later.
 
-If you want to immediately receive `false` on an unsuccessful locking attempt, you can configure the mutex to work in the non-blocking mode, 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**.
 
 Install
 -------
@@ -42,21 +55,25 @@ Register the Redis server: (e.g. in `config/initializers/redis_mutex.rb` for Rai
 Redis::Classy.db = Redis.new(:host => 'localhost')
 ```
 
-Note that Redis Mutex uses the `redis-classy` gem internally.
+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`:
 
 ```ruby
-mutex = Redis::Mutex.new(key, options)
-mutex.lock
-mutex.unlock
-Redis::Mutex.sweep
+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
 ```
 
-For the key, it takes any Ruby objects that respond to :id, where the key is automatically set as "TheClass:id",
-or pass any string or symbol.
+The key argument can be symbol, string, or any Ruby objects that respond to `id` method, where the key is automatically set as
+`TheClass:id`. For any given key, `Redis::Mutex:` prefix will be automatically prepended. For instance, if you pass a `Room`
+object with id of `123`, the actual key in Redis will be `Redis::Mutex:Room:123`. The automatic prefixing and instance binding
+is the feature of `Redis::Classy` - for more internal details, refer to [Redis Classy](https://github.com/kenn/redis-classy).
 
-Also the initialize method takes several options.
+The initialize method takes several options.
 
 ```ruby
 :block  => 1    # Specify in seconds how long you want to wait for the lock to be released.
@@ -67,46 +84,59 @@ Also the initialize method takes several options.
                 # with the one who held the lock. (default: 10)
 ```
 
-The lock method returns `true` when the lock has been successfully obtained, or returns `false` when the attempts
-failed after the seconds specified with **:block**. It immediately returns `false` when 0 is given to **:block**.
+The lock method returns `true` when the lock has been successfully obtained, 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`.
 
-Here's a sample usage in a Rails app:
+In the following Rails example, only one request can enter to a given room.
 
 ```ruby
 class RoomController < ApplicationController
+  before_filter { @room = Room.find(params[:id]) }
+  
   def enter
-    @room = Room.find(params[:id])
-
-    mutex = Redis::Mutex.new(@room)   # key => "Room:123"
-    mutex.lock do
+    success = Redis::Mutex.lock(@room) do    # key => "Room:123"
       # do something exclusively
     end
+    render :text => success ? 'success!' : 'failed to obtain lock!'
   end
 end
 ```
 
-Note that you need to explicitly call the unlock method unless you don't use the block syntax.
-
-In the following example, 
+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.
 
 ```ruby
 def enter
   mutex = Redis::Mutex.new('non-blocking', :block => 0, :expire => 10.minutes)
-  mutex.lock
-  # do something exclusively
-  mutex.unlock
-rescue
-  mutex.unlock
-  raise
+  if mutex.lock
+    begin
+      # do something exclusively
+    ensure
+      mutex.unlock
+    end
+    render :text => 'success!'
+  else
+    render :text => 'failed to obtain lock!'
+  end
 end
 ```
 
-Also note that, internally, the actual key is structured in the following form:
+Macro-style definition
+----------------------
+
+If you want to wrap an entire method into a critical section, you can use the macro-style definition. The locking scope
+will be `TheClass#method` and only one method can run at any given time.
+
+If you give a proc object to the `after_failure` option, it will get called after locking attempt failed.
 
 ```ruby
- Redis.new.keys
- => ["Redis::Mutex:Room:111", "Redis::Mutex:Room:112", ... ]
+class JobController < ApplicationController
+  include Redis::Mutex::Macro
+  auto_mutex :run, :block => 0, :after_failure => lambda { render :text => "failed to obtain lock!" }
+  
+  def run
+    # do something exclusively
+    render :text => "success!"
+  end
+end
 ```
-
-The automatic prefixing and binding is the feature of `Redis::Classy`.
-For more internal details, refer to [Redis Classy](https://github.com/kenn/redis-classy).

data/VERSION

@@ -1 +1 @@
-1.2.2
+1.2.3

data/lib/redis/mutex.rb

@@ -11,7 +11,7 @@ class Redis
   #
   class Mutex < Redis::Classy
     autoload :Macro, 'redis/mutex/macro'
-    attr_reader :block, :sleep, :expire, :locking
+    attr_reader :locking
     DEFAULT_EXPIRE = 10
 
     def initialize(object, options={})
@@ -53,26 +53,26 @@ class Redis
 
     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
+      @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 getset(@expires_at).to_f <= now    # Success, we acquired the previously expired lock
+      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!
     end
 
     def unlock(force=false)
       @locking = false
-      del if get.to_f == @expires_at or force   # Release the lock if it seems to be yours
+      self.del if self.get.to_f == @expires_at or force       # Release the lock if it seems to be yours
     end
 
     class << self
       def sweep
-        return 0 if (all_keys = keys).empty?
+        return 0 if (all_keys = self.keys).empty?
 
         now = Time.now.to_f
-        values = mget(*all_keys)
+        values = self.mget(*all_keys)
 
         expired_keys = [].tap do |array|
           all_keys.each_with_index do |key, i|
@@ -81,7 +81,7 @@ class Redis
         end
 
         expired_keys.each do |key|
-          del(key) if getset(key, now + DEFAULT_EXPIRE).to_f <= now # Make extra sure that anyone haven't extended the lock
+          self.del(key) if self.getset(key, now + DEFAULT_EXPIRE).to_f <= now # Make extra sure that anyone haven't extended the lock
         end
 
         expired_keys.size

data/redis-mutex.gemspec

@@ -5,11 +5,11 @@
 
 Gem::Specification.new do |s|
   s.name = "redis-mutex"
-  s.version = "1.2.2"
+  s.version = "1.2.3"
 
   s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
   s.authors = ["Kenn Ejima"]
-  s.date = "2011-11-05"
+  s.date = "2011-11-11"
   s.description = "Distrubuted mutex using Redis"
   s.email = "kenn.ejima@gmail.com"
   s.extra_rdoc_files = [

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: redis-mutex
 version: !ruby/object:Gem::Version
-  version: 1.2.2
+  version: 1.2.3
   prerelease: 
 platform: ruby
 authors:
@@ -9,11 +9,11 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2011-11-05 00:00:00.000000000 Z
+date: 2011-11-11 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: redis-classy
-  requirement: &2162029080 !ruby/object:Gem::Requirement
+  requirement: &2154746560 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ~>
@@ -21,10 +21,10 @@ dependencies:
         version: 1.0.0
   type: :runtime
   prerelease: false
-  version_requirements: *2162029080
+  version_requirements: *2154746560
 - !ruby/object:Gem::Dependency
   name: rspec
-  requirement: &2161974220 !ruby/object:Gem::Requirement
+  requirement: &2154745900 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -32,10 +32,10 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *2161974220
+  version_requirements: *2154745900
 - !ruby/object:Gem::Dependency
   name: bundler
-  requirement: &2161971780 !ruby/object:Gem::Requirement
+  requirement: &2154744920 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -43,10 +43,10 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *2161971780
+  version_requirements: *2154744920
 - !ruby/object:Gem::Dependency
   name: jeweler
-  requirement: &2161970380 !ruby/object:Gem::Requirement
+  requirement: &2154744400 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -54,7 +54,7 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *2161970380
+  version_requirements: *2154744400
 description: Distrubuted mutex using Redis
 email: kenn.ejima@gmail.com
 executables: []
@@ -92,7 +92,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
       version: '0'
       segments:
       - 0
-      hash: -2314477826109442509
+      hash: 2435582858684301188
 required_rubygems_version: !ruby/object:Gem::Requirement
   none: false
   requirements: