redis-mutex 0.9.0 → 1.0.0

data/README.rdoc

@@ -1,11 +1,25 @@
 = Redis Mutex
 
-Distrubuted non-blocking mutex in Ruby using Redis.
+Distrubuted mutex in Ruby using Redis. Supports both blocking and non-blocking semantics.
 
-The idea was taken from - http://redis.io/commands/setnx and http://gist.github.com/457269
+The idea was taken from http://redis.io/commands/setnx and http://gist.github.com/457269,
+also block syntax was inspired by https://github.com/nateware/redis-objects.
 
 Requires the redis-classy gem.
 
+== Synopsis
+
+Initialize a Redis::Mutex object with a key, then only one thread / process / server can
+enter the locked block at a time.
+
+ mutex = Redis::Mutex.new(:lock_name)
+ mutex.lock do
+   do_something
+ end
+
+By default, when one is running the locked block, others wait 1 second, polling interval is 100ms.
+If 1 second has passed, the lock method returns false.
+
 == Install
 
  gem install redis-mutex
@@ -16,18 +30,31 @@ In Gemfile:
 
  gem "redis-mutex"
 
-In config/initializers/redis_mutex.rb:
+Create a reference to Redis. (e.g. in config/initializers/redis_mutex.rb for Rails)
 
  Redis::Classy.db = Redis.new(:host => 'localhost')
 
 There are four methods - new, lock, unlock and sweep:
 
- mutex = Redis::Classy::Mutex.new(some_object)
+ mutex = Redis::Mutex.new(key, options)
  mutex.lock
  mutex.unlock
- Redis::Classy::Mutex.sweep
+ Redis::Mutex.sweep
 
-It takes any Ruby objects that respond to :id, where the key is automatically set as "TheClass:id", or pass any string as a key.
+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.
+
+Also the initialize method takes several options.
+
+ :block  => 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  => 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 => Specify in seconds when the lock should forcibly be removed when something went wrong
+            with the one who held the lock. (in seconds, 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.
 
 Here's a sample usage in a Rails app:
 
@@ -35,22 +62,19 @@ Here's a sample usage in a Rails app:
    def enter
      @room = Room.find_by_id(params[:id])
      
-     mutex = Redis::Classy::Mutex.new(@room)   # key => "Room:123"
-     
-     if mutex.lock    # return true when you successfully obtain the lock for the room 123
-       ...
+     mutex = Redis::Mutex.new(@room)   # key => "Room:123"
+     mutex.lock do
        do_something
-       ...
-       mutex.unlock   # exit the critical section ASAP
      end
    end
  end
 
-The caveat is that the lock just returns false when it fails and do not block.
+Note that you need to explicitly call the unlock method unless you don't use the block syntax.
 
-If you take a closer look, you find that the actual key is structured in the following form:
+Also note that, if you take a closer look, you find that the actual key is structured in the following form:
 
- Redis::Classy.keys
- => ["Redis::Classy::Mutex:Room:123"]
+ Redis.new.keys
+ => ["Redis::Mutex:Room:123"]
 
+The automatic prefixing and binding is the feature of Redis::Classy.
 For more internal details, refer to https://github.com/kenn/redis-classy

data/Rakefile

@@ -27,9 +27,12 @@ RSpec::Core::RakeTask.new(:spec) do |spec|
   spec.pattern = FileList['spec/**/*_spec.rb']
 end
 
-RSpec::Core::RakeTask.new(:rcov) do |spec|
-  spec.pattern = 'spec/**/*_spec.rb'
-  spec.rcov = true
+desc "Flush the test database"
+task :flushdb do
+  require 'redis-classy'
+  Redis::Classy.db = Redis.new
+  Redis::Classy.select 1
+  Redis::Classy.flushdb
 end
 
 task :default => :spec

data/VERSION

@@ -1 +1 @@
-0.9.0
+1.0.0

data/lib/redis/mutex.rb

@@ -0,0 +1,83 @@
+class Redis
+  #
+  # Redis::Mutex options
+  #
+  # :block  => 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  => 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 => Specify in seconds when the lock should forcibly be removed when something went wrong
+  #            with the one who held the lock. (in seconds, default: 10)
+  #
+  class Mutex < Redis::Classy
+
+    DEFAULT_EXPIRE = 10
+    attr_accessor :options
+
+    def initialize(object, options={})
+      super(object.is_a?(String) || object.is_a?(Symbol) ? object : "#{object.class.name}:#{object.id}")
+      @options = options
+      @options[:block] ||= 1
+      @options[:sleep] ||= 0.1
+      @options[:expire] ||= DEFAULT_EXPIRE
+    end
+
+    def lock
+      if @options[:block] > 0
+        start_at = Time.now
+        success = false
+        while Time.now - start_at < @options[:block]
+          success = true and break if try_lock
+          sleep @options[:sleep]
+        end
+      else
+        # Non-blocking
+        success = try_lock
+      end
+
+      if block_given? and success
+        yield
+        # 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
+
+      success
+    end
+
+    def try_lock
+      now = Time.now.to_f
+      @expires_at = now + @options[: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)
+      del if get.to_f == @expires_at or force   # Release the lock if it seems to be yours
+    end
+
+    def self.sweep
+      return 0 if (all_keys = keys).empty?
+
+      now = Time.now.to_f
+      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
+      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
+      end
+
+      expired_keys.size
+    end
+  end
+end

data/lib/redis-mutex.rb

@@ -1,5 +1,5 @@
 require 'redis-classy'
 
-class Redis::Classy
-  autoload :Mutex, 'redis/classy/mutex'
+class Redis
+  autoload :Mutex, 'redis/mutex'
 end

data/redis-mutex.gemspec

@@ -0,0 +1,65 @@
+# Generated by jeweler
+# DO NOT EDIT THIS FILE DIRECTLY
+# Instead, edit Jeweler::Tasks in Rakefile, and run 'rake gemspec'
+# -*- encoding: utf-8 -*-
+
+Gem::Specification.new do |s|
+  s.name = %q{redis-mutex}
+  s.version = "1.0.0"
+
+  s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
+  s.authors = ["Kenn Ejima"]
+  s.date = %q{2011-03-01}
+  s.description = %q{Distrubuted non-blocking mutex in Ruby using Redis}
+  s.email = %q{kenn.ejima@gmail.com}
+  s.extra_rdoc_files = [
+    "LICENSE.txt",
+    "README.rdoc"
+  ]
+  s.files = [
+    ".document",
+    ".rspec",
+    "Gemfile",
+    "Gemfile.lock",
+    "LICENSE.txt",
+    "README.rdoc",
+    "Rakefile",
+    "VERSION",
+    "lib/redis-mutex.rb",
+    "lib/redis/mutex.rb",
+    "redis-mutex.gemspec",
+    "spec/redis_mutex_spec.rb",
+    "spec/spec_helper.rb"
+  ]
+  s.homepage = %q{http://github.com/kenn/redis-mutex}
+  s.licenses = ["MIT"]
+  s.require_paths = ["lib"]
+  s.rubygems_version = %q{1.5.3}
+  s.summary = %q{Distrubuted non-blocking mutex in Ruby using Redis}
+  s.test_files = [
+    "spec/redis_mutex_spec.rb",
+    "spec/spec_helper.rb"
+  ]
+
+  if s.respond_to? :specification_version then
+    s.specification_version = 3
+
+    if Gem::Version.new(Gem::VERSION) >= Gem::Version.new('1.2.0') then
+      s.add_runtime_dependency(%q<redis-classy>, ["~> 0.9.0"])
+      s.add_development_dependency(%q<rspec>, ["~> 2.5.0"])
+      s.add_development_dependency(%q<bundler>, ["~> 1.0.0"])
+      s.add_development_dependency(%q<jeweler>, ["~> 1.5.2"])
+    else
+      s.add_dependency(%q<redis-classy>, ["~> 0.9.0"])
+      s.add_dependency(%q<rspec>, ["~> 2.5.0"])
+      s.add_dependency(%q<bundler>, ["~> 1.0.0"])
+      s.add_dependency(%q<jeweler>, ["~> 1.5.2"])
+    end
+  else
+    s.add_dependency(%q<redis-classy>, ["~> 0.9.0"])
+    s.add_dependency(%q<rspec>, ["~> 2.5.0"])
+    s.add_dependency(%q<bundler>, ["~> 1.0.0"])
+    s.add_dependency(%q<jeweler>, ["~> 1.5.2"])
+  end
+end
+

data/spec/redis_mutex_spec.rb

@@ -0,0 +1,53 @@
+require 'spec_helper'
+
+describe Redis::Mutex do
+  after do
+    Redis::Classy.flushdb
+  end
+
+  it "should set the value to the expiration" do
+    start = Time.now
+    expires_in = 10
+    mutex = Redis::Mutex.new(:test_lock, :expire => expires_in)
+    mutex.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
+  end
+
+  it "should get a lock when existing lock is expired" do
+    mutex = Redis::Mutex.new(:test_lock)
+    # locked in the far past
+    Redis::Mutex.set(:test_lock, Time.now - 60)
+
+    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, :block => 0.2)
+
+    # someone beats us to it
+    mutex2 = Redis::Mutex.new(:test_lock, :block => 0.2)
+    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
+    mutex = Redis::Mutex.new(:test_lock, :expire => 0.1, :block => 0)
+    mutex.lock
+    sleep 0.2   # lock expired
+
+    # someone overwrites the expired lock
+    mutex2 = Redis::Mutex.new(:test_lock, :expire => 10, :block => 0)
+    mutex2.lock.should be_true
+
+    mutex.unlock
+    mutex.get.should_not be_nil   # lock should still be there
+  end
+end

data/spec/spec_helper.rb

@@ -7,6 +7,12 @@ require 'redis-mutex'
 # in ./support/ and its subdirectories.
 Dir["#{File.dirname(__FILE__)}/support/**/*.rb"].each {|f| require f}
 
+Redis::Classy.db = Redis.new
+Redis::Classy.select 1
+unless Redis::Classy.keys.empty?
+  puts '[ERROR]: Redis database 1 not empty! run "rake flushdb" beforehand.'
+  exit!
+end
+
 RSpec.configure do |config|
-  
 end

metadata

@@ -2,7 +2,7 @@
 name: redis-mutex
 version: !ruby/object:Gem::Version 
   prerelease: 
-  version: 0.9.0
+  version: 1.0.0
 platform: ruby
 authors: 
 - Kenn Ejima
@@ -10,7 +10,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2011-02-28 00:00:00 -08:00
+date: 2011-03-01 00:00:00 -08:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency 
@@ -76,8 +76,9 @@ files:
 - Rakefile
 - VERSION
 - lib/redis-mutex.rb
-- lib/redis/classy/mutex.rb
-- spec/redis-mutex_spec.rb
+- lib/redis/mutex.rb
+- redis-mutex.gemspec
+- spec/redis_mutex_spec.rb
 - spec/spec_helper.rb
 has_rdoc: true
 homepage: http://github.com/kenn/redis-mutex
@@ -93,7 +94,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements: 
   - - ">="
     - !ruby/object:Gem::Version 
-      hash: 4175039287226783610
+      hash: -1194994369925945289
       segments: 
       - 0
       version: "0"
@@ -111,5 +112,5 @@ signing_key:
 specification_version: 3
 summary: Distrubuted non-blocking mutex in Ruby using Redis
 test_files: 
-- spec/redis-mutex_spec.rb
+- spec/redis_mutex_spec.rb
 - spec/spec_helper.rb

data/lib/redis/classy/mutex.rb

@@ -1,45 +0,0 @@
-class Redis::Classy::Mutex < Redis::Classy
-
-  TIMEOUT = 10
-
-  def initialize(object, timeout=TIMEOUT)
-    @now = Time.now.to_i
-    @expires_at = @now + timeout
-    super(object.is_a?(String) ? object : "#{object.class.name}:#{object.id}")
-  end
-
-  def lock
-    return true   if self.setnx(@expires_at)  # Success, the lock was acquired
-    return false  if self.get.to_i > @now     # Failure, someone took the　lock and it is still effective
-
-    # The lock has expired but wasn't released... BAD!
-    return true   if self.getset(@expires_at).to_i <= @now   # Success, we acquired the previously expired lock!
-    return false  # Dammit, it seems that someone else was even faster than us to acquire this lock.
-  end
-
-  def unlock
-    self.del      if self.get.to_i == @expires_at   # Release the lock if it seems to be yours.
-    true
-  end
-
-  def self.sweep(timeout=TIMEOUT)
-    now = Time.now.to_i
-    keys = self.keys
-
-    return 0 if keys.empty?
-
-    values = self.mget(*keys)
-
-    expired_keys = [].tap do |array|
-      keys.each_with_index do |key, i|
-        array << key if !values[i].nil? and values[i].to_i <= now
-      end
-    end
-
-    expired_keys.each do |key|
-      self.del(key) if self.getset(key, now + timeout).to_i <= now # Make extra sure someone haven't released the lock yet.
-    end
-
-    expired_keys.size
-  end
-end

data/spec/redis-mutex_spec.rb

@@ -1,7 +0,0 @@
-require File.expand_path(File.dirname(__FILE__) + '/spec_helper')
-
-describe "RedisMutex" do
-  pending "fails" do
-    fail "hey buddy, you should probably rename this file and start specing for real"
-  end
-end