quack_concurrency 0.5.4 → 0.6.0

data/lib/quack_concurrency/future/canceled.rb

@@ -1,6 +1,7 @@
 module QuackConcurrency
   class Future
     class Canceled < Error
+
     end
   end
 end

data/lib/quack_concurrency/future/complete.rb

@@ -1,6 +1,7 @@
 module QuackConcurrency
   class Future
     class Complete < Error
+
     end
   end
 end

data/lib/quack_concurrency/mutex.rb

@@ -1,26 +1,31 @@
 module QuackConcurrency
-  
-  # @note duck type for `::Thread::Mutex`
+
+  # {Mutex} is similar to +::Mutex+.
+  #
+  # A few differences include:
+  # * {#lock} supports passing a block and behaves like +::Mutex#synchronize+
+  # * {#unlock} supports passing a block
   class Mutex
-  
+
     # Creates a new {Mutex} concurrency tool.
     # @return [Mutex]
     def initialize
+      @condition_variable = SafeConditionVariable.new
       @mutex = ::Mutex.new
-      @condition_variable = UninterruptibleConditionVariable.new
       @owner = nil
     end
-    
-    # @raise [ThreadError] if current `Thread` is already locking it
+
+    # @raise [ThreadError] if current thread is already locking it
     #@overload lock
-    #  Obtains the lock or sleeps the current `Thread` until it is available.
+    #  Obtains the lock or sleeps the current thread until it is available.
     #  @return [void]
     #@overload lock(&block)
     #  Obtains the lock, runs the block, then releases the lock when the block completes.
-    #  @yield block to run with the lock
+    #  @raise [Exception] any exception raised in block
+    #  @yield block to run while holding the lock
     #  @return [Object] result of the block
     def lock(&block)
-      raise ThreadError, 'this Thread is already locking this Mutex' if owned?
+      raise ThreadError, 'Attempt to lock a mutex which is already locked by this thread' if owned?
       if block_given?
         lock
         begin
@@ -36,40 +41,63 @@ module QuackConcurrency
         nil
       end
     end
-    
+
+    # Checks if it is locked by a thread.
+    # @return [Boolean]
     def locked?
       !!@owner
     end
-    
+
+    # Checks if it is locked by another thread.
+    # @return [Boolean]
+    def locked_out?
+      # don't need a mutex because we know #owned? can't change during the call 
+      locked? && !owned?
+    end
+
+    # Checks if it is locked by current thread.
+    # @return [Boolean]
     def owned?
       @owner == caller
     end
-    
+
+    # Returns the thread locking it if one exists.
+    # @return [nil,Thread] the locking +Thread+ if one exists, otherwise +nil+
     def owner
       @owner
     end
-    
+
+    # Releases the lock and puts this thread to sleep.
+    # @param timeout [nil, Numeric] time to sleep in seconds or +nil+ to sleep forever
+    # @raise [TypeError] if +timeout+ is not +nil+ or +Numeric+
+    # @raise [ArgumentError] if +timeout+ is not positive
+    # @return [Integer] elapsed time sleeping
     def sleep(timeout = nil)
-      if timeout != nil && !timeout.is_a?(Numeric)
-        raise ArgumentError, "'timeout' argument must be nil or a Numeric"
-      end
+      validate_timeout(timeout)
       unlock do
-        if timeout
-          elapsed_time = Kernel.sleep(timeout)
+        if timeout == nil || timeout == Float::INFINITY
+          elapsed_time = (timer { Thread.stop }).round
         else
-          elapsed_time = Kernel.sleep
+          elapsed_time = Kernel.sleep(timeout)
         end
       end
     end
-    
+
+    # Obtains the lock or blocks until the lock is available.
+    # @raise [ThreadError] if block not given
+    # @raise [ThreadError] if current thread is already locking it
+    # @raise [Exception] any exception raised in block
+    # @return [Object] value return from block
     def synchronize(&block)
+      raise ThreadError, 'must be called with a block' unless block_given?
       lock(&block)
     end
-    
-    # Attempts to obtain the lock and returns immediately.
+
+    # Attempts to obtain the lock and return immediately.
+    # @raise [ThreadError] if current thread is already locking it
     # @return [Boolean] returns if the lock was granted
     def try_lock
-      raise ThreadError, 'this Thread is already locking this Mutex' if owned?
+      raise ThreadError, 'Attempt to lock a mutex which is already locked by this thread' if owned?
       @mutex.synchronize do
         if locked?
           false
@@ -79,25 +107,33 @@ module QuackConcurrency
         end
       end
     end
-    
+
+    # @raise [ThreadError] if current thread is not locking it
+    #@overload unlock
+    #  Releases the lock
+    #  @return [void]
+    #@overload unlock(&block)
+    #  Releases the lock, runs the block, then reacquires the lock when available,
+    #    blocking if necessary.
+    #  @raise [Exception] any exception raised in block
+    #  @yield block to run while releasing the lock
+    #  @return [Object] result of the block
     def unlock(&block)
       if block_given?
-        unlock
-        begin
-          yield
-        ensure
-          lock
-        end
+        temporarily_release(&block)
       else
         @mutex.synchronize do
-          raise ThreadError, 'Mutex is not locked' unless locked?
-          raise ThreadError, 'current Thread is not locking the Mutex' unless owned?
+          ensure_can_unlock
           if @condition_variable.any_waiting_threads?
             @condition_variable.signal
             
             # we do this to avoid a bug
-            # consider what would happen if we set this to nil and then a thread called #lock
-            #   before the resuming thread was able to set itself at the owner in #lock
+            # consider this problem, imagine we have three threads:
+            #   * A: this thread
+            #   * B: has previously called #lock and is waiting on the @condition_variable
+            #   * C: enters #lock after A has released the lock but before B has reacquired it
+            #   is this scenario the threads may end up executing not in the chronological order
+            #     that they entered #lock
             @owner = true
           else
             @owner = nil
@@ -106,16 +142,82 @@ module QuackConcurrency
         nil
       end
     end
-    
+
+    # Returns the number of threads currently waiting on it.
+    # @return [Integer]
     def waiting_threads_count
       @condition_variable.waiting_threads_count
     end
-    
+
     private
-    
+
+    # Returns the current thread.
+    # @return [Thread]
     def caller
       Thread.current
     end
-    
+
+    # Ensure it can be unlocked
+    # @raise [ThreadError] if it is not locked by the calling thread
+    def ensure_can_unlock
+      raise ThreadError, 'Attempt to unlock a ReentrantMutex which is not locked' unless locked?
+      raise ThreadError, 'Attempt to unlock a ReentrantMutex which is locked by another thread' unless owned?
+    end
+
+    # Try to immediately lock it.
+    # @api private
+    # @raise [ThreadError] if another thread is locking it
+    # @return [void]
+    def lock_immediately
+      unless try_lock
+        raise ThreadError, 'Attempt to lock a mutex which is locked by another thread'
+      end
+    end
+
+    # Temporarily unlocks it while a block is run.
+    # If an error is raised in the block the it will try to be immediately relocked
+    #   before passing the error up. If unsuccessful, a +ThreadError+ will be raised to
+    #   imitate the core's behavior.
+    # @api private
+    # @raise [ThreadError] if relock unsuccessful after an error
+    # @raise [ArgumentError] if no block given
+    # @return [void]
+    def temporarily_release(&block)
+      raise ArgumentError, 'no block given' unless block_given?
+      unlock
+      begin
+        return_value = yield
+        lock
+      rescue Exception
+        lock_immediately
+        raise
+      end
+      return_value
+    end
+
+    # Calculate time elapsed when running block.
+    # @api private
+    # @yield called while running timer
+    # @yieldparam start_time [Time]
+    # @raise [Exception] any exception raised in block
+    # @return [Float] time elapsed while running block
+    def timer(&block)
+      start_time = Time.now
+      yield(start_time)
+      time_elapsed = Time.now - start_time
+    end
+
+    # Validates a timeout value
+    # @api private
+    # @raise [TypeError] if {timeout} is not +nil+ or +Numeric+
+    # @raise [ArgumentError] if {timeout} is not positive
+    # @return [void]
+    def validate_timeout(timeout)
+      unless timeout == nil
+        raise TypeError, "'timeout' must be nil or a Numeric" unless timeout.is_a?(Numeric)
+        raise ArgumentError, "'timeout' must not be negative" if timeout.negative?
+      end
+    end
+
   end
 end

data/lib/quack_concurrency/queue.rb

@@ -1,31 +1,34 @@
 module QuackConcurrency
-  
-  # @note duck type for +::Thread::Queue+
+
+  # This is a duck type for +::Thread::Queue+.
+  # It is intended to be a drop in replacement for it's core counterpart.
+  # Valuable if +::Thread::Queue+ has not been implemented.
   class Queue
-  
+
     # Creates a new {Queue} concurrency tool.
     # @return [Queue]
     def initialize
+      @closed = false
+      @items = []
       @mutex = ::Mutex.new
       @pop_mutex = Mutex.new
       @waiter = Waiter.new
-      @items = []
-      @closed = false
     end
-    
-    # Removes all objects from the {Queue}.
+
+    # Removes all objects from it.
     # @return [self]
     def clear
       @mutex.synchronize { @items.clear }
       self
     end
-    
-    # Closes the {Queue}. A closed {Queue} cannot be re-opened.
+
+    # Closes it.
+    # Once closed, it cannot be re-opened.
     # After the call to close completes, the following are true:
-    # * {#closed?} will return `true`.
+    # * {#closed?} will return +true+.
     # * {#close} will be ignored.
     # * {#push} will raise an exception.
-    # * until empty, calling {#pop} will return an object from the {Queue} as usual.
+    # * until empty, calling {#pop} will return an object from it as usual.
     # @return [self]
     def close
       @mutex.synchronize do
@@ -35,37 +38,38 @@ module QuackConcurrency
       end
       self
     end
-    
-    # Checks if {Queue} is closed.
+
+    # Checks if it is closed.
     # @return [Boolean]
     def closed?
       @closed
     end
-    
-    # Checks if {Queue} is empty.
+
+    # Checks if it is empty.
     # @return [Boolean]
     def empty?
       @items.empty?
     end
-    
-    # Returns the length of the {Queue}.
+
+    # Returns the length of it.
     # @return [Integer]
     def length
       @items.length
     end
     alias_method :size, :length
-    
-    # Returns the number of threads waiting on the {Queue}.
+
+    # Returns the number of threads waiting on it.
     # @return [Integer]
     def num_waiting
       @pop_mutex.waiting_threads_count + @waiter.waiting_threads_count
     end
-    
-    # Retrieves item from the {Queue}.
-    # @note If the {Queue} is empty, it will block until an item is available.
-    #   If `non_block` is `true`, it will raise {ThreadError} instead.
-    # @raise {ThreadError} if {Queue} is empty and `non_block` is `true`
+
+    # Retrieves an item from it.
+    # @note If it is empty, the method will block until an item is available.
+    # If +non_block+ is +true+, a +ThreadError+ will be raised.
+    # @raise [ThreadError] if it is empty and +non_block+ is +true+
     # @param non_block [Boolean]
+    # @return [Object]
     def pop(non_block = false)
       @pop_mutex.lock do
         @mutex.synchronize do
@@ -83,20 +87,20 @@ module QuackConcurrency
     end
     alias_method :deq, :pop
     alias_method :shift, :pop
-    
-    # Pushes the given object to the {Queue}.
+
+    # Pushes the given object to it.
     # @param item [Object]
     # @return [self]
     def push(item = nil)
       @mutex.synchronize do
         raise ClosedQueueError if closed?
         @items.push(item)
-        @waiter.resume_one
+        @waiter.resume_next
       end
       self
     end
     alias_method :<<, :push
     alias_method :enq, :push
-    
+
   end
 end

data/lib/quack_concurrency/reentrant_mutex.rb

@@ -2,32 +2,41 @@
 
 
 module QuackConcurrency
+
+  # {ReentrantMutex}s are similar to {Mutex}s with with the key distinction being
+  # that a thread can call lock on a {Mutex} that it has already locked.
   class ReentrantMutex < Mutex
-  
+
     # Creates a new {ReentrantMutex} concurrency tool.
     # @return [ReentrantMutex]
     def initialize
       super
       @lock_depth = 0
     end
-    
+
     #@overload lock
-    #  Obtains the lock or sleeps the current `Thread` until it is available.
+    #  Obtains a lock, blocking until available.
+    #  It will acquire a lock even if one is already held.
     #  @return [void]
     #@overload lock(&block)
-    #  Obtains the lock, runs the block, then releases the lock when the block completes.
+    #  Obtains a lock, runs the block, then releases a lock.
+    #  It will block until a lock is available.
+    #  It will acquire a lock even if one is already held.
+    #  @raise [ThreadError] if not locked by the calling thread when unlocking
+    #  @raise [ThreadError] if not holding the same lock count when unlocking
+    #  @raise [Exception] any exception raised in block
     #  @yield block to run with the lock
     #  @return [Object] result of the block
     def lock(&block)
       if block_given?  
         lock
         start_depth = @lock_depth
-        start_owner = owner
         begin
           yield
         ensure
-          unless @lock_depth == start_depth && owner == start_owner
-            raise Error, 'could not unlock reentrant mutex as its state has been modified'
+          ensure_can_unlock
+          unless @lock_depth == start_depth
+            raise ThreadError, 'Attempt to unlock a ReentrantMutex whose lock depth has been changed since locking it'
           end
           unlock
         end
@@ -37,105 +46,84 @@ module QuackConcurrency
         nil
       end
     end
-    
-    # Checks if this {ReentrantMutex} is locked by a Thread other than the caller.
-    # @return [Boolean]
-    def locked_out?
-      # don't need a mutex because we know #owned? can't change during the call 
-      locked? && !owned?
-    end
-    
-    # Releases the lock and sleeps.
-    # When the calling Thread is next woken up, it will attempt to reacquire the lock.
-    # @param timeout [Integer] seconds to sleep, `nil` will sleep forever
-    # @raise [Error] if this {ReentrantMutex} wasn't locked by the calling Thread
-    # @return [void]
+
+    # @see Mutex#sleep
     def sleep(timeout = nil)
-      raise Error, 'can not unlock reentrant mutex, it is not locked' unless locked?
-      raise Error, 'can not unlock reentrant mutex, caller is not the owner' unless owned?
+      ensure_can_unlock
       base_depth do
         super(timeout)
       end
     end
-    
-    # Obtains a lock, runs the block, and releases the lock when the block completes.
-    # @return [Object] value from yielded block
-    def synchronize(&block)
-      lock(&block)
-    end
-    
-    alias parent_try_lock try_lock
-    private :parent_try_lock
+
     # Attempts to obtain the lock and returns immediately.
     # @return [Boolean] returns if the lock was granted
     def try_lock
-      if owned?
+      if owned? || super
         @lock_depth += 1
         true
       else
-        lock_successful = parent_try_lock
-        if lock_successful
-          @lock_depth += 1
-          true
-        else
-          false
-        end
+        false
       end
     end
-    
-    # Releases the lock.
-    # @raise [Error] if {ReentrantMutex} wasn't locked by the calling Thread
-    # @return [void]
+
+    #@overload unlock
+    #  Releases a lock.
+    #  @return [void]
+    #@overload unlock(&block)
+    #  Releases a lock, runs the block, then reacquires the lock when available,
+    #    blocking if necessary.
+    #  @raise [Exception] any exception raised in block
+    #  @raise [ThreadError] if relock unsuccessful after an error
+    #  @yield block to run while releasing the lock
+    #  @return [Object] result of the block
+    # @raise [ThreadError] if it is not locked by this thread
     def unlock(&block)
-      raise Error, 'can not unlock reentrant mutex, it is not locked' unless locked?
-      raise Error, 'can not unlock reentrant mutex, caller is not the owner' unless owned?
+      ensure_can_unlock
       if block_given?
-        unlock
-        begin
-          yield
-        ensure
-          lock
-        end
+        temporarily_release(&block)
       else
         @lock_depth -= 1
         super if @lock_depth == 0
         nil
       end
     end
-    
-    # Releases the lock.
-    # @raise [Error] if {ReentrantMutex} wasn't locked by the calling Thread
-    # @return [void]
+
+    # Releases all lock, runs the block, then reacquires the same lock count when available,
+    #   blocking if necessary.
+    # @raise [ArgumentError] if no block given
+    # @raise [ThreadError] if this thread does not hold any locks
+    # @raise [Exception] any exception raised in block
+    # @yield block to run while locks have been released
+    # @return [Object] result of the block
     def unlock!(&block)
-      raise Error, 'can not unlock reentrant mutex, it is not locked' unless locked?
-      raise Error, 'can not unlock reentrant mutex, caller is not the owner' unless owned?
-      if block_given?
-        base_depth do
-          unlock
-          begin
-            yield
-          ensure
-            lock
-          end
-        end
-      else
-        @lock_depth = 0
-        super
-        nil
+      ensure_can_unlock
+      base_depth do
+        temporarily_release(&block)
       end
     end
-    
+
     private
-    
+
+    # Releases all but one lock, runs the block, then reacquires the released lock count when available,
+    #   blocking if necessary.
     # @api private
+    # @raise [Exception] any exception raised in block
+    # @return [Object] result of the block
     def base_depth(&block)
       start_depth = @lock_depth
       @lock_depth = 1
-      yield
-    ensure
+      return_value = yield
       @lock_depth = start_depth
+      return_value
     end
-    
+
+    # Ensure it can be unlocked
+    # @raise [ThreadError] if it is not locked by this thread
+    # @return [void]
+    def ensure_can_unlock
+      raise ThreadError, 'Attempt to unlock a ReentrantMutex which is not locked' unless locked?
+      raise ThreadError, 'Attempt to unlock a ReentrantMutex which is locked by another thread' unless owned?
+    end
+
   end
 end
-