clasp 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+--- 
+SHA1: 
+  metadata.gz: 5885cf34377db5819f7ede1186985edd13fb5159
+  data.tar.gz: 3a64a4c1e0dfeee866cb52615ed6acb44fc48bd7
+SHA512: 
+  metadata.gz: 046ca81ef9150e7cd3e77ada1f8f27d84dae98941b1cec86728381f74c46478c987163bf438ae3e0743b6951d7fc29ccd17d2ba94058e7c3465b3bb88e8698b2
+  data.tar.gz: ecc4612154e5011d650c99a1e6bab07a1e67ef28a08f0ed9d85597c415cf42bd15f20bae0b6f6b3f9f7f6a24beed9d8e0dcc136eb4e0f547386812cf536d0955

data/LICENSE

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2013 Ian Unruh
+
+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,43 @@
+# Clasp
+
+[![Build Status](https://travis-ci.org/ianunruh/clasp.png?branch=master)](https://travis-ci.org/ianunruh/clasp)
+
+Named reentrant locks with deadlock detection for Ruby
+
+## Installation & usage
+
+Install using `gem install clasp` or add it to your `Gemfile`.
+
+### Basic usage
+
+```ruby
+manager = Clasp::LockManager.new
+
+manager.lock 'id1'
+manager.unlock 'id1'
+```
+
+### Deadlock detection
+
+```ruby
+## Thread 1                                ## Thread 2
+manager.lock 'AAA'                         manager.lock 'BBB'
+begin                                      begin
+  manager.lock 'BBB'                         manager.lock 'AAA'
+  # do work...                               # do work...
+  manager.unlock 'BBB'                       manager.unlock 'AAA'
+ensure                                     ensure
+  manager.unlock 'AAA'                       manager.unlock 'BBB'
+end                                        end
+```
+
+Using standard locks, this program could run forever because of a deadlock. Using `LockManager`
+prevents this by tracking all locks and checking if a deadlock is about to occur.
+
+The first thread that detects the deadlock can release any locks it holds. After this happens,
+it can rollback and try again later. The competing thread will then be able to lock any
+resources it needs to continue.
+
+## Todo
+
++ More tests

data/lib/clasp/disposable_lock.rb

@@ -0,0 +1,91 @@
+module Clasp
+  # @api private
+  class DisposableLock
+    extend Forwardable
+
+    def_delegators :@lock, :owned?, :owned_by?, :queue
+
+    # @return [undefined]
+    def initialize
+      @closed = false
+      @lock = ReentrantLock.new
+    end
+
+    # @return [Boolean]
+    def lock
+      unless @lock.try_lock
+        loop do
+          check_for_deadlock
+          break if @lock.try_timed_lock(0.3)
+        end
+      end
+
+      if @closed
+        @lock.unlock
+        false
+      else
+        true
+      end
+    end
+
+    # @return [undefined]
+    def unlock
+      @lock.unlock
+    ensure
+      try_close
+    end
+
+    # @return [Boolean]
+    def closed?
+      @closed
+    end
+
+    private
+
+    # @return [undefined]
+    def try_close
+      if @lock.try_lock
+        @closed = @lock.hold_count == 1
+        @lock.unlock
+      end
+    end
+
+    # @raise [DeadlockError]
+    # @return [undefined]
+    def check_for_deadlock
+      if @lock.locked? && !@lock.owned?
+        deadlock_candidates_for(Thread.current).each do |waiter|
+          if @lock.owned_by?(waiter)
+            raise DeadlockError, 'Imminent deadlock detected while acquiring a lock'
+          end
+        end
+      end
+    end
+
+    # @param [Thread] thread
+    # @return [Set]
+    def deadlock_candidates_for(thread)
+      waiters_for_locks_owned_by(thread, LockManagerTracker.instances, Set.new)
+    end
+
+    # @param [Thread] thread
+    # @param [Enumerable] managers
+    # @param [Set] waiters
+    # @return [Set]
+    def waiters_for_locks_owned_by(thread, managers, waiters)
+      # Find all locks owned by the given thread
+      locks = managers.flat_map(&:locks).find_all { |lock|
+        lock.owned_by?(thread)
+      }
+
+      locks.flat_map(&:queue).each do |waiter|
+        if waiters.add?(waiter)
+          # Recursively find waiters for locks owned by this waiter
+          waiters_for_locks_owned_by(waiter, managers, waiters)
+        end
+      end
+
+      waiters
+    end
+  end
+end

data/lib/clasp/errors.rb

@@ -0,0 +1,10 @@
+module Clasp
+  # Raised when an error occurs while acquiring a lock
+  class LockAcquisitionError < RuntimeError; end
+
+  # Raised when an imminent deadlock is detected while acquiring a lock
+  class DeadlockError < LockAcquisitionError; end
+
+  # Raised when a lock is used incorrectly by the calling thread
+  class IllegalLockUsageError < RuntimeError; end
+end

data/lib/clasp/lock_manager.rb

@@ -0,0 +1,60 @@
+module Clasp
+  class LockManager
+    # @return [undefined]
+    def initialize
+      @locks = ThreadSafe::Cache.new
+      LockManagerTracker.register(self)
+    end
+
+    # Obtains the lock for the given identifier
+    #
+    # @raise [LockAcquisitonError]
+    #   If the lock could not be acquired, usually due to deadlock
+    # @param [Object] identifier
+    # @return [undefined]
+    def lock(identifier)
+      obtained = false
+      until obtained
+        lock = @locks.compute_if_absent(identifier) { DisposableLock.new }
+        obtained = lock.lock
+        unless obtained
+          @locks.delete_pair(identifier, lock)
+        end
+      end
+    end
+
+    # Returns true if the calling thread holds the lock for the given identifier
+    #
+    # @param [Object] identifier
+    # @return [Boolean]
+    def owned?(identifier)
+      lock = @locks.get(identifier)
+      lock && lock.owned?
+    end
+
+    # Releases the lock for the given identifier
+    #
+    # @raise [IllegalLockUsageError]
+    #   If the calling thread did not hold the lock for the given identifier
+    # @param [Object] identifier
+    # @return [undefined]
+    def unlock(identifier)
+      unless @locks.key?(identifier)
+        raise IllegalLockUsageError
+      end
+
+      lock = @locks.get(identifier)
+      lock.unlock
+
+      if lock.closed?
+        @locks.delete_pair(identifier, lock)
+      end
+    end
+
+    # @api private
+    # @return [Enumerable]
+    def locks
+      @locks.values
+    end
+  end # LockManager
+end # Clasp

data/lib/clasp/lock_manager_tracker.rb

@@ -0,0 +1,24 @@
+module Clasp
+  # @api private
+  module LockManagerTracker
+    extend self
+
+    @mutex = Mutex.new
+    @instances = Ref::WeakKeyMap.new
+
+    # @param [LockManager] instance
+    # @return [undefined]
+    def register(instance)
+      @mutex.synchronize do
+        @instances[instance] = true
+      end
+    end
+
+    # @return [Enumerable]
+    def instances
+      @mutex.synchronize do
+        @instances.keys
+      end
+    end
+  end # LockManagerTracker
+end # Clasp

data/lib/clasp/reentrant_lock.rb

@@ -0,0 +1,166 @@
+module Clasp
+  # Simple reentrant lock implementation that uses fair ordering
+  class ReentrantLock
+    # @return [Thread]
+    attr_reader :owner
+
+    # @return [undefined]
+    def initialize
+      @hold_count = 0
+      @mutex = Mutex.new
+      @queue = []
+    end
+
+    # Returns the depth of the lock
+    # @return [Integer]
+    def hold_count
+      if @owner == Thread.current
+        @hold_count
+      else
+        0
+      end
+    end
+
+    # Returns a snapshot of the threads waiting for this lock
+    # @return [Enumerable]
+    def queue
+      @mutex.synchronize do
+        @queue.to_a
+      end
+    end
+
+    # Returns the number of threads waiting for this lock
+    # @return [Integer]
+    def queue_size
+      @mutex.synchronize do
+        @queue.size
+      end
+    end
+
+    # Returns true if this lock is currently held by a thread
+    # @return [Boolean]
+    def locked?
+      !!@owner
+    end
+
+    # Returns true if this lock is currently held by the calling thread
+    # @return [Boolean]
+    def owned?
+      @owner == Thread.current
+    end
+
+    # Returns true if this lock is currently held by the given thread
+    #
+    # @param [Thread] thread
+    # @return [Boolean]
+    def owned_by?(thread)
+      @owner == thread
+    end
+
+    # Acquires this lock for the calling thread
+    #
+    # If this lock has already been acquired by the calling thread, the hold count
+    # or depth of the lock is incremented.
+    #
+    # If this lock has already been acquired by another thread, this thread is placed
+    # in a queue and will be given the lock once all threads before it have gone
+    # through the queue.
+    #
+    # @return [undefined]
+    def lock
+      @mutex.synchronize do
+        unless @owner == Thread.current
+          while @owner
+            @queue.push Thread.current
+
+            begin
+              @mutex.sleep
+            ensure
+              @queue.pop
+            end
+          end
+
+          @owner = Thread.current
+        end
+
+        @hold_count += 1
+      end
+    end
+
+    # Attempts to acquire this lock for the calling thread
+    #
+    # If this lock has already been acquired by the calling thread, the hold count
+    # or depth of the lock is incremented.
+    #
+    # If this lock has already been acquired by another thread, this method will return
+    # immediately without waiting for the lock to become free.
+    #
+    # @return [Boolean]
+    def try_lock
+      @mutex.synchronize do
+        unless @owner == Thread.current
+          return false if @owner
+          @owner = Thread.current
+        end
+
+        @hold_count += 1
+        true
+      end
+    end
+
+    # @param [Float] timeout
+    # @return [Boolean]
+    def try_timed_lock(timeout)
+      @mutex.synchronize do
+        unless @owner == Thread.current
+          start = Time.now
+
+          while @owner
+            return false if (Time.now - start) >= timeout
+
+            @queue.push Thread.current
+            begin
+              @mutex.sleep timeout
+            ensure
+              @queue.pop
+            end
+          end
+
+          @owner = Thread.current
+        end
+
+        @hold_count += 1
+        true
+      end
+    end
+
+    # @raise [IllegalLockUsageError]
+    # @return [undefined]
+    def unlock
+      @mutex.synchronize do
+        unless @owner == Thread.current
+          raise IllegalLockUsageError, 'Calling thread not holding lock'
+        end
+
+        @hold_count -= 1
+        if @hold_count == 0
+          @owner = nil
+          wakeup_next
+        end
+      end
+    end
+
+    private
+
+    # Invocation of this method must be synchronized
+    # @return [undefined]
+    def wakeup_next
+      t = @queue.first
+      t.wakeup if t
+    rescue ThreadError
+      # The thread died while waiting for the lock
+      @queue.pop
+      retry
+    end
+  end # ReentrantLock
+end # Clasp

data/lib/clasp/version.rb

@@ -0,0 +1,3 @@
+module Clasp
+  VERSION = '0.1.0'
+end

data/lib/clasp.rb

@@ -0,0 +1,13 @@
+require 'atomic'
+require 'forwardable'
+require 'ref'
+require 'set'
+require 'thread_safe'
+
+require 'clasp/version'
+
+require 'clasp/disposable_lock'
+require 'clasp/errors'
+require 'clasp/lock_manager'
+require 'clasp/lock_manager_tracker'
+require 'clasp/reentrant_lock'

data/spec/lock_manager_spec.rb

@@ -0,0 +1,111 @@
+require 'spec_helper'
+
+describe Clasp::LockManager do
+  let(:lock_a) { SecureRandom.uuid }
+  let(:lock_b) { SecureRandom.uuid }
+  let(:lock_c) { SecureRandom.uuid }
+  let(:lock_d) { SecureRandom.uuid }
+
+  before do
+    Thread.abort_on_exception = true
+  end
+
+  it 'stores locks by identifiers' do
+    subject.should_not be_owned(lock_a)
+    subject.should_not be_owned(lock_b)
+
+    subject.lock(lock_a)
+    subject.should be_owned(lock_a)
+    subject.should_not be_owned(lock_b)
+
+    subject.unlock(lock_a)
+    subject.should_not be_owned(lock_a)
+    subject.should_not be_owned(lock_b)
+  end
+
+  it 'cleans up locks that are no longer in use' do
+    subject.locks.should be_empty
+
+    subject.lock(lock_a)
+    subject.unlock(lock_a)
+
+    subject.locks.should be_empty
+  end
+
+  it 'keeps locks that are still in use' do
+    subject.lock(lock_a)
+    subject.lock(lock_a)
+
+    subject.unlock(lock_a)
+    subject.locks.should_not be_empty
+
+    subject.unlock(lock_a)
+    subject.locks.should be_empty
+  end
+
+  it 'raises an exception when an unknown lock is released' do
+    expect {
+      subject.unlock(lock_a)
+    }.to raise_error(Clasp::IllegalLockUsageError)
+  end
+
+  it 'detects a deadlock between two threads' do
+    latch = CountdownLatch.new(2)
+    deadlock = CountdownLatch.new(1)
+
+    start_thread(latch, deadlock, lock_a, subject, lock_b, subject)
+    start_thread(latch, deadlock, lock_b, subject, lock_a, subject)
+
+    unless deadlock.await(30)
+      raise 'Could not resolve deadlock within 30 seconds'
+    end
+  end
+
+  it 'detects a deadlock between three threads in a vector' do
+    latch = CountdownLatch.new(3)
+    deadlock = CountdownLatch.new(1)
+
+    start_thread(latch, deadlock, lock_a, subject, lock_b, subject)
+    start_thread(latch, deadlock, lock_b, subject, lock_c, subject)
+    start_thread(latch, deadlock, lock_c, subject, lock_a, subject)
+
+    unless deadlock.await(30)
+      raise 'Could not resolve deadlock within 30 seconds'
+    end
+  end
+
+  it 'detects a deadlock across lock managers' do
+    manager_a = described_class.new
+    manager_b = described_class.new
+
+    latch = CountdownLatch.new(2)
+    deadlock = CountdownLatch.new(1)
+
+    start_thread(latch, deadlock, lock_a, manager_a, lock_a, manager_b)
+    start_thread(latch, deadlock, lock_a, manager_b, lock_a, manager_a)
+
+    unless deadlock.await(30)
+      raise 'Could not resolve deadlock within 30 seconds'
+    end
+  end
+
+  private
+
+  def start_thread(latch, deadlock, lock_a, manager_a, lock_b, manager_b)
+    Thread.new do
+      manager_a.lock(lock_a)
+      latch.countdown
+
+      begin
+        latch.await
+
+        manager_b.lock(lock_b)
+        manager_b.unlock(lock_b)
+      rescue Clasp::DeadlockError
+        deadlock.countdown
+      ensure
+        manager_a.unlock(lock_a)
+      end
+    end
+  end
+end

data/spec/reentrant_lock_spec.rb

@@ -0,0 +1,49 @@
+require 'spec_helper'
+
+describe Clasp::ReentrantLock do
+  it 'exposes hold count differently depending on calling thread' do
+    subject.hold_count.should == 0
+
+    start_latch = CountdownLatch.new(1)
+    latch = CountdownLatch.new(1)
+
+    t = Thread.new do
+      subject.lock
+      subject.should be_owned
+      subject.hold_count.should == 1
+
+      start_latch.countdown
+      latch.await
+
+      subject.unlock
+    end
+
+    start_latch.await
+
+    subject.should be_owned_by(t)
+    subject.hold_count.should == 0
+
+    latch.countdown
+
+    t.join
+  end
+
+  it 'raises an exception when released by non-owner thread' do
+    expect {
+      subject.unlock
+    }.to raise_error(Clasp::IllegalLockUsageError)
+  end
+
+  it 'removes timed out waiters from the queue' do
+    subject.lock
+
+    t1 = Thread.new do
+      subject.try_timed_lock(0)
+      subject.queue_size.should == 0
+    end
+
+    t1.join
+
+    subject.unlock
+  end
+end

data/spec/spec_helper.rb

@@ -0,0 +1,8 @@
+require 'securerandom'
+require 'simplecov'
+
+SimpleCov.start
+
+require 'clasp'
+
+require File.expand_path '../support/countdown_latch', __FILE__

data/spec/support/countdown_latch.rb

@@ -0,0 +1,24 @@
+class CountdownLatch
+  def initialize(initial)
+    @count = initial
+
+    @mutex = Mutex.new
+    @condition = ConditionVariable.new
+  end
+
+  def countdown
+    @mutex.synchronize do
+      @count -= 1 if @count > 0
+      @condition.broadcast if @count == 0
+    end
+  end
+
+  def await(timeout = nil)
+    @mutex.synchronize do
+      return true if @count == 0
+      @condition.wait @mutex, timeout
+
+      @count == 0
+    end
+  end
+end

metadata

@@ -0,0 +1,120 @@
+--- !ruby/object:Gem::Specification 
+name: clasp
+version: !ruby/object:Gem::Version 
+  version: 0.1.0
+platform: ruby
+authors: 
+- Ian Unruh
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2013-12-08 00:00:00 Z
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: atomic
+  prerelease: false
+  requirement: &id001 !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ~>
+      - !ruby/object:Gem::Version 
+        version: 1.1.14
+  type: :runtime
+  version_requirements: *id001
+- !ruby/object:Gem::Dependency 
+  name: ref
+  prerelease: false
+  requirement: &id002 !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ~>
+      - !ruby/object:Gem::Version 
+        version: 1.0.5
+  type: :runtime
+  version_requirements: *id002
+- !ruby/object:Gem::Dependency 
+  name: thread_safe
+  prerelease: false
+  requirement: &id003 !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ~>
+      - !ruby/object:Gem::Version 
+        version: 0.1.3
+  type: :runtime
+  version_requirements: *id003
+- !ruby/object:Gem::Dependency 
+  name: rake
+  prerelease: false
+  requirement: &id004 !ruby/object:Gem::Requirement 
+    requirements: 
+    - &id005 
+      - ">="
+      - !ruby/object:Gem::Version 
+        version: "0"
+  type: :development
+  version_requirements: *id004
+- !ruby/object:Gem::Dependency 
+  name: rspec
+  prerelease: false
+  requirement: &id006 !ruby/object:Gem::Requirement 
+    requirements: 
+    - *id005
+  type: :development
+  version_requirements: *id006
+- !ruby/object:Gem::Dependency 
+  name: simplecov
+  prerelease: false
+  requirement: &id007 !ruby/object:Gem::Requirement 
+    requirements: 
+    - *id005
+  type: :development
+  version_requirements: *id007
+description: Identifier-based locking with deadlock detection
+email: ianunruh@gmail.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: []
+
+files: 
+- LICENSE
+- README.md
+- lib/clasp.rb
+- lib/clasp/disposable_lock.rb
+- lib/clasp/errors.rb
+- lib/clasp/lock_manager.rb
+- lib/clasp/lock_manager_tracker.rb
+- lib/clasp/reentrant_lock.rb
+- lib/clasp/version.rb
+- spec/lock_manager_spec.rb
+- spec/reentrant_lock_spec.rb
+- spec/spec_helper.rb
+- spec/support/countdown_latch.rb
+homepage: https://github.com/ianunruh/clasp
+licenses: 
+- MIT
+metadata: {}
+
+post_install_message: 
+rdoc_options: []
+
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - *id005
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - *id005
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 2.1.10
+signing_key: 
+specification_version: 4
+summary: Identifier-based locking with deadlock detection
+test_files: 
+- spec/lock_manager_spec.rb
+- spec/reentrant_lock_spec.rb
+- spec/spec_helper.rb
+- spec/support/countdown_latch.rb