clasp 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 --- 
 SHA1: 
-  metadata.gz: 5885cf34377db5819f7ede1186985edd13fb5159
-  data.tar.gz: 3a64a4c1e0dfeee866cb52615ed6acb44fc48bd7
+  metadata.gz: 3b554152379fc07df7a3c60574f69bacfbfb5ddf
+  data.tar.gz: 3bdb8d2bc7b29bfc37967f740fe6cd503ca7bea2
 SHA512: 
-  metadata.gz: 046ca81ef9150e7cd3e77ada1f8f27d84dae98941b1cec86728381f74c46478c987163bf438ae3e0743b6951d7fc29ccd17d2ba94058e7c3465b3bb88e8698b2
-  data.tar.gz: ecc4612154e5011d650c99a1e6bab07a1e67ef28a08f0ed9d85597c415cf42bd15f20bae0b6f6b3f9f7f6a24beed9d8e0dcc136eb4e0f547386812cf536d0955
+  metadata.gz: 2170cd98557f990ae3b6eb25c82e3db9fdf9a69d5a98619a9bf9b2653a3b90acd6fb195b7740e5e89a425db354728a6945935a16d90f4fb88e1d5d4ddc2090a8
+  data.tar.gz: 34b46a0aef1dfdedfa4989b3f6f32a3bd6d78107560c2c256b2df366de8e240f2651f604643dd8bd67c1df6f9c2d7474fa8647d035b406d9f6b54e6da34c149f

data/README.md

@@ -1,6 +1,6 @@
 # Clasp
 
-[![Build Status](https://travis-ci.org/ianunruh/clasp.png?branch=master)](https://travis-ci.org/ianunruh/clasp)
+[![Build Status](https://travis-ci.org/ianunruh/clasp.png?branch=master)](https://travis-ci.org/ianunruh/clasp) [![Gem Version](https://badge.fury.io/rb/clasp.png)](http://badge.fury.io/rb/clasp)
 
 Named reentrant locks with deadlock detection for Ruby
 
@@ -38,6 +38,28 @@ The first thread that detects the deadlock can release any locks it holds. After
 it can rollback and try again later. The competing thread will then be able to lock any
 resources it needs to continue.
 
-## Todo
+### Debugging deadlocks
 
-+ More tests
+Clasp provides advanced debugging information when deadlocks occur.
+
+Turn on debugging mode for your application:
+
+```ruby
+Clasp.debug = true
+```
+
+Then log the messages for `Clasp::DeadlockError`. You could see informative details about how
+the deadlock occured:
+
+```
+Imminent deadlock detected
+
+#<Thread:0x62f0 id=6 run> wanted #<DisposableLock 25296/f2057ff3-1a65-4815-ac59-91d0d73f2c87>
+#<Thread:0x62e4 id=7 sleep> is waiting on a lock owned by #<Thread:0x62f0 id=6 run>
+
+Locks owned by #<Thread:0x62f0 id=6 run>
+	#<DisposableLock 25296/a8f0d33e-74db-45cd-867d-aa0ef82dfcf9>
+
+Locks owned by #<Thread:0x62e4 id=7 sleep>
+	#<DisposableLock 25296/f2057ff3-1a65-4815-ac59-91d0d73f2c87>
+```

data/lib/clasp.rb

@@ -6,8 +6,21 @@ require 'thread_safe'
 
 require 'clasp/version'
 
+require 'clasp/deadlock_session'
 require 'clasp/disposable_lock'
 require 'clasp/errors'
 require 'clasp/lock_manager'
 require 'clasp/lock_manager_tracker'
-require 'clasp/reentrant_lock'
+require 'clasp/reentrant_lock'
+
+module Clasp
+  extend self
+
+  # Enable detailed information that can be used to diagnose deadlocks
+  # @return [Boolean]
+  attr_accessor :debug
+
+  alias_method :debug?, :debug
+
+  self.debug = false
+end

data/lib/clasp/deadlock_session.rb

@@ -0,0 +1,82 @@
+module Clasp
+  class DeadlockSession
+    # @raise [DeadlockError]
+    # @param [Thread] thread
+    # @param [DisposableLock] lock
+    # @return [undefined]
+    def self.detect_for(thread, lock)
+      new.detect_for(thread, lock)
+    end
+
+    # @raise [DeadlockError]
+    # @param [Thread] thread
+    # @param [DisposableLock] lock
+    # @return [undefined]
+    def detect_for(thread, lock)
+      @managers = LockManagerTracker.instances
+      @waiters = Set.new
+
+      populate_waiters_for_threads_owned_by(thread)
+
+      @waiters.each do |waiter|
+        if lock.owned_by?(waiter)
+          on_deadlock_detected(thread, lock, waiter)
+        end
+      end
+    end
+
+    private
+
+    # @raise [DeadlockError]
+    # @param [Thread] thread
+    # @param [DisposableLock] lock
+    # @param [Thread] waiter
+    # @return [undefined]
+    def on_deadlock_detected(thread, lock, waiter)
+      if Clasp.debug?
+        message = "Imminent deadlock detected\n"
+        message << "\n"
+        message << "#{thread} wanted #{lock}\n"
+        message << "#{waiter} is waiting on a lock owned by #{thread}\n"
+
+        left_locks = locks_owned_by(thread)
+        right_locks = locks_owned_by(waiter)
+
+        message << "\n"
+        message << "Locks owned by #{thread}\n"
+        left_locks.each do |lock|
+          message << "\t#{lock}\n"
+        end
+
+        message << "\n"
+        message << "Locks owned by #{waiter}\n"
+        right_locks.each do |lock|
+          message << "\t#{lock}\n"
+        end
+      else
+        message = "Imminent deadlock detected while acquiring lock"
+      end
+
+      raise DeadlockError, message
+    end
+
+    # @param [Thread] thread
+    # @return [Enumerable]
+    def locks_owned_by(thread)
+      @managers.flat_map(&:locks).find_all { |lock|
+        lock.owned_by?(thread)
+      }
+    end
+
+    # @param [Thread] thread
+    # @return [undefined]
+    def populate_waiters_for_threads_owned_by(thread)
+      locks_owned_by(thread).flat_map(&:queue).each do |waiter|
+        if @waiters.add?(waiter)
+          # Recursively find waiters for locks owned by this waiter
+          populate_waiters_for_threads_owned_by(waiter)
+        end
+      end
+    end
+  end # DeadlockSession
+end # Clasp

data/lib/clasp/disposable_lock.rb

@@ -5,10 +5,16 @@ module Clasp
 
     def_delegators :@lock, :owned?, :owned_by?, :queue
 
+    # @param [LockManager] manager
+    # @param [Object] identifier
     # @return [undefined]
-    def initialize
+    def initialize(manager, identifier)
       @closed = false
       @lock = ReentrantLock.new
+
+      # Used for debugging purposes
+      @manager = manager.__id__
+      @identifier = identifier
     end
 
     # @return [Boolean]
@@ -40,6 +46,13 @@ module Clasp
       @closed
     end
 
+    # @return [String]
+    def to_s
+      str = "#<DisposableLock #{@manager}/#{@identifier}"
+      str << " closed" if @closed
+      str << ">"
+    end
+
     private
 
     # @return [undefined]
@@ -54,38 +67,8 @@ module Clasp
     # @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
+        DeadlockSession.detect_for(Thread.current, self)
       end
-
-      waiters
     end
-  end
-end
+  end # DisposableLock
+end # Clasp

data/lib/clasp/lock_manager.rb

@@ -15,7 +15,9 @@ module Clasp
     def lock(identifier)
       obtained = false
       until obtained
-        lock = @locks.compute_if_absent(identifier) { DisposableLock.new }
+        lock = @locks.compute_if_absent(identifier) {
+          DisposableLock.new(self, identifier)
+        }
         obtained = lock.lock
         unless obtained
           @locks.delete_pair(identifier, lock)
@@ -40,7 +42,7 @@ module Clasp
     # @return [undefined]
     def unlock(identifier)
       unless @locks.key?(identifier)
-        raise IllegalLockUsageError
+        raise IllegalLockUsageError, "Unknown lock #{identifier}"
       end
 
       lock = @locks.get(identifier)

data/lib/clasp/version.rb

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

data/spec/lock_manager_spec.rb

@@ -6,10 +6,6 @@ describe Clasp::LockManager do
   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)
@@ -49,63 +45,102 @@ describe Clasp::LockManager do
     }.to raise_error(Clasp::IllegalLockUsageError)
   end
 
-  it 'detects a deadlock between two threads' do
-    latch = CountdownLatch.new(2)
-    deadlock = CountdownLatch.new(1)
+  context 'deadlock detection' do
+    let(:threads) { ThreadSafe::Array.new }
+
+    before { Thread.abort_on_exception = true }
+    after  { Thread.abort_on_exception = false }
 
-    start_thread(latch, deadlock, lock_a, subject, lock_b, subject)
-    start_thread(latch, deadlock, lock_b, subject, lock_a, subject)
+    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
 
-    unless deadlock.await(30)
-      raise 'Could not resolve deadlock within 30 seconds'
+      join_all
     end
-  end
 
-  it 'detects a deadlock between three threads in a vector' do
-    latch = CountdownLatch.new(3)
-    deadlock = CountdownLatch.new(1)
+    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)
 
-    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
 
-    unless deadlock.await(30)
-      raise 'Could not resolve deadlock within 30 seconds'
+      join_all
     end
-  end
 
-  it 'detects a deadlock across lock managers' do
-    manager_a = described_class.new
-    manager_b = described_class.new
+    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)
 
-    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)
 
-    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
 
-    unless deadlock.await(30)
-      raise 'Could not resolve deadlock within 30 seconds'
+      join_all
     end
-  end
 
-  private
+    context 'with debugging mode enabled' do
+      before { Clasp.debug = true }
+      after  { Clasp.debug = false }
+
+      it 'provides detailed information about deadlock' do
+        latch = CountdownLatch.new(2)
+        deadlock = CountdownLatch.new(1)
 
-  def start_thread(latch, deadlock, lock_a, manager_a, lock_b, manager_b)
-    Thread.new do
-      manager_a.lock(lock_a)
-      latch.countdown
+        start_thread(latch, deadlock, lock_a, subject, lock_b, subject)
+        start_thread(latch, deadlock, lock_b, subject, lock_a, subject)
 
-      begin
-        latch.await
+        unless deadlock.await(30)
+          raise 'Could not resolve deadlock within 30 seconds'
+        end
 
-        manager_b.lock(lock_b)
-        manager_b.unlock(lock_b)
-      rescue Clasp::DeadlockError
-        deadlock.countdown
-      ensure
-        manager_a.unlock(lock_a)
+        join_all
       end
     end
+
+    private
+
+    def start_thread(latch, deadlock, lock_a, manager_a, lock_b, manager_b)
+      thread = 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
+          @exception = $!
+          deadlock.countdown
+        ensure
+          manager_a.unlock(lock_a)
+        end
+      end
+
+      threads.push(thread)
+    end
+
+    def join_all
+      threads.map(&:join)
+    end
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification 
 name: clasp
 version: !ruby/object:Gem::Version 
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors: 
 - Ian Unruh
@@ -80,6 +80,7 @@ files:
 - LICENSE
 - README.md
 - lib/clasp.rb
+- lib/clasp/deadlock_session.rb
 - lib/clasp/disposable_lock.rb
 - lib/clasp/errors.rb
 - lib/clasp/lock_manager.rb