mlanett-redis-lock 0.2.4 → 0.2.5

data/Gemfile

@@ -4,10 +4,10 @@ source 'https://rubygems.org'
 gemspec
 
 group :development do
+  gem "guard"
   gem "guard-rspec"
   gem "rb-fsevent"      # for guard
   gem "rspec"
-  gem "ruby-debug19", require: false
 end
 
 group :test do

data/README.md

@@ -33,27 +33,30 @@ rather than acquiring the lock with a very long lifetime which will result in lo
 
 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 10 seconds.
-It uses exponential backoff with sleeps so it's fairly safe to use longer timeouts.
+A lock may need more than one attempt to acquire it. Redis::Lock offers an acquisition timeout; this defaults to 10 seconds.
+
+There are two lock methods: Redis#lock, which is more convenient, and Redis::Lock#lock.
+Notice there are two timeouts: the lock's lifetime (:life option) and the acquisition timeout, which is less important.
+The acquisition timeout is set via the :acquire option to Redis#lock or passed directly to Redis::Lock#lock.
 
 ## 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 10 second).
+lock() takes a key and lifetime and optionally an acquisition timeout (defaulting to 10 seconds).
 
 redis.lock("test") { |lock| do_something }
 
-redis.lock("test") do |lock|
+redis.lock("test", life: 2*60, acquire: 2) do |lock|
   array.each do |entry|
     do_something(entry)
     lock.extend_life(60)
   end
 end
 
-## Problems
+## Goals
 
-Why do other gems get this wrong?
+I wrote this when noticing that other lock gems were using non-robust approaches.
 
 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.

data/lib/redis-lock.rb

@@ -21,9 +21,9 @@ class Redis
 
     # @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[:life] should be set, but defaults to 1 minute
     # @param options[:owner] may be set, but defaults to HOSTNAME:PID
-    # @param options[:sleep] optional, number of milliseconds to sleep when lock is held, defaults to 125
+    # @param options[:sleep] is used when trying to acquire the lock; milliseconds; defaults to 125.
     def initialize( redis, key, options = {} )
       check_keys( options, :owner, :life, :sleep )
       @redis  = redis
@@ -35,8 +35,9 @@ class Redis
       @sleep_in_ms = options[:sleep] || 125
     end
 
-    def lock( timeout = 10, &block )
-      do_lock_with_timeout(timeout) or raise LockNotAcquired.new(key)
+    # @param acquisition_timeout defaults to 10 seconds and can be used to determine how long to wait for a lock.
+    def lock( acquisition_timeout = 10, &block )
+      do_lock_with_timeout(acquisition_timeout) or raise LockNotAcquired.new(key)
       if block then
         begin
           result = (block.arity == 1) ? block.call(self) : block.call
@@ -74,9 +75,9 @@ class Redis
     # internal api
     #
 
-    def do_lock_with_timeout( timeout )
+    def do_lock_with_timeout( acquisition_timeout )
       locked = false
-      with_timeout(timeout) { locked = do_lock }
+      with_timeout(acquisition_timeout) { locked = do_lock }
       locked
     end
 
@@ -166,9 +167,10 @@ class Redis
       return false
     end
 
-    # Calls block until it returns true or times out. TODO: Use exponential backoff.
+    # Calls block until it returns true or times out.
     # @param block should return true if successful, false otherwise
     # @returns true if successful, false otherwise
+    # Note: at one time I thought of using a backoff strategy, but don't think that's important now.
     def with_timeout( timeout, &block )
       expire = Time.now + timeout.to_f
       sleepy = @sleep_in_ms / 1000.to_f()
@@ -178,7 +180,6 @@ class Redis
         log :debug, "Timeout for #{@key}" and return false if Time.now + sleepy > expire
         sleep(sleepy)
         # might like a different strategy, but general goal is not use 100% cpu while contending for a lock.
-        # sleepy = [ sleepy * 2, ( expire - Time.now ) / 4 ].min
       end
     end
 
@@ -219,7 +220,12 @@ class Redis
 
   # Convenience methods
 
-  # @option timeout defaults to 10 seconds
+  # @param key is a unique string identifying the object to lock, e.g. "user-1"
+  # @options are as specified for Redis::Lock#lock (including :life)
+  # @param options[:life] should be set, but defaults to 1 minute
+  # @param options[:owner] may be set, but defaults to HOSTNAME:PID
+  # @param options[:sleep] is used when trying to acquire the lock; milliseconds; defaults to 125.
+  # @param options[:acquire] defaults to 10 seconds and can be used to determine how long to wait for a lock.
   def lock( key, options = {}, &block )
     acquire = options.delete(:acquire) || 10
     Lock.new( self, key, options ).lock( acquire, &block )

data/lib/redis-lock/version.rb

@@ -1,5 +1,5 @@
 class Redis
   class Lock
-    VERSION = "0.2.4"
+    VERSION = "0.2.5"
   end
 end

data/spec/redis_lock_spec.rb

@@ -136,4 +136,10 @@ describe Redis::Lock, redis: true do
     # We leave [ present, present ] to be unspecified.
   end
 
+  example "How to get a lock using the helper." do
+    redis.lock "mykey", life: 10, acquire: 1 do |lock|
+      lock.extend_life 10
+    end
+  end
+
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: mlanett-redis-lock
 version: !ruby/object:Gem::Version
-  version: 0.2.4
+  version: 0.2.5
   prerelease: 
 platform: ruby
 authors:
@@ -13,7 +13,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2013-07-01 00:00:00.000000000 Z
+date: 2013-08-25 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: redis
@@ -70,12 +70,18 @@ required_ruby_version: !ruby/object:Gem::Requirement
   - - ! '>='
     - !ruby/object:Gem::Version
       version: '0'
+      segments:
+      - 0
+      hash: -132533030489951021
 required_rubygems_version: !ruby/object:Gem::Requirement
   none: false
   requirements:
   - - ! '>='
     - !ruby/object:Gem::Version
       version: '0'
+      segments:
+      - 0
+      hash: -132533030489951021
 requirements: []
 rubyforge_project: 
 rubygems_version: 1.8.23