redis_exp_lock 0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 80f06ec8bcc081e69fac7bc26af297a9e62180af
+  data.tar.gz: 8875e101298264a8983a72d1b9d076e79c48b486
+SHA512:
+  metadata.gz: 514d2ef4aaa60255e3d3c664625c2ec06ecb669c160f7fcefefb84f6ef82443f1f60622a1fe98b7af5b509d4f54877c7337280e28242fd07b79cd193ca898531
+  data.tar.gz: eb34fbb2d1608563f2f9ad04983cff5c33cd7ada98f58ecd0a58e8af326b56a42a28481bb11f9c167ae35dac04741a1794e4b73a159a86504b82a615034e84f1

data/LICENSE

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2015 Jeff Lee <jeffomatic@gmail.com>
+
+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,121 @@
+# redis_exp_lock
+
+A Ruby library providing distributed mutual exclusion using Redis. If you want to prevent multiple network nodes on from accessing a shared resource at the same time, and don't want to roll out a Zookeeper cluster (nobody's judging), this is for you. By default, locks provided by this library use an  expiration time, to prevent irrecoverable locks in case the client fails.
+
+## Requirements
+
+Redis 2.6.12 or higher, because:
+
+- This library uses Redis's Lua functionality in order to eliminate certain race conditions on lock release. Lock expiration is handled by the Redis server itself, eliminating the need for precise time synchronization between your application hosts.
+- This library uses the `SET` command with the `PX` and `NX` optional parameters. It's possible to emulate this functionality using Lua, but the current library omits this for brevity.
+
+## Usage example
+
+```ruby
+require 'redis'
+requie 'redis_exp_lock'
+
+redis = Redis.new
+
+# Create a new lock client
+lock = RedisExpLock.new('lock_key', :redis => redis)
+
+# Use the client to provide mutual exclusion.
+lock.synchronize do
+  # Put critical section code here.
+end
+```
+
+## Installation
+
+Add to your Gemfile:
+
+```ruby
+gem 'redis_exp_lock'
+```
+
+## API
+
+### ::initialize(lock_key, opts)
+
+Creates a new lock client. The constructor takes two parameters, a lock key and and a hash of configuration options.
+
+The **lock key** key identifies a resource to be locked. Clients with the same lock key can only acquire the lock one at a time.
+
+The **options hash** takes the following options:
+
+##### :redis
+
+(required) An instance of a Redis client that obeys the [redis-rb](https://github.com/redis/redis-rb) interface.
+
+##### :expiry
+
+The lifetime of the lock, in seconds. A lock's lifetime begins counting down as soon as the Redis key corresponding to the lock is successfully set. Set this to `nil` if you want a non-expiring lock, which is not recommended. Defaults to 60 seconds.
+
+##### :retries
+
+In the event that the lock has been acquired by another client, the current client can automatically attempt to re-acquire the lock, up to a configurable number of attempts. Defaults to zero (no automatic retries).
+
+##### :interval
+
+The amount of time in seconds that the client will wait before attempting to re-acquire the lock. Defaults to 0.01 (ten milliseconds).
+
+### #locked?
+
+Without calling into Redis, returns whether the local lock is in a lock state, i.e., `lock` has been called without a corresponding `unlock`.
+
+### #key_locked?
+
+Calls remotely to Redis to determine if the lock key has been locked by *any* client.
+
+### #key_owned?
+
+Calls remotely to Redis to determine if the client currently owns the lock.
+
+### #try_lock
+
+Attempts to obtain the lock and returns immediately. Returns `true` if the lock was successfully acquired, otherwise returns `false`.
+
+- Raises `RedisExpLock::AlreadyAcquiredLockError` if client's lock state has not yet been cleared, i.e., if `#lock` was previously called without a corresponding `#unlock`.
+
+### #lock
+
+Attempts to grab the lock, and waits if it isn’t available. Returns the number of attempts required to acquire the lock.
+
+- Raises `RedisExpLock::AlreadyAcquiredLockError` if client's lock state has not yet been cleared, i.e., if `#lock` was previously called without a corresponding `#unlock`.
+- Raises `RedisExpLock::TooManyLockAttemptsError` if the max number of retries is exceed when attempting to acquire the lock.
+
+### #unlock
+
+Releases the lock. Returns `true` if the lock was successfully released. Returns `false` if the client never acquired the lock, or the lock expired before the unlock.
+
+### #synchronize(&block)
+
+Obtains a lock, runs the supplied block, and releases the lock when the block completes. Yields the number of attempts required to acquire the lock.
+
+- Raises `RedisExpLock::AlreadyAcquiredLockError` if client's lock state has not yet been cleared, i.e., if `#lock` was previously called without a corresponding `#unlock`.
+- Raises `RedisExpLock::TooManyLockAttemptsError` if the max number of retries is exceed when attempting to acquire the lock.
+
+## Algorithm
+
+### Lock acquisition
+
+Locks are acquired by setting a Redis key with a UUID generated immediately prior to the lock attempt.
+
+Since the Redis server manages the lifetime, there is no need for any client-side logic that deals with lock expiration, and thus no need to ensure that clients are time-synchronized.
+
+### Lock release
+
+Locks are released by deleting the Redis key, **only if** the key's value matches the UUID generated during a successful lock attempt. A Lua script provides the following atomic sequence:
+
+1. `GET` the value of the key.
+2. If the value of the key is the same as the UUID, then use `DEL` to remove the key.
+
+Without using a Lua script to ensure atomicity, it's possible to encounter subtle race conditions, in which another client acquires the lock between the two steps above.
+
+### Caveats
+
+Lock clients in this library rely on prompt responses from the Redis server. Under aberrant network conditions, there are some edge cases that may cause your application to get out of whack. For example:
+
+1. Lock acquisition requests may be received by the Redis server, but the response could fail to reach the client (e.g., in a socket timeout on the client side). In other words, it's possible that the Redis server thinks the lock has been acquired, but the local client doesn't. If this is a serious concern, be sure to set an expiry value so that the lock can automatically be released by the Redis server.
+2. For expiring locks: it may take a while for the Redis server to respond to a lock acquisition request. This may result in situations where your critical section may not have the full lifetime of the lock to complete. In extreme cases, it's possible for the lock to have already expired on the server by the time the client recognizes its acquisition. If this is a serious concern, consider wrapping the lock acquisition with a timer to make sure you actually have enough time to proceed with your critical section.

data/lib/redis_exp_lock/version.rb

@@ -0,0 +1,3 @@
+class RedisExpLock
+	VERSION = '0.1'
+end

data/lib/redis_exp_lock.rb

@@ -0,0 +1,97 @@
+require 'shavaluator'
+
+class RedisExpLock
+
+	# Errors
+	class TooManyLockAttemptsError < RuntimeError; end
+	class AlreadyAcquiredLockError < RuntimeError; end
+
+	LUA = {
+  	# Deletes keys if they equal the given values
+		:delequal => """
+	    local deleted = 0
+	    if redis.call('GET', KEYS[1]) == ARGV[1] then
+	      return redis.call('DEL', KEYS[1])
+	    end
+	    return 0
+		""",
+	}
+
+	attr_reader :redis, :lock_key, :lock_uuid, :expiry, :retries, :retry_interval
+
+	def initialize(lock_key, opts)
+		defaults = {
+			:expiry => nil, # in seconds
+			:retries => 0,
+			:retry_interval => 0.01, # in seconds
+		}
+		opts = {}.merge(defaults).merge(opts)
+
+		@lock_key = lock_key.to_s
+		raise ArgumentError.new('Invalid lock key') unless @lock_key.size > 0
+		@lock_uuid = nil
+
+		@redis = opts[:redis]
+		@shavaluator = Shavaluator.new(:redis => @redis)
+		@shavaluator.add(LUA)
+
+		@expiry = opts[:expiry]
+		@retries = opts[:retries]
+		@retry_interval = opts[:retry_interval]
+	end
+
+	def locked?
+		!@lock_uuid.nil?
+	end
+
+	def key_locked?
+		@redis.exists(@lock_key)
+	end
+
+	def key_owned?
+		!@lock_uuid.nil? && @lock_uuid == @redis.get(@lock_key)
+	end
+
+	# Attempt to acquire the lock, returning true if the lock was succesfully
+	# acquired, and false if not.
+	def try_lock
+		raise AlreadyAcquiredLockError if locked?
+
+		uuid = SecureRandom.uuid
+		set_opts = {
+			:nx => true
+		}
+    set_opts[:px] = Integer(@expiry * 1000) if @expiry
+
+    if @redis.set(@lock_key, uuid, set_opts)
+    	@lock_uuid = uuid
+    	true
+    else
+    	false
+    end
+	end
+
+	def lock
+		attempts = 0
+		while attempts <= @retries
+			attempts += 1
+			return attempts if try_lock
+			sleep @retry_interval
+		end
+		raise TooManyLockAttemptsError
+	end
+
+	def unlock
+		return false unless locked?
+		was_locked = @shavaluator.exec(:delequal, :keys => [@lock_key], :argv => [@lock_uuid]) == 1
+		@lock_uuid = nil
+		was_locked
+	end
+
+	def synchronize(&crit_sec)
+		attempts = lock
+		crit_sec.call attempts
+		unlock
+	end
+
+end

data/redis_exp_lock.gemspec

@@ -0,0 +1,22 @@
+# encoding: utf-8
+$:.unshift File.expand_path("../lib", __FILE__)
+require 'redis_exp_lock/version'
+
+Gem::Specification.new do |s|
+  s.name = 'redis_exp_lock'
+  s.licenses = ['MIT']
+  s.summary = "Distributed mutual exclusion using Redis"
+  s.version = RedisExpLock::VERSION
+  s.homepage = 'https://github.com/jeffomatic/redis_exp_lock_rb'
+
+  s.authors = ["Jeff Lee"]
+  s.email = 'jeffomatic@gmail.com'
+
+  s.files = %w( README.md LICENSE redis_exp_lock.gemspec )
+  s.files += Dir.glob('lib/**/*')
+
+  s.add_runtime_dependency('shavaluator', '~>0.1')
+
+  s.add_development_dependency('rspec', '~>3.1.0')
+  s.add_development_dependency('redis', '~>3.2.0')
+end

metadata

@@ -0,0 +1,90 @@
+--- !ruby/object:Gem::Specification
+name: redis_exp_lock
+version: !ruby/object:Gem::Version
+  version: '0.1'
+platform: ruby
+authors:
+- Jeff Lee
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2015-02-06 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: shavaluator
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.1'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 3.1.0
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 3.1.0
+- !ruby/object:Gem::Dependency
+  name: redis
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 3.2.0
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 3.2.0
+description: 
+email: jeffomatic@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- lib/redis_exp_lock.rb
+- lib/redis_exp_lock/version.rb
+- redis_exp_lock.gemspec
+homepage: https://github.com/jeffomatic/redis_exp_lock_rb
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.4.2
+signing_key: 
+specification_version: 4
+summary: Distributed mutual exclusion using Redis
+test_files: []