bfg-redis-lock 0.0.1

data/.gitignore

@@ -0,0 +1,18 @@
+*.gem
+*.rbc
+.bundle
+.config
+.yardoc
+Gemfile.lock
+InstalledFiles
+_yardoc
+coverage
+doc/
+lib/bundler/man
+pkg
+rdoc
+spec/reports
+test/tmp
+test/version_tmp
+tmp
+vendor/bundle

data/.rspec

@@ -0,0 +1,2 @@
+--color
+--format progress

data/Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in redis-lock.gemspec
+gemspec

data/LICENSE.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2012 BiddingForGood
+
+MIT License
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,80 @@
+# Redis::Lock
+
+Yet another gem for pessimistic locking using Redis. 
+
+The gem uses unique identifiers for the lock values instead of timestamps as described in [the Redis SETNX documentation](http://redis.io/commands/setnx).
+This avoids any issues with the clocks on the client and server not being exactly in sync. While this shouldn't occur, it does and the implementation described here could fail if the client is more than 1 second out of sync with the server.
+
+The gem uses a combination of [SETNX](http://redis.io/commands/setnx) and [EXPIRES](http://redis.io/commands/expires) instead of [GETSET](http://redis.io/commands/getset) as described in the lock implementation on the redis site. If a client crashes between issuing the 
+SETNX and the EXPIRES commands, the next client that attempts to get a lock will set the EXPIRES on the lock and wait as normal 
+( just in case there is a legitimate lock in use and something else happened ).
+
+When attempting to remove the lock, the client verifies that they are still the lock owner before removing it. The gem watches the lock key while
+attempting to remove the lock to catch the case where the lock expires and is acquired by another client between checking ownership and deleting the lock.
+If the lock is changed while attempting to remove the lock, the removal process will be tried again.
+
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+    gem 'bfg-redis-lock'
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install bfg-redis-lock
+
+## Usage
+
+    require 'redis'
+    require 'redis-lock'
+
+Once required, you can do things like:
+
+    redis = Redis.new
+    redis.lock "my_key" do |lock|
+      # do something while locked
+    end
+    
+The block form above ensures that the lock is released after the block has been executed. Alternatively, you can choose to not provide a block and
+work directly with the lock:
+
+    redis = Redis.new
+    lock = redis.lock "my_key"
+
+    # do some stuff
+    
+    lock.unlock
+
+If you would like, you can specify a timeout for acquiring the lock as well as the lock duration in seconds. The defaults are 5 seconds for acquiring a lock and 10 seconds for the lock duration:
+
+    redis = Redis.new
+    redis.lock "my_key", :acquire_timeout => 2, :lock_duration => 5 do |lock|
+      # do something
+    end
+
+If the lock can't be acquired before the timeout, a LockError will be raised:
+
+    redis = Redis.new
+    lock = redis.lock "my_key", :lock_duration => 30
+    redis.lock "my_key", :acquire_timeout => 1 # raises a LockError after one second of attempting to acquire the lock
+
+You can extend a lock if you are the owner:
+
+    redis = Redis.new
+    lock = redis.lock "my_key"
+    lock.extend_lock 30 # extend lock_duration to be 30 seconds from now
+
+If you are no longer the lock owner, a LockError will be raised.
+
+## Contributing
+
+1. Fork it
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Add some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create new Pull Request

data/Rakefile

@@ -0,0 +1,8 @@
+require "bundler/gem_tasks"
+
+require 'rspec/core/rake_task'
+RSpec::Core::RakeTask.new do |t|
+  # Put spec opts in a file named .rspec in root
+end
+
+task :default => :spec

data/lib/redis-lock.rb

@@ -0,0 +1,192 @@
+require "redis"
+require "redis-lock/version"
+require "securerandom"
+
+class Redis
+  
+  class Lock
+    
+    class LockError < StandardError
+    end
+    
+    attr_reader :redis
+    attr_reader :id
+    attr_reader :lockname
+    attr_reader :acquire_timeout
+    attr_reader :lock_duration
+    attr_reader :logger
+    attr_accessor :before_delete_callback
+    attr_accessor :before_extend_callback
+    
+    def initialize(redis, lock_name, options = {})
+      @redis = redis
+      @lockname = "lock:#{lock_name}"
+      @acquire_timeout = options[:acquire_timeout] || 5
+      @lock_duration = options[:lock_duration] || 10
+      @logger = options[:logger]
+      
+      # generate a unique UUID for this lock
+      @id = SecureRandom.uuid
+    end
+    
+    def lock(&block)
+      acquire_lock or raise LockError.new(lockname)
+      
+      if block
+        begin
+          block.call(self)
+        ensure
+          release_lock
+        end
+      end
+      
+      self
+    end
+    
+    def unlock
+      release_lock
+      self
+    end
+    
+    def acquire_lock
+      try_until = Time.now + acquire_timeout
+      
+      # loop until now + timeout trying to get the lock
+      while Time.now < try_until
+        log :debug, "attempting to acquire lock #{lockname}"
+
+        # try and obtain the lock
+        if redis.setnx(lockname, id)
+          log :info, "lock #{lockname} acquired for #{id}"
+          # lock was obtained, so add an expiration
+          add_expiration
+          return true
+        elsif missing_expiration?
+          # if no expiration, client that obtained lock likely crashed - add an expiration
+          # and wait
+          log :debug, "expiration missing on lock #{lockname}"
+          add_expiration
+        end
+        
+        # didn't get the lock, sleep briefly and try again
+        sleep(0.001)
+      end
+      
+      # was never able to get the lock - give up
+      return false
+    end
+    
+    def extend_lock(extend_by = 10)
+      begin
+        with_watch do
+          if lock_owner?
+            log :debug, "we are the lock owner - extending lock by #{extend_by} seconds"
+            
+            # check if we want to do a callback
+            if before_extend_callback
+              log :debug, "calling callback"
+              before_extend_callback.call(redis)
+            end
+            
+            redis.multi do |multi|
+              multi.expire lockname, extend_by
+            end
+            
+            # we extended the lock, return the lock
+            return self
+          end
+
+          log :debug, "we aren't the lock owner - raising LockError"
+
+          # we aren't the lock owner anymore - raise LockError
+          raise LockError.new("unable to extend #{lockname} - no longer the lock owner")
+        end
+      rescue LockError => e
+        raise e
+      rescue StandardError => e
+        log :warn, "#{lockname} changed while attempting to release key - retrying"
+        # try extending the lock again, just in case
+        extend_lock extend_by
+      end
+    end
+    
+    def release_lock
+      # we are going to watch the lock key while attempting to remove it, so we can
+      # retry removing the lock if the lock is changed while we are removing it.
+      release_with_watch do
+
+        log :debug, "releasing #{lockname}..."
+
+        # make sure we still own the lock
+        if lock_owner?
+          log :debug, "we are the lock owner"
+          
+          # check if we want to do a callback
+          if before_delete_callback
+            log :debug, "calling callback"
+            before_delete_callback.call(redis)
+          end
+
+          redis.multi do |multi|
+            multi.del lockname
+          end
+          return true
+        end
+        
+        # we weren't the owner of the lock anymore - just return
+        return false
+
+      end
+    end
+    
+    def locked?
+      lock_owner?
+    end
+    
+    def missing_expiration?
+      redis.ttl(lockname) == -1
+    end
+    
+    def add_expiration()
+      log :debug, "adding expiration of #{lock_duration} seconds to #{lockname}"
+      redis.expire(lockname, lock_duration)
+    end
+    
+    def lock_owner?
+      log :debug, "our id: #{id} - lock owner: #{redis.get(lockname)}"
+      redis.get(lockname) == id
+    end
+    
+    def release_with_watch(&block)
+      with_watch do
+        begin
+          block.call
+        rescue => e
+          log :warn, "#{lockname} changed while attempting to release key - retrying"
+          release_with_watch &block
+        end
+      end
+    end
+    
+    def with_watch(&block)
+      redis.watch lockname
+      begin
+        block.call
+      ensure
+        redis.unwatch
+      end
+    end
+    
+    def log(level, message)
+      if logger
+        logger.send(level) { message }
+      end
+    end
+    
+  end # Lock class
+
+  def lock(key, options = {}, &block)
+    Lock.new(self, key, options).lock(&block)
+  end
+
+end

data/lib/redis-lock/version.rb

@@ -0,0 +1,5 @@
+class Redis
+  class Lock
+    VERSION = "0.0.1"
+  end
+end

data/redis-lock.gemspec

@@ -0,0 +1,26 @@
+# -*- encoding: utf-8 -*-
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'redis-lock/version'
+
+Gem::Specification.new do |gem|
+  gem.name          = "bfg-redis-lock"
+  gem.version       = Redis::Lock::VERSION
+  gem.authors       = ["Stuart Garner"]
+  gem.email         = ["stuart@biddingforgood.com"]
+  gem.summary       = %q{A pessimistic redis lock implementation.'}
+  gem.description   = <<-DESC
+    A pessimistic redis lock implementation that doesn't use timestamps, works with the latest redis client, and properly handles removing locks.
+  DESC
+  gem.homepage      = "https://github.com/BiddingForGood/redis-lock"
+
+  gem.files         = `git ls-files`.split($/)
+  gem.executables   = gem.files.grep(%r{^bin/}).map{ |f| File.basename(f) }
+  gem.test_files    = gem.files.grep(%r{^(test|spec|features)/})
+  gem.require_paths = ["lib"]
+  
+  gem.add_dependency "redis", "~> 3.0.0"
+
+  gem.add_development_dependency "rake", "~> 0.9.2"
+  gem.add_development_dependency "rspec", "~> 2.12.0"
+end

data/spec/redis-lock_spec.rb

@@ -0,0 +1,180 @@
+require 'spec_helper'
+require 'logger'
+require 'benchmark'
+
+describe Redis::Lock do
+  
+  let(:redis) { Redis.new }
+  
+  before(:each) do
+    redis.del "lock:test"
+  end
+
+  it "responds to lock" do
+    redis.should respond_to(:lock)
+  end
+  
+  it "can acquire and release a lock" do
+    lock = redis.lock "test"
+  
+    redis.get("lock:test").should eq(lock.id)
+    lock.should be_locked
+    
+    lock.unlock
+  
+    redis.get("lock:test").should be_nil
+    lock.should_not be_locked
+  end
+  
+  it "processes a provided block and ensures that the lock is release when completed" do
+    lock = redis.lock "test" do |lock|
+      redis.set "test", "hello"
+      lock.should be_locked
+    end
+  
+    redis.get("test").should eq("hello")
+    lock.should_not be_locked
+  end
+  
+  it "prevents other clients from obtaining a lock" do
+    lock = redis.lock "test", :lock_duration => 10
+    expect { redis.lock "test", :acquire_timeout => 1 }.to raise_exception
+    lock.unlock
+  end
+  
+  it "expires the locks appropriately" do
+    lock = redis.lock "test", :lock_duration => 1
+    sleep(2)
+    lock.should_not be_locked
+  end
+  
+  it "handles clients crashing between obtaining a lock and setting the expires" do
+    redis.set "lock:test", "xxx"
+    
+    lock = redis.lock("test", :acquire_timeout => 5, :lock_duration => 1)
+    lock.should be_locked
+    
+    redis.get("lock:test").should_not eq("xxx")
+    redis.get("lock:test").should eq(lock.id)
+    redis.ttl("lock:test").should_not eq(-1)
+    lock.unlock
+  end
+  
+  it "doesn't remove the lock if the lock expires before complete and another client aquires the lock" do
+    lock1 = redis.lock "test", :lock_duration => 1
+    lock2 = redis.lock "test", :acquire_timeout => 3
+    lock1.unlock
+    
+    lock1.should_not be_locked
+    redis.get("lock:test").should eq(lock2.id)
+    lock2.should be_locked
+  
+    lock2.unlock
+  end
+  
+  it "retries removing the lock when another client changes it during delete" do
+    callback = Proc.new do |redis|
+      redis.incr "retry_count"
+
+      # mess with the lock using another client
+      unless redis.get("retry_count").to_i > 1
+        Redis.new.expires "lock:test", 60
+      end
+    end
+    
+    redis.set "retry_count", 0
+    lock = redis.lock "test"
+    lock.before_delete_callback = callback
+    lock.unlock
+    
+    redis.get("retry_count").should eq(2.to_s)
+    lock.should_not be_locked
+  end
+  
+  it "doesn't remove the lock when another client changes it" do
+    callback = Proc.new do |redis|
+      redis.incr "retry_count"
+
+      # mess with the lock using another client
+      unless redis.get("retry_count").to_i > 1
+        Redis.new.set "lock:test", "xxx"
+      end
+    end
+    
+    redis.set "retry_count", 0
+    lock = redis.lock "test"
+    lock.before_delete_callback = callback
+    lock.unlock
+    
+    redis.get("retry_count").should eq(1.to_s)
+    lock.should_not be_locked
+    redis.get("lock:test").should eq("xxx")
+    
+    redis.del("lock:test")
+  end
+  
+  it "can extend a lock we own" do
+    lock = redis.lock "test", :lock_duration => 10
+    lock.extend_lock 30
+    
+    redis.ttl("lock:test").should eq(30)
+
+    lock.unlock
+  end
+  
+  it "can't extend a lock we don't own" do
+    lock1 = redis.lock "test", :lock_duration => 1
+    lock2 = redis.lock "test"
+    
+    expect { lock1.extend_lock 30 }.to raise_exception
+    
+    lock1.unlock
+    lock2.unlock
+  end
+  
+  it "will retry the lock extension if the key changes while we are doing the extension" do
+    callback = Proc.new do |redis|
+      redis.incr "retry_count"
+
+      # mess with the lock using another client
+      unless redis.get("retry_count").to_i > 1
+        Redis.new.expires "lock:test", 60
+      end
+    end
+    
+    redis.set "retry_count", 0
+    lock = redis.lock "test", :lock_duration => 10
+    lock.before_extend_callback = callback
+    lock.extend_lock 30
+    
+    redis.get("retry_count").should eq(2.to_s)
+    lock.should be_locked
+
+    lock.unlock
+  end
+  
+  it "can run a lot of times without any conflicts" do
+    redis.set "num_locks", 0
+    threads = []
+    logger = Logger.new(STDOUT)
+    # logger.level = Logger::INFO
+    logger.level = Logger::WARN
+    
+    time = Benchmark.realtime do
+      10.times do 
+        threads << Thread.new do
+          10.times do
+            Redis.new.lock("test", :lock_duration => 1, :logger => logger) do |lock|
+              lock.redis.incr "num_locks"
+            end
+            sleep(0.1)
+          end
+        end
+      end
+      threads.each { |t| t.join }
+    end
+    
+    redis.get("num_locks").should eq(100.to_s)
+  end
+  
+end

data/spec/spec_helper.rb

@@ -0,0 +1,16 @@
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+
+require 'redis-lock'
+
+RSpec.configure do |config|
+  config.treat_symbols_as_metadata_keys_with_true_values = true
+  config.run_all_when_everything_filtered = true
+  config.filter_run :focus
+
+  # Run specs in random order to surface order dependencies. If you find an
+  # order dependency and want to debug it, you can fix the order by providing
+  # the seed, which is printed after each run.
+  #     --seed 1234
+  config.order = 'random'
+end

metadata

@@ -0,0 +1,109 @@
+--- !ruby/object:Gem::Specification
+name: bfg-redis-lock
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+  prerelease: 
+platform: ruby
+authors:
+- Stuart Garner
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2012-12-06 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: redis
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 3.0.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 3.0.0
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 0.9.2
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 0.9.2
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 2.12.0
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 2.12.0
+description: ! '    A pessimistic redis lock implementation that doesn''t use timestamps,
+  works with the latest redis client, and properly handles removing locks.
+
+'
+email:
+- stuart@biddingforgood.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- .gitignore
+- .rspec
+- Gemfile
+- LICENSE.txt
+- README.md
+- Rakefile
+- lib/redis-lock.rb
+- lib/redis-lock/version.rb
+- redis-lock.gemspec
+- spec/redis-lock_spec.rb
+- spec/spec_helper.rb
+homepage: https://github.com/BiddingForGood/redis-lock
+licenses: []
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 1.8.23
+signing_key: 
+specification_version: 3
+summary: A pessimistic redis lock implementation.'
+test_files:
+- spec/redis-lock_spec.rb
+- spec/spec_helper.rb