mlanett-redis-lock 0.2.4 → 0.2.7

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 148ebe29b3ebd72bd6cc37ab0e34b471326c8076
+  data.tar.gz: 2e6110d8ba371f5ad6d7ee40ae5e35ad1b555c78
+SHA512:
+  metadata.gz: 52b8e7beac0570d9bd348cf0ec8f90a5f1dc3ff5fa8ebde0e5e44a7d04f4dde99614e1e799d695bc5184a314a3bf39c096b3cd6c09bf7c56b9f784e30b712a79
+  data.tar.gz: 9fa50ba005240a11dee08225481842012c52a1d2b25f0bcfbd0f872509f46d55a72b4e36646e62214163891ec86caa16a309cd3d150b3fd600ff44292022c4f8

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).
+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 an acquisition timeout (defaulting to 10 seconds).
 
-redis.lock("test") { |lock| do_something }
+    redis.lock("test") { |lock| do_something }
 
-redis.lock("test") do |lock|
-  array.each do |entry|
-    do_something(entry)
-    lock.extend_life(60)
-  end
-end
+    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.
@@ -64,7 +67,7 @@ The code which cleans the stale lock must not interfere with a different owner a
 
 ## Contributors
 
-Alexander Lang (langalex), Jonathan Hyman (jonhyman), Jamie Cobbett (jamiecobbett), and Ravil Bayramgalin (brainopia) have contributed to Redis Lock.
+Alexander Lang (langalex), Jonathan Hyman (jonhyman), Jamie Cobbett (jamiecobbett), Ravil Bayramgalin (brainopia), and Tom Mornini (tmornini) have contributed to Redis Lock.
 
 ## Contributing
 

data/lib/redis-lock/version.rb

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

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,14 +220,22 @@ 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 )
+
+    lock = Redis::Lock.new self, key, options
+
+    block_given? ? lock.lock(acquire, &block) : lock
   end
 
   def unlock( key )
-    Lock( self, key ).unlock
+    Redis::Lock.new( self, key ).unlock
   end
 
 end # Redis

data/redis-lock.gemspec

@@ -2,7 +2,7 @@
 require File.expand_path('../lib/redis-lock/version', __FILE__)
 
 Gem::Specification.new do |gem|
-  gem.authors       = ["Mark Lanett", "Ravil Bayramgalin", "Jamie Cobbett", "Jonathan Hyman", "Alexander Lang"]
+  gem.authors       = ["Mark Lanett", "Ravil Bayramgalin", "Jamie Cobbett", "Jonathan Hyman", "Alexander Lang", "Tom Mornini"]
   gem.email         = ["mark.lanett@gmail.com"]
   gem.description   = %q{Pessimistic locking using Redis}
   gem.summary       = %q{Pessimistic locking using Redis}

data/spec/redis_lock_spec.rb

@@ -136,4 +136,17 @@ describe Redis::Lock, redis: true do
     # We leave [ present, present ] to be unspecified.
   end
 
+  example "How to get a lock using the helper when passing a block" do
+    redis.lock "mykey", life: 10, acquire: 1 do |lock|
+      lock.extend_life 10
+      :return_value_of_block
+    end.should eql(:return_value_of_block)
+  end
+
+  example "How to get a lock using the helper when not passing a block" do
+    lock = redis.lock "mykey", life: 10, acquire: 1
+    lock.should be_an_instance_of(Redis::Lock)
+    lock.unlock
+  end
+
 end

metadata

@@ -1,8 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: mlanett-redis-lock
 version: !ruby/object:Gem::Version
-  version: 0.2.4
-  prerelease: 
+  version: 0.2.7
 platform: ruby
 authors:
 - Mark Lanett
@@ -10,25 +9,24 @@ authors:
 - Jamie Cobbett
 - Jonathan Hyman
 - Alexander Lang
+- Tom Mornini
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2013-07-01 00:00:00.000000000 Z
+date: 2015-10-22 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: '0'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
-    none: false
     requirements:
-    - - ! '>='
+    - - ">="
       - !ruby/object:Gem::Version
         version: '0'
 description: Pessimistic locking using Redis
@@ -38,9 +36,9 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
-- .gitignore
-- .rspec
-- .travis.yml
+- ".gitignore"
+- ".rspec"
+- ".travis.yml"
 - Gemfile
 - Gemfile-redis2
 - Gemfile-redis2.lock
@@ -60,27 +58,26 @@ files:
 - test/stress.rb
 homepage: ''
 licenses: []
+metadata: {}
 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
+rubygems_version: 2.4.5.1
 signing_key: 
-specification_version: 3
+specification_version: 4
 summary: Pessimistic locking using Redis
 test_files:
 - spec/helper.rb