mlanett-redis-lock 0.0.1

data/.gitignore

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

data/.rspec

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

data/Gemfile

@@ -0,0 +1,15 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in redis-lock.gemspec
+gemspec
+
+group :development do
+  gem "guard-rspec"
+  gem "rb-fsevent"      # for guard
+  gem "rspec"
+  gem "ruby-debug19", require: false
+end
+
+group :test do
+  gem "simplecov", require: false
+end

data/Guardfile

@@ -0,0 +1,6 @@
+guard "rspec" do
+  watch(%r{^lib/redis-lock\.rb$}) { "spec" }
+  watch(%r{^spec/.+_spec\.rb$})
+  watch("spec/helper.rb")         { "spec" }
+  watch(%r{^spec/support/.+\.rb}) { "spec" }
+end

data/LICENSE

@@ -0,0 +1,22 @@
+Copyright (c) 2012 Mark Lanett
+
+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,61 @@
+# Redis::Lock
+
+This gem implements a pessimistic lock using Redis.
+It correctly handles timeouts and vanishing lock owners (such as machine failures)
+
+This uses setnx, but not the setnx algorithm described in the redis cookbook, which is not robust.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+    gem 'redis-lock'
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install redis-lock
+
+## Background
+
+A lock needs an expected lifetime.
+If the owner of a lock disappears (due to machine failure, network failure, process death),
+you want the lock to expire and another owner to be able to acquire the lock.
+At the same time, the owner of a lock should be able to extend its lifetime.
+Thus, you can acquire a lock with a conservative estimate on lifetime, and extend it as necessary,
+rather than acquiring the lock with a very long lifetime which will result in long waits in the event of failures.
+
+A lock needs an owner. Redis::Lock defaults to using an owner id of HOSTNAME:PID.
+
+A lock may need more than one attempt to acquire it. Redis::Lock offers a timeout; this defaults to 1 second.
+It uses exponential backoff with sleeps so it's fairly safe to use longer timeouts.
+
+## Usage
+
+This gem adds lock() and unlock() to Redis instances.
+lock() takes a block and is safer than using lock() and unlock() separately.
+lock() takes a key and lifetime and optionally a timeout (otherwise defaulting to 1 second).
+
+redis.lock("test") { do_something }
+
+## Problems
+
+Why do other gems get this wrong?
+
+You need to be able to handle race conditions while acquiring the lock.
+You need to be able to handle the owner of the lock failing to release it.
+You need to be able to detect stale locks.
+You need to handle race conditions while cleaning the stale lock and acquiring a new one.
+The code which cleans the stale lock may not be able to assume it gets the new one.
+The code which cleans the stale lock must not interfere with a different owner acquiring the lock.
+
+## Contributing
+
+1. Fork it
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Added some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create new Pull Request

data/Rakefile

@@ -0,0 +1,7 @@
+#!/usr/bin/env rake
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:rspec)
+
+task :default => [:rspec]

data/lib/redis-lock.rb

@@ -0,0 +1,225 @@
+require "redis"
+require "redis-lock/version"
+
+class Redis
+
+  class Lock
+
+    class LockNotAcquired < StandardError
+    end
+
+    attr :redis
+    attr :key
+    attr :okey        # key with redis namespace
+    attr :oval
+    attr :xkey        # expiration key with redis namespace
+    attr :xval
+    attr :life, true  # how long we expect to keep this lock locked
+    attr :logger, true
+
+    # @param redis is a Redis instance
+    # @param key is a unique string identifying the object to lock, e.g. "user-1"
+    # @param options[:life] may be set, but defaults to 1 minute
+    # @param options[:owner] may be set, but defaults to HOSTNAME:PID
+    def initialize( redis, key, options = {} )
+      check_keys( options, :owner, :life )
+      @redis  = redis
+      @key    = key
+      @okey   = "lock:owner:#{key}"
+      @oval   = options[:owner] || "#{`hostname`.strip}:#{Process.pid}"
+      @xkey   = "lock:expire:#{key}"
+      @life   = options[:life] || 60
+    end
+
+    def lock( timeout = 1, &block )
+      do_lock_with_timeout(timeout) or raise LockNotAcquired.new(key)
+      if block then
+        begin
+          block.call
+        ensure
+          release_lock
+        end
+      end
+      self
+    end
+
+    def extend_life( new_life )
+      do_extend( new_life ) or raise LockNotAcquired.new(key)
+      self
+    end
+
+    def unlock
+      release_lock
+      self
+    end
+
+    #
+    # queries
+    #
+
+    def locked?( now = Time.now.to_i )
+      # read both in a transaction in a multi to ensure we have a consistent view
+      result = redis.multi do |multi|
+        multi.get( okey )
+        multi.get( xkey )
+      end
+      result && result.size == 2 && is_locked?( result[0], result[1], now )
+    end
+
+    #
+    # internal api
+    #
+
+    def do_lock_with_timeout( timeout )
+      locked = false
+      with_timeout(timeout) { locked = do_lock }
+      locked
+    end
+
+    # @returns true if locked, false otherwise
+    def do_lock( tries = 2 )
+      # We need to set both owner and expire at the same time
+      # If the existing lock is stale, we delete it and try again once
+
+      loop do
+        new_xval = Time.now.to_i + life
+        result   = redis.mapped_msetnx okey => oval, xkey => new_xval
+
+        if result == 1 then
+          log :debug, "do_lock() success"
+          @xval = new_xval
+          return true
+
+        else
+          log :debug, "do_lock() failed"
+          # consider the possibility that this lock is stale
+          tries -= 1
+          next if tries > 0 && stale_key?
+          return false
+        end
+      end
+    end
+
+    def do_extend( new_life, my_owner = oval )
+      # We use watch and a transaction to ensure we only change a lock we own
+      # The transaction fails if the watched variable changed
+      # Use my_owner = oval to make testing easier.
+      new_xval = Time.now.to_i + new_life
+      with_watch( okey  ) do
+        owner = redis.get( okey )
+        if owner == my_owner then
+          result = redis.multi do |multi|
+            multi.set( xkey, new_xval )
+          end
+          if result && result.size == 1 then
+            log :debug, "do_extend() success"
+            @xval = new_xval
+            return true
+          end
+        end
+      end
+      return false
+    end
+
+    # Only actually deletes it if we own it.
+    # There may be strange cases where we fail to delete it, in which case expiration will solve the problem.
+    def release_lock( my_owner = oval )
+      # Use my_owner = oval to make testing easier.
+      with_watch( okey, xkey ) do
+        owner = redis.get( okey )
+        if owner == my_owner then
+          redis.multi do |multi|
+            multi.del( okey )
+            multi.del( xkey )
+          end
+        end
+      end
+    end
+
+    def stale_key?( now = Time.now.to_i )
+      # Check if expiration exists and is it stale?
+      # If so, delete it.
+      # watch() both keys so we can detect if they change while we do this
+      # multi() will fail if keys have changed after watch()
+      # Thus, we snapshot consistency at the time of watch()
+      # Note: inside a watch() we get one and only one multi()
+      with_watch( okey, xkey ) do
+        owner  = redis.get( okey )
+        expire = redis.get( xkey )
+        if is_deleteable?( owner, expire, now ) then
+          result = redis.multi do |r|
+            r.del( okey )
+            r.del( xkey )
+          end
+          # If anything changed then multi() fails and returns nil
+          if result && result.size == 2 then
+            log :info, "Deleted stale key from #{owner}"
+            return true
+          end
+        end
+      end # watch
+      # Not stale
+      return false
+    end
+
+    # Calls block until it returns true or times out. Uses exponential backoff.
+    # @param block should return true if successful, false otherwise
+    # @returns true if successful, false otherwise
+    def with_timeout( timeout, &block )
+      expire = Time.now + timeout.to_f
+      sleepy = 0.125
+      # this looks inelegant compared to while Time.now < expire, but does not oversleep
+      loop do
+        return true if block.call
+        log :debug, "Timeout" and return false if Time.now + sleepy > expire
+        sleep(sleepy)
+        sleepy *= 2
+      end
+    end
+
+    def with_watch( *args, &block )
+      # Note: watch() gets cleared by a multi() but it's safe to call unwatch() anyway.
+      redis.watch( *args )
+      begin
+        block.call
+      ensure
+        redis.unwatch
+      end
+    end
+
+    # @returns true if the lock exists and is owned by the given owner
+    def is_locked?( owner, expiration, now = Time.now.to_i )
+      owner == oval && ! is_deleteable?( owner, expiration, now )
+    end
+
+    # @returns true if this is a broken or expired lock
+    def is_deleteable?( owner, expiration, now = Time.now.to_i )
+      expiration = expiration.to_i
+      ( owner || expiration > 0 ) && ( ! owner || expiration < now )
+    end
+
+    def log( level, *messages )
+      if logger then
+        logger.send(level) { "[#{Time.now.strftime "%Y%m%d%H%M%S"} #{oval}] #{messages.join(' ')}" }
+      end
+      self
+    end
+
+    def check_keys( set, *keys )
+      extra = set.keys - keys
+      raise "Unknown Option #{extra.first}" if extra.size > 0
+    end
+
+  end # Lock
+
+  # Convenience methods
+
+  def lock( key, timeout = 1, options = {}, &block )
+    Lock.new( self, key, options ).lock( timeout, &block )
+  end
+
+  def unlock( key )
+    Lock( self, key ).unlock
+  end
+
+end # Redis

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,19 @@
+# -*- encoding: utf-8 -*-
+require File.expand_path('../lib/redis-lock/version', __FILE__)
+
+Gem::Specification.new do |gem|
+  gem.authors       = ["Mark Lanett"]
+  gem.email         = ["mark.lanett@gmail.com"]
+  gem.description   = %q{Pessimistic locking using Redis}
+  gem.summary       = %q{Pessimistic locking using Redis}
+  gem.homepage      = ""
+
+  gem.executables   = `git ls-files -- bin/*`.split("\n").map{ |f| File.basename(f) }
+  gem.files         = `git ls-files`.split("\n")
+  gem.test_files    = `git ls-files -- {test,spec,features}/*`.split("\n")
+  gem.name          = "mlanett-redis-lock"
+  gem.require_paths = ["lib"]
+  gem.version       = Redis::Lock::VERSION
+
+  gem.add_dependency "redis"
+end

data/spec/helper.rb

@@ -0,0 +1,21 @@
+# -*- encoding: utf-8 -*-
+
+require "bundler/setup"       # set up gem paths
+require "ruby-debug"          # because sometimes you need it
+
+require "simplecov"           # code coverage
+SimpleCov.start               # must be loaded before our own code
+
+require "redis-lock"          # load this gem
+require "support/redis"       # simple helpers for testing
+
+RSpec.configure do |spec|
+  # @see https://www.relishapp.com/rspec/rspec-core/docs/helper-methods/define-helper-methods-in-a-module
+  spec.include RedisClient, redis: true
+
+  # nuke the Redis database around each run
+  # @see https://www.relishapp.com/rspec/rspec-core/docs/hooks/around-hooks
+  spec.around( :each, redis: true ) do |example|
+    with_clean_redis { example.run }
+  end
+end

data/spec/redis_lock_spec.rb

@@ -0,0 +1,111 @@
+require "helper"
+
+describe Redis::Lock, redis: true do
+
+  let(:non) { nil }
+  let(:her) { "Alice" }
+  let(:him) { "Bob" }
+  let(:hers)       { Redis::Lock.new( redis, "alpha", owner: her ) }
+  let(:her_same)   { Redis::Lock.new( redis, "alpha", owner: her ) }
+  let(:his)        { Redis::Lock.new( redis, "alpha", owner: him ) }
+  let(:his_other)  { Redis::Lock.new( redis, "beta",  owner: him ) }
+  let(:past   ) { 1 }
+  let(:present) { 2 }
+  let(:future ) { 3 }
+
+  it "can acquire and release a lock" do
+    hers.lock do
+      hers.should be_locked
+    end
+    hers.should_not be_locked
+  end
+
+  it "can prevent other use of a lock" do
+    hers.lock do
+      expect { his.lock.unlock }.to raise_exception
+    end
+    expect { his.lock.unlock }.to_not raise_exception
+  end
+
+  it "can lock two different items at the same time" do
+    his.lock do
+      expect { his_other.lock.unlock }.to_not raise_exception
+      his.should be_locked
+    end
+  end
+
+  it "does not support nesting" do
+    hers.lock do
+      expect { her_same.lock }.to raise_exception
+    end
+  end
+
+  it "can acquire a lock" do
+    hers.do_lock.should be_true
+  end
+
+  it "can release a lock" do
+    hers.lock.release_lock
+  end
+
+  it "can use a timeout" do
+    hers.with_timeout(1) { true }.should be_true
+    hers.with_timeout(1) { false }.should be_false
+    # a few attempts are OK
+    results = [ false, false, true ]
+    hers.with_timeout(1) { results.shift }.should be_true
+    # this is too many attemps
+    results = [ false, false, false, false, false, true ]
+    hers.with_timeout(1) { results.shift }.should be_false
+  end
+
+  it "does not take too long to time out" do
+    start = Time.now.to_f
+    hers.with_timeout(1) { false }
+    time = Time.now.to_f - start
+    time.should be_within(0.2).of(1.0)
+  end
+
+  it "can time out an expired lock" do
+    hers.life = 1
+    hers.lock
+    # don't unlock it, let hers time out
+    expect { his.lock(10).unlock }.to_not raise_exception
+  end
+
+  it "can extend the life of a lock" do
+    hers.life = 1
+    hers.lock
+    hers.extend_life(100)
+    expect { his.lock(10).unlock }.to raise_exception
+    hers.unlock
+  end
+
+  it "can determine if it is locked" do
+    hers.is_locked?( non, nil,    present ).should be_false
+    hers.is_locked?( non, future, present ).should be_false
+    hers.is_locked?( non, past,   present ).should be_false
+    hers.is_locked?( her, nil,    present ).should be_false
+    hers.is_locked?( her, future, present ).should be_true  # the only valid case
+    hers.is_locked?( her, past,   present ).should be_false
+    hers.is_locked?( him, nil,    present ).should be_false
+    hers.is_locked?( him, future, present ).should be_false
+    hers.is_locked?( him, past,   present ).should be_false
+    # We leave [ present, present ] to be unspecified.
+  end
+
+  it "can detect broken or expired locks" do
+    hers.is_deleteable?( non, nil,    present ).should be_false # no lock => not expired
+
+    hers.is_deleteable?( non, future, present ).should be_true  # broken => expired
+    hers.is_deleteable?( non, past,   present ).should be_true  # broken => expired
+    hers.is_deleteable?( her, nil,    present ).should be_true  # broken => expired
+
+    hers.is_deleteable?( her, future, present ).should be_false # current; not expired
+
+    hers.is_deleteable?( her, past,   present ).should be_true  # expired
+
+    # We leave [ present, present ] to be unspecified.
+  end
+
+end

data/spec/redis_spec.rb

@@ -0,0 +1,46 @@
+require "helper"
+
+# These are here to be sure Redis works the way we expect.
+
+describe Redis, redis: true do
+
+  it "can do a multi setnx" do
+    redis.mapped_msetnx "one" => "uno", "two" => "dos"
+    redis.get("one").should eq("uno")
+    redis.get("two").should eq("dos")
+  end
+
+  it "can delete multiple items" do
+    redis.set "one", "uno"
+    redis.set "two", "dos"
+    x = redis.multi do |multi|
+      multi.del "one"
+      multi.del "two"
+    end
+    x.should eq( [1,1] )
+    redis.get("one").should be_nil
+    redis.get("two").should be_nil
+  end
+
+  it "can detect multi success" do
+    redis.set "one", "uno"
+    with_watch( redis, "one" ) do
+      x = redis.multi do |multi|
+        multi.del "one"
+      end
+      x.should eq([1])
+    end
+  end
+
+  it "can detect multi failures" do
+    redis.set "one", "uno"
+    with_watch( redis,  "one" ) do
+      x = redis.multi do |multi|
+        multi.del "one"
+        other.set "one", "ichi"
+      end
+      x.should be_nil
+    end
+  end
+
+end

data/spec/support/redis.rb

@@ -0,0 +1,37 @@
+# -*- encoding: utf-8 -*-
+
+require "redis"
+
+module RedisClient
+
+  TEST_REDIS = { url: "redis://127.0.0.1:6379/1" }
+
+  def redis
+    @redis ||= ::Redis.connect(TEST_REDIS)
+  end
+
+  def other
+    @other ||= ::Redis.connect(TEST_REDIS)
+  end
+
+  def with_watch( redis, *args )
+    redis.watch( *args )
+    begin
+      yield
+    ensure
+      redis.unwatch
+    end
+  end
+
+  def with_clean_redis(&block)
+    redis.client.disconnect # auto connect after fork
+    other.client.disconnect # auto connect after fork
+    redis.flushall          # clean before run
+    yield
+  ensure
+    redis.flushall          # clean up after run
+    redis.quit              # quit (close) connection
+    other.quit              # quit (close) connection
+  end
+
+end # RedisClient

data/test/stress.rb

@@ -0,0 +1,109 @@
+#!/usr/bin/env ruby
+
+require "bundler/setup"       # set up gem paths
+require "redis-lock"          # load this gem
+require "optparse"
+require "ostruct"
+
+options = OpenStruct.new({
+  forks: 30,
+  tries: 10,
+  sleep: 2,
+  keys:  5
+})
+
+TEST_REDIS = { url: "redis://127.0.0.1:6379/1" }
+
+OptionParser.new do |opts|
+  opts.banner = "Usage: #{__FILE__} --forks F --tries T --sleep S"
+  opts.on( "-f", "--forks FORKS", "How many processes to fork" )                { |i| options.forks = i.to_i }
+  opts.on( "-t", "--tries TRIES", "How many attempts each process should try" ) { |i| options.tries = i.to_i }
+  opts.on( "-s", "--sleep SLEEP", "How long processes should sleep/work" )      { |i| options.sleep = i.to_i }
+  opts.on( "-k", "--keys KEYS", "How many keys a process should run through" )  { |i| options.keys = i.to_i }
+  opts.on( "-h", "--help", "Display this usage summary" ) { puts opts; exit }
+end.parse!
+
+class Thing
+  attr :id
+  attr :activity
+  def initialize( id, activity )
+    @id       = id
+    @activity = activity
+  end
+  def process
+    Kernel.sleep( rand activity )
+  end
+end # Thing
+
+class Runner
+
+  attr :options
+
+  def initialize( options )
+    @options = options
+  end
+
+  def redis
+    @redis ||= ::Redis.connect(TEST_REDIS)
+  end
+
+  def test( key, time )
+    redis.lock( key, time, life: time*2 ) do
+      val1 = rand(65536)
+      redis.set( "#{key}:widget", val1 )
+      Kernel.sleep( time )
+      val2 = redis.get("#{key}:widget").to_i
+      expect( val1, val2 )
+    end
+    true
+  rescue => x
+    # STDERR.puts "Failed due to #{x.inspect}"
+    false
+  end
+
+  def run
+    keys    = Hash[ (0...options.keys).map { |i| [ i, "key:#{i}" ] } ] # i => key:i
+    fails   = Hash[ (0...options.keys).map { |i| [ i, 0 ] } ] # i => 0
+    stats   = OpenStruct.new( ok: 0, fails: 0 )
+    while keys.size > 0 do
+      i = keys.keys.sample
+      if test( keys[i], (options.sleep) ) then
+        keys.delete(i)
+        stats.ok += 1
+      else
+        fails[i] += 1
+        stats.fails += 1
+        if fails[i] >= options.tries then
+          keys.delete(i)
+        end
+      end
+    end
+    puts "[#{Process.pid}] Complete; Ok: #{stats.ok}, Failures: #{stats.fails}"
+  end
+
+  def launch
+    Kernel.fork do
+      GC.copy_on_write_friendly = true if ( GC.copy_on_write_friendly? rescue false )
+      run
+    end
+  end
+
+  def expect( val1, val2 )
+    if val1 != val2 then
+      STDERR.puts "[#{Process.pid}] Value mismatch"
+      Kernel.abort
+    end
+  end
+
+end
+
+# main
+
+redis = ::Redis.connect(TEST_REDIS)
+redis.flushall          # clean before run
+redis.client.disconnect # don't keep when forking
+
+options.forks.times do
+  Runner.new( options ).launch
+end
+Process.waitall

metadata

@@ -0,0 +1,76 @@
+--- !ruby/object:Gem::Specification
+name: mlanett-redis-lock
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+  prerelease: 
+platform: ruby
+authors:
+- Mark Lanett
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2012-02-04 00:00:00.000000000Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: redis
+  requirement: &70233994826820 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: *70233994826820
+description: Pessimistic locking using Redis
+email:
+- mark.lanett@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- .gitignore
+- .rspec
+- Gemfile
+- Guardfile
+- LICENSE
+- README.md
+- Rakefile
+- lib/redis-lock.rb
+- lib/redis-lock/version.rb
+- redis-lock.gemspec
+- spec/helper.rb
+- spec/redis_lock_spec.rb
+- spec/redis_spec.rb
+- spec/support/redis.rb
+- test/stress.rb
+homepage: ''
+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.15
+signing_key: 
+specification_version: 3
+summary: Pessimistic locking using Redis
+test_files:
+- spec/helper.rb
+- spec/redis_lock_spec.rb
+- spec/redis_spec.rb
+- spec/support/redis.rb
+- test/stress.rb