quack_concurrency 0.5.4 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d110c1994e7796f45c3cade0f82f7bae2ce8daa0fa775e32fe92cb5a5d1bb3e7
-  data.tar.gz: 1253c01f31d051a5cdccd599c3d1ce597bc580c9e06311727b132aa4e1f2e172
+  metadata.gz: 98f80adbcb27205b31915dac49d3577b27f9fe57c1c47e54950d1484c6788b90
+  data.tar.gz: f43c9afe0d281b1a739533db8aa6631808ceada3d5712447cc9d35ec3e25a07e
 SHA512:
-  metadata.gz: c44997c7c973429240bbf600ea68818eedb548012ccc0248028a4fc5a18509e9050b44baa92c563190512c1cb34a0999d8624288827915eb4dcdbc05997961ad
-  data.tar.gz: 99f22237f7a44ea60ac10c0a25c8ac6627fa17cf13de2f55e4797a749607f676dd02ffbfd47ade2f93a983e5ca83dab89e8374480ab930326154e47c14d69c36
+  metadata.gz: 8ccbd4e65d61e1a69785d5a35e14e5cb77357260c15958de82abbd3b79567b2cbd3a19667a5f25a7523e55aefb744447473e95bfc60fa19c009bcc1d98932682
+  data.tar.gz: f45e1759342961393e890d8bcb34d5a244ba70eba8c8a5ae7671886692330579b07c9890764d41ad7c442dbe3d1a3a9141b6a26022914430564c154febc18f7b

data/README.md

@@ -1,5 +1,5 @@
 # Quack Concurrency
-This Ruby Gem offers a few concurrency tools that could also be found in [*Concurrent Ruby*](https://github.com/ruby-concurrency/concurrent-ruby). However, all of *Quack Concurrency's* tools will tolerate duck types of Ruby's core classes to adjust the blocking behaviour of the tools. The tools include: `ConditionVariable`, `Future`, `Mutex`, `Queue`, `ReentrantMutex`, `UninterruptibleConditionVariable` and `UninterruptibleSleeper`. The tools will accept duck types for `Thread` and `Kernel`. *TODO: list some projects useing it*.
+This Ruby Gem offers a few concurrency tools that could also be found in [*Concurrent Ruby*](https://github.com/ruby-concurrency/concurrent-ruby). However, all of *Quack Concurrency's* tools will tolerate duck types of Ruby's core `::Mutex` and `::ConditionVariable` classes to adjust the blocking behaviour of the tools. The tools available include: `ConditionVariable`, `Future`, `Mutex`, `Queue`, `ReentrantMutex`, `SafeConditionVariable`, `SafeSleeper` and `Sleeper`. *TODO: list some projects using it*.
 
 # Install
 `gem install quack_concurrency`

data/lib/quack_concurrency.rb

@@ -2,28 +2,21 @@ require 'thread'
 require 'reentrant_mutex'
 
 require 'quack_concurrency/condition_variable'
+require 'quack_concurrency/condition_variable/waitable'
 require 'quack_concurrency/error'
 require 'quack_concurrency/future'
 require 'quack_concurrency/future/canceled'
 require 'quack_concurrency/future/complete'
 require 'quack_concurrency/mutex'
 require 'quack_concurrency/queue'
-require 'quack_concurrency/queue/error'
 require 'quack_concurrency/reentrant_mutex'
-require 'quack_concurrency/reentrant_mutex/error'
-require 'quack_concurrency/uninterruptible_condition_variable'
-require 'quack_concurrency/uninterruptible_sleeper'
+require 'quack_concurrency/safe_condition_variable'
+require 'quack_concurrency/safe_condition_variable/waitable'
+require 'quack_concurrency/sleeper'
+require 'quack_concurrency/safe_sleeper'
 require 'quack_concurrency/waiter'
 
 
-# if you pass a duck type Hash to any of the concurrency tools it will force you to
-#  supply all the required ducktypes, all or nothing, as it were
-# this is to protect against forgetting to pass one of the duck types as this
-#   would be a hard bug to solve otherwise
-
-
 module QuackConcurrency
-  
-  ClosedQueueError = ::ClosedQueueError
-  
+
 end

data/lib/quack_concurrency/condition_variable.rb

@@ -1,128 +1,134 @@
 module QuackConcurrency
-  
-  # @note duck type for `::Thread::ConditionVariable`
+
+  # {ConditionVariable} is similar to +::ConditionVariable+.
+  #
+  # A a few differences include:
+  # * {#wait} supports passing a {ReentrantMutex} and {Mutex}
+  # * methods have been added to get information on waiting threads
   class ConditionVariable
-  
+
     # Creates a new {ConditionVariable} concurrency tool.
     # @return [ConditionVariable]
     def initialize
-      @waiting_threads = []
       @mutex = ::Mutex.new
+      @waitables = []
+      @waitables_to_resume = []
     end
-    
-    # Returns if any `Threads` are currently waiting.
-    # @api private
+
+    # Checks if any threads are waiting on it.
     # @return [Boolean]
     def any_waiting_threads?
       waiting_threads_count >= 1
     end
-    
-    # Wakes up all `Threads` currently waiting.
+
+    # Resumes all threads waiting on it.
     # @return [self]
     def broadcast
       @mutex.synchronize do
-        signal_next until @waiting_threads.empty?
+        signal_next until @waitables_to_resume.empty?
       end
       self
     end
-    
-    # Wakes up the next waiting `Thread`, if any exist.
+
+    # Returns the {Waitable} representing the next thread to be woken.
+    # It will return the thread that made the earliest call to {#wait}.
+    # @api private
+    # @return [Waitable]
+    def next_waitable_to_wake
+      @mutex.synchronize { @waitables.first }
+    end
+
+    # Resumes next thread waiting on it if one exists.
     # @return [self]
     def signal
       @mutex.synchronize do
-        signal_next if @waiting_threads.any?
+        signal_next if @waitables_to_resume.any?
       end
       self
     end
-    
-    # Sleeps the current `Thread`.
-    # @param duration [nil, Numeric] time to sleep in seconds
-    # @api private
-    # @return [void]
-    def sleep(duration)
-      if duration == nil || duration == Float::INFINITY
-        Thread.stop
-      else
-        Thread.sleep(duration)
-      end
-      nil
-    end
-    
-    # Sleeps the current `Thread` until {#signal} or {#broadcast} wake it.
-    # If a {Mutex} is given, the {Mutex} will be unlocked before sleeping and relocked when woken.
-    # @raise [ArgumentError]
-    # @param mutex [nil,Mutex]
-    # @param timeout [nil,Numeric] maximum time to wait, specified in seconds
+
+    # Puts this thread to sleep until another thread resumes it.
+    # Threads will be woken in the chronological order that this was called.
+    # @note Will block until resumed
+    # @param mutex [Mutex] mutex to be unlocked while this thread is sleeping
+    # @param timeout [nil,Numeric] maximum time to sleep in seconds, +nil+ for forever
+    # @raise [TypeError] if +timeout+ is not +nil+ or +Numeric+
+    # @raise [ArgumentError] if +timeout+ is negative
+    # @raise [Exception] any exception raised by +::ConditionVariable#wait+ (eg. interrupts, +ThreadError+)
     # @return [self]
-    def wait(mutex = nil, timeout = nil)
+    def wait(mutex, timeout = nil)
       validate_mutex(mutex)
-      if timeout != nil && !timeout.is_a?(Numeric)
-        raise ArgumentError, "'timeout' argument must be nil or a Numeric"
-      end
-      @mutex.synchronize { @waiting_threads.push(caller) }
-      if mutex
-        # ideally we would would check if this Thread can sleep (not the last Thread alive)
-        #   before we unlock the mutex, however I am not sure is that can be implemented
-        if mutex.respond_to?(:unlock!)
-          mutex.unlock! { sleep(timeout) }
-        else
-          mutex.unlock
-          begin
-            sleep(timeout)
-          ensure # rescue a fatal error (eg. only Thread stopped)
-            if mutex.locked?
-              # another Thread locked this before it died
-              # this is not a correct state to be in but I don't know how to fix it
-              # given that there are no other alive Threads then than the ramifications should be minimal
-            else
-              mutex.lock
-            end
-          end
-        end
-      else
-        sleep(timeout)
+      validate_timeout(timeout)
+      waitable = waitable_for_current_thread
+      @mutex.synchronize do
+        @waitables.push(waitable)
+        @waitables_to_resume.push(waitable)
       end
+      waitable.wait(mutex, timeout)
       self
-    ensure
-      @mutex.synchronize { @waiting_threads.delete(caller) }
     end
-    
-    # Returns the number of `Thread`s currently waiting.
+
+    # Remove a {Waitable} whose thread has been woken.
     # @api private
+    # @return [void]
+    def waitable_woken(waitable)
+      @mutex.synchronize { @waitables.delete(waitable) }
+    end
+
+    # Returns the number of threads currently waiting on it.
     # @return [Integer]
     def waiting_threads_count
-      @waiting_threads_sleepers.length
+      @waitables.length
     end
-    
+
     private
-    
-    # Gets the currently executing `Thread`.
-    # @api private
-    # @return [Thread]
-    def caller
-      Thread.current
-    end
-    
-    # Wakes up the next waiting `Thread`.
-    # Will try again if the `Thread` has already been woken.
+
+    # Wakes up the next waiting thread.
+    # Will try again if the thread has already been woken.
     # @api private
     # @return [void]
     def signal_next
-      begin
-        next_waiting_thread = @waiting_threads.shift
-        next_waiting_thread.run if next_waiting_thread
-      rescue ThreadError
-        # Thread must be dead
-        retry
+      loop do
+        next_waitable = @waitables_to_resume.shift
+        if next_waitable
+          resume_successful = next_waitable.resume
+          break if resume_successful
+        end
       end
       nil
     end
-    
+
+    # Validates that an object behaves like a +::Mutex+
+    # Must be able to lock and unlock +mutex+.
+    # @api private
+    # @param mutex [Mutex] mutex to be validated
+    # @raise [TypeError] if +mutex+ does not behave like a +::Mutex+
+    # @return [void]
     def validate_mutex(mutex)
-      return if mutex == nil
-      return if mutex.respond_to?(:lock) && (mutex.respond_to?(:unlock) || mutex.respond_to?(:unlock!))
-      raise ArgumentError, "'mutex' must respond to 'lock' and ('unlock' or'unlock!')"
+      return if mutex.respond_to?(:lock) && mutex.respond_to?(:unlock)
+      return if mutex.respond_to?(:unlock!)
+      raise TypeError, "'mutex' must respond to ('lock' and 'unlock') or 'unlock!'"
+    end
+
+    # Validates a timeout value
+    # @api private
+    # @param timeout [nil,Numeric]
+    # @raise [TypeError] if +timeout+ is not +nil+ or +Numeric+
+    # @raise [ArgumentError] if +timeout+ is negative
+    # @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
+
+    # Returns a waitable to represent the current thread.
+    # @api private
+    # @return [Waitable]
+    def waitable_for_current_thread
+      Waitable.new(self)
     end
-    
+
   end
 end

data/lib/quack_concurrency/condition_variable/waitable.rb

@@ -0,0 +1,108 @@
+module QuackConcurrency
+  class ConditionVariable
+
+    # Used to put threads to sleep and wake them back up in order.
+    # A given mutex will be unlocked while the thread sleeps.
+    # When waking a thread it will ensure the mutex is relocked before wakng the next thread.
+    # Threads will be woken in the chronological order that {#wait} was called.
+    class Waitable
+
+      # Creates a new {Waitable}.
+      # @return [ConditionVariable]
+      def initialize(condition_variable)
+        @condition_variable = condition_variable
+        @complete_condition_variable = ::ConditionVariable.new
+        @mutex = ::Mutex.new
+        @sleeper = Sleeper.new
+        @state = :inital
+      end
+
+      # Request the sleeping thread to wake.
+      # It will return +false+ if the thread was already woken,
+      #   possibly due to an interrupt or calling +Thread#run+, etc.
+      # @return [Boolean] if the thread was successfully woken during this call
+      def resume
+        @mutex.synchronize do
+          if @state == :complete
+            false
+          else
+            @sleeper.wake
+            true
+          end
+        end
+      end
+
+      # Puts this thread to sleep until {#resume} is called.
+      # Unlocks +mutex+ while sleeping
+      # It will ensure that previous sleeping threads have resumed before mutex is relocked.
+      # @note Will block until resumed
+      # @param mutex [Mutex] mutex to be unlocked while this thread is sleeping
+      # @param timeout [nil,Numeric] maximum time to sleep in seconds, nil for forever
+      # @raise [TypeError] if +timeout+ is not +nil+ or +Numeric+
+      # @raise [ArgumentError] if +timeout+ is negative
+      # @raise [Exception] any exception raised by +::ConditionVariable#wait+ (eg. interrupts, +ThreadError+)
+      # @return [self]
+      def wait(mutex, timeout)
+        # ideally we would would check if this thread can sleep (ie. is not the last thread alive)
+        #   before we unlock the mutex, however I am not sure that it can be implemented
+        if mutex.respond_to?(:unlock!)
+          mutex.unlock! { sleep(timeout) }
+        else
+          mutex_unlock(mutex) { sleep(timeout) }
+        end
+      ensure
+        @mutex.synchronize do
+          @condition_variable.waitable_woken(self)
+          @state = :complete
+          @complete_condition_variable.broadcast
+        end
+      end
+
+      # Wait until thread has woken and relocked the mutex.
+      # Will block until thread has resumed.
+      # Will not block if {#resume} has already been called.
+      # @api private
+      # @return [void]
+      def wait_until_resumed
+        @mutex.synchronize do
+          @complete_condition_variable.wait(@mutex) unless @state == :complete
+        end
+      end
+
+      private
+
+      # Temporarily unlocks a mutex while a block is run.
+      # If an error is raised in the block, +mutex+ 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
+      # @return [void]
+      def mutex_unlock(mutex, &block)
+        mutex.unlock
+        yield
+        mutex.lock
+      rescue Exception
+        unless mutex.try_lock
+          raise ThreadError, "Attempt to lock a mutex which is locked by another thread"
+        end
+        raise
+      end
+
+      # Puts this thread to sleep.
+      # It will ensure that previous sleeping threads have resumed before returning.
+      # @api private
+      # @param timeout [nil, Numeric] time to sleep in seconds, nil for forever
+      # @return [void]
+      def sleep(timeout)
+        @sleeper.sleep(timeout)
+        loop do
+          next_waitable = @condition_variable.next_waitable_to_wake
+          break if next_waitable == self
+          next_waitable.wait_until_resumed
+        end
+      end
+
+    end
+  end
+end

data/lib/quack_concurrency/error.rb

@@ -1,5 +1,5 @@
 module QuackConcurrency
   class Error < StandardError
+
   end
 end
-    

data/lib/quack_concurrency/future.rb

@@ -1,68 +1,69 @@
 module QuackConcurrency
+
+  # Used to send a value or error from one thread to another without the need for coordination.
   class Future
-    
+
     # Creates a new {Future} concurrency tool.
     # @return [Future]
     def initialize
-      @waiter = Waiter.new
-      @mutex = ::Mutex.new
-      @value = nil
       @complete = false
       @exception = false
+      @mutex = ::Mutex.new
+      @value = nil
+      @waiter = Waiter.new
     end
-    
-    # Cancels the {Future}.
-    # Calling {#get} will result in Canceled being raised.
-    # Same as `raise(Canceled.new)`.
-    # @raise [Complete] if the {Future} was already completed
-    # @param exception [Exception] custom `Exception` to set
+
+    # Cancels it.
+    # If no +exception+ is specified, a {Canceled} error will be set.
+    # @raise [Complete] if the {Future} has already completed
+    # @param exception [Exception] custom exception to set (see {#raise})
     # @return [void]
     def cancel(exception = nil)
       exception ||= Canceled.new
       self.raise(exception)
       nil
     end
-    
-    # Checks if {Future} has a value or was canceled.
+
+    # Checks if it has a value or error set.
     # @return [Boolean]
     def complete?
       @complete
     end
-    
-    # Gets the value of the {Future}.
-    # @note This method will block until the future has completed.
-    # @raise [Canceled] if the {Future} is canceled
-    # @raise [Exception] if the {Future} was canceled with a given exception
-    # @return [Object] value of the {Future}
+
+    # Gets it's value.
+    # @note This method will block until the future has completed
+    # @raise [Canceled] if it is canceled
+    # @raise [Exception] if specific error was set
+    # @return [Object] it's value
     def get
       @waiter.wait
       Kernel.raise(@exception) if @exception
       @value
     end
-    
-    # Cancels the {Future} with a custom `Exception`.
-    # @raise [Complete] if the future has already completed
-    # @param exception [Exception]
+
+    # Sets it to an error.
+    # @raise [Complete] if the it has already completed
+    # @param exception [nil,Object] +Exception+ class or instance to set, otherwise a +StandardError+ will be set
     # @return [void]
     def raise(exception = nil)
       exception = case
       when exception == nil then StandardError.new
       when exception.is_a?(Exception) then exception
-      when exception <= Exception then exception.new
+      when Exception >= exception then exception.new
       else
-        Kernel.raise(ArgumentError, "'exception' must be nil or an instance of or descendant of Exception")
+        Kernel.raise(TypeError, "'exception' must be nil or an instance of or descendant of Exception")
       end
       @mutex.synchronize do
         Kernel.raise(Complete) if @complete
         @complete = true
         @exception = exception
-        @waiter.resume_all_forever
+        @waiter.resume_all_indefinitely
       end
       nil
     end
-    
-    # Sets the value of the {Future}.
-    # @raise [Complete] if the {Future} has already completed
+
+    # Sets it to a value.
+    # @raise [Complete] if it has already completed
     # @param new_value [nil,Object] value to assign to future
     # @return [void]
     def set(new_value = nil)
@@ -70,10 +71,10 @@ module QuackConcurrency
         Kernel.raise(Complete) if @complete
         @complete = true
         @value = new_value
-        @waiter.resume_all_forever
+        @waiter.resume_all_indefinitely
       end
       nil
     end
-    
+
   end
 end