quack_concurrency 0.4.1 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0ab1347b652fc8daf227009ca005e3d7720b53e7bf25936047630b8b9ba56fcb
-  data.tar.gz: b0ef0c7084f46c038d6ec4ac91b940a2da738cfdec4b9ecf82ab02d15b0cb98a
+  metadata.gz: 7933176e96ff2045aa5e480dcdfc5682bfc4e3e1ce860e9a1810c08a0f1b1024
+  data.tar.gz: 7fa030e38a160f8a136198af6f0fada02de1974c81a06576d1b0cb62934ad230
 SHA512:
-  metadata.gz: '08e1d499bc5a4007a6649b58786c60693f3ff9b76cfc69ad59905d9f367df1a239dca09bca12685ccc166727ed3de9c2299b52535eb1b0a86e9eeb5264672c68'
-  data.tar.gz: f30d2a54cdc67b668ab83ad6bfbf18ac60aacdeaf3358d2c54d88be303152a29f9ebb44648e9cd249193c3d9bc02c3e616f69a6b1f65fdd607d4872b8f00e5a7
+  metadata.gz: a4b9c81683dae54bc82d8db1d9f551635d18bdb0028135483ddaacdfbffdde91f1295d5f5b22498c92ff85bab4fcb1c691cbca61d594bc5d5c62b76503d23842
+  data.tar.gz: 3b474d262f7fa0227f6aa7c25488fb2bae135c5f0ebe4372a79000745143b0e593faaf807e200a1b52309a95cb664e66f580a077af1233c924360e44cb578181

data/README.md

@@ -7,4 +7,4 @@ This Ruby Gem offers a few concurrency tools that could also be found in [*Concu
 Then simply `require 'quack_concurrency'` in your project.
 
 # Documentation
-[![Yard Docs](http://img.shields.io/badge/yard-docs-blue.svg)](http://www.rubydoc.info/gems/quack_concurrency)
+[![Yard Docs](https://img.shields.io/badge/yard-docs-blue.svg?style=for-the-badge)](http://www.rubydoc.info/gems/quack_concurrency)

data/lib/quack_concurrency/condition_variable.rb

@@ -0,0 +1,116 @@
+module QuackConcurrency
+  
+  # @note duck type for `::Thread::ConditionVariable`
+  class ConditionVariable
+  
+    # Creates a new {ConditionVariable} concurrency tool.
+    # @return [ConditionVariable]
+    def initialize
+      @waiting_threads = []
+      @mutex = ::Mutex.new
+    end
+    
+    # Returns if any `Threads` are currently waiting.
+    # @api private
+    # @return [Boolean]
+    def any_waiting_threads?
+      waiting_threads_count >= 1
+    end
+    
+    # Wakes up all `Threads` currently waiting.
+    # @return [self]
+    def broadcast
+      @mutex.synchronize do
+        signal_next until @waiting_threads.empty?
+      end
+      self
+    end
+    
+    # Wakes up the next waiting `Thread`, if any exist.
+    # @return [self]
+    def signal
+      @mutex.synchronize do
+        signal_next if @waiting_threads.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
+    # @return [self]
+    def wait(mutex = nil, 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
+        if mutex.respond_to?(:unlock!)
+          mutex.unlock! { sleep(timeout) }
+        else
+          mutex.unlock
+          sleep(timeout)
+          mutex.lock
+        end
+      else
+        sleep(timeout)
+      end
+      @mutex.synchronize { @waiting_threads.delete(caller) }
+      self
+    end
+    
+    # Returns the number of `Thread`s currently waiting.
+    # @api private
+    # @return [Integer]
+    def waiting_threads_count
+      @waiting_threads_sleepers.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.
+    # @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
+      end
+      nil
+    end
+    
+    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!')"
+    end
+    
+  end
+end

data/lib/quack_concurrency/future.rb

@@ -1,61 +1,72 @@
 module QuackConcurrency
-  class Future < ConcurrencyTool
+  class Future
     
-    # Creates a new +Future+ concurrency tool.
-    # @param duck_types [Hash] hash of core Ruby classes to overload.
-    #   If a +Hash+ is given, the keys +:condition_variable+ and +:mutex+ must be present.
+    # Creates a new {Future} concurrency tool.
     # @return [Future]
-    def initialize(duck_types: nil)
-      classes = setup_duck_types(duck_types)
-      @condition_variable = classes[:condition_variable].new
-      @mutex = classes[:mutex].new
+    def initialize
+      @waiter = Waiter.new
+      @mutex = ::Mutex.new
       @value = nil
-      @value_set = false
       @complete = false
+      @exception = false
     end
     
-    # Cancels the future.
-    # @raise [Complete] if the future is already completed
-    # @return [void] value of the future
-    def cancel
-      @mutex.synchronize do
-        raise Complete if @complete
-        @complete = true
-        @condition_variable.broadcast
-      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
+    # @return [void]
+    def cancel(exception = nil)
+      exception ||= Canceled.new
+      self.raise(exception)
       nil
     end
     
-    # Checks if future has a value or is canceled.
+    # Checks if {Future} has a value or was canceled.
     # @return [Boolean]
     def complete?
       @complete
     end
     
-    # Gets the value of the future.
+    # Gets the value of the {Future}.
     # @note This method will block until the future has completed.
-    # @raise [Canceled] if the future is canceled
-    # @return value of the future
+    # @raise [Canceled] if the {Future} is canceled
+    # @raise [Exception] if the {Future} was canceled with a given exception
+    # @return [Object] value of the {Future}
     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]
+    # @return [void]
+    def raise(exception = nil)
+      unless exception == nil || exception.is_a?(Exception)
+        Kernel.raise(ArgumentError, "'exception' must be nil or an instance of an Exception")
+      end
       @mutex.synchronize do
-        @condition_variable.wait(@mutex) unless complete?
-        raise 'internal error, invalid state' unless complete?
-        raise Canceled unless @value_set
-        @value
+        Kernel.raise(Complete) if @complete
+        @complete = true
+        @exception = exception || StandardError.new
+        @waiter.resume_all_forever
       end
+      nil
     end
     
-    # Sets the value of the future.
-    # @raise [Complete] if the future has already completed
-    # @param new_value value to assign to future
+    # Sets the value of the {Future}.
+    # @raise [Complete] if the {Future} has already completed
+    # @param new_value [nil,Object] value to assign to future
     # @return [void]
     def set(new_value = nil)
       @mutex.synchronize do
-        raise Complete if @complete
-        @value_set = true
+        Kernel.raise(Complete) if @complete
         @complete = true
         @value = new_value
-        @condition_variable.broadcast
+        @waiter.resume_all_forever
       end
       nil
     end

data/lib/quack_concurrency/mutex.rb

@@ -0,0 +1,121 @@
+module QuackConcurrency
+  
+  # @note duck type for `::Thread::Mutex`
+  class Mutex
+  
+    # Creates a new {Mutex} concurrency tool.
+    # @return [Mutex]
+    def initialize
+      @mutex = ::Mutex.new
+      @condition_variable = UninterruptibleConditionVariable.new
+      @owner = nil
+    end
+    
+    # @raise [ThreadError] if current `Thread` is already locking it
+    #@overload lock
+    #  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
+    #  @return [Object] result of the block
+    def lock(&block)
+      raise ThreadError, 'this Thread is already locking this Mutex' if owned?
+      if block_given?
+        lock
+        begin
+          yield
+        ensure
+          unlock
+        end
+      else
+        @mutex.synchronize do
+          @condition_variable.wait(@mutex) if locked?
+          @owner = caller
+        end
+        nil
+      end
+    end
+    
+    def locked?
+      !!@owner
+    end
+    
+    def owned?
+      @owner == caller
+    end
+    
+    def owner
+      @owner
+    end
+    
+    def sleep(timeout = nil)
+      if timeout != nil && !timeout.is_a?(Numeric)
+        raise ArgumentError, "'timeout' argument must be nil or a Numeric"
+      end
+      unlock do
+        if timeout
+          elapsed_time = Kernel.sleep(timeout)
+        else
+          elapsed_time = Kernel.sleep
+        end
+      end
+    end
+    
+    def synchronize(&block)
+      lock(&block)
+    end
+    
+    # Attempts to obtain the lock and returns immediately.
+    # @return [Boolean] returns if the lock was granted
+    def try_lock
+      raise ThreadError, 'this Thread is already locking this Mutex' if owned?
+      @mutex.synchronize do
+        if locked?
+          false
+        else
+          @owner = caller
+          true
+        end
+      end
+    end
+    
+    def unlock(&block)
+      if block_given?
+        unlock
+        begin
+          yield
+        ensure
+          lock
+        end
+      else
+        @mutex.synchronize do
+          raise ThreadError, 'Mutex is not locked' unless locked?
+          raise ThreadError, 'current Thread is not locking the Mutex' unless owned?
+          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
+            @owner = true
+          else
+            @owner = nil
+          end
+        end
+        nil
+      end
+    end
+    
+    def waiting_threads_count
+      @condition_variable.waiting_threads_count
+    end
+    
+    private
+    
+    def caller
+      Thread.current
+    end
+    
+  end
+end

data/lib/quack_concurrency/queue.rb

@@ -1,97 +1,97 @@
 module QuackConcurrency
   
   # @note duck type for +::Thread::Queue+
-  class Queue < ConcurrencyTool
+  class Queue
   
     # Creates a new {Queue} concurrency tool.
-    # @param duck_types [Hash] hash of core Ruby classes to overload.
-    #   If a +Hash+ is given, the keys +:condition_variable+ and +:mutex+ must be present.
     # @return [Queue]
-    def initialize(duck_types: nil)
-      classes = setup_duck_types(duck_types)
-      @condition_variable = classes[:condition_variable].new
-      @mutex = classes[:mutex].new
-      @queue = []
-      @waiting_count = 0
+    def initialize
+      @mutex = ::Mutex.new
+      @pop_mutex = Mutex.new
+      @waiter = Waiter.new
+      @items = []
       @closed = false
     end
     
-    # Removes all objects from the queue.
+    # Removes all objects from the {Queue}.
     # @return [self]
     def clear
-      @mutex.synchronize { @queue = [] }
+      @mutex.synchronize { @items.clear }
       self
     end
     
-    # Closes the queue. A closed queue cannot be re-opened.
+    # Closes the {Queue}. A closed {Queue} 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 the {Queue} as usual.
     # @return [self]
     def close
       @mutex.synchronize do
         return if closed?
         @closed = true
-        @condition_variable.broadcast
+        @waiter.resume_all
       end
       self
     end
     
-    # Checks if queue is closed.
+    # Checks if {Queue} is closed.
     # @return [Boolean]
     def closed?
       @closed
     end
     
-    # Checks if queue is empty.
+    # Checks if {Queue} is empty.
     # @return [Boolean]
     def empty?
-      @queue.empty?
+      @items.empty?
     end
     
-    # Returns the length of the queue.
+    # Returns the length of the {Queue}.
     # @return [Integer]
     def length
-      @queue.length
+      @items.length
     end
     alias_method :size, :length
     
-    # Returns the number of threads waiting on the queue.
+    # Returns the number of threads waiting on the {Queue}.
     # @return [Integer]
     def num_waiting
-      @waiting_count
+      @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 {Error} instead.
-    # @raise {Error} if queue is empty and +non_block+ is true
-    # @param non_block [Boolean] 
+    # 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`
+    # @param non_block [Boolean]
     def pop(non_block = false)
-      @mutex.synchronize do
-        if @waiting_count >= length
-          return if closed?
-          raise Error if non_block
-          @waiting_count += 1
-          @condition_variable.wait(@mutex)
-          @waiting_count -= 1
-          return if closed?
+      @pop_mutex.lock do
+        @mutex.synchronize do
+          if empty?
+            return if closed?
+            raise ThreadError if non_block
+            @mutex.unlock
+            @waiter.wait
+            @mutex.lock
+            return if closed?
+          end
+          @items.shift
         end
-        @queue.shift
       end
     end
     alias_method :deq, :pop
     alias_method :shift, :pop
     
-    # Pushes the given object to the queue.
+    # Pushes the given object to the {Queue}.
+    # @param item [Object]
     # @return [self]
     def push(item = nil)
       @mutex.synchronize do
         raise ClosedQueueError if closed?
-        @queue.push(item)
-        @condition_variable.signal
+        @items.push(item)
+        @waiter.resume_one
       end
       self
     end