quack_concurrency 0.3.1 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c54a140614cc505337efaaab611c8bb6d8e19bc794b0204fbd6630dcabe742a9
-  data.tar.gz: '0568def469ea6c5be8645b53f8ccc9aa8a07b18ee072d6b72a88c0717519629b'
+  metadata.gz: 10e029270e81499f14736ffdbd03926f83696ded0fd26b8115fe476d9c7724a9
+  data.tar.gz: 057fddbd478fb2fc8a7ff785f3f0315b360c01491fd4db927f220cadfe7fad64
 SHA512:
-  metadata.gz: 9b52245506a8d0102c74b0160536c575e9e6784a4201776e0a9f4ac3b3975f6c93f0c376a7879529e2f1d6e19272e7b417bea57e77db3114da69daef62e6dcf8
-  data.tar.gz: 6dc0136c93ad3918c68e7c80deb142db0f81760a995a984dfff77537d7f4e3699f95d7b31c9bd1980c8c8bce3981d1840ea63b086b0c095bfea0885a3dbddba4
+  metadata.gz: 9859b662740ad3c4a0d5808b0af646be37d6bad5d06be25885746cd33aaadda174d914c6aabf901a88d7b9ca2a0dffef7424c51e4b7533a94c0031640cacf53a
+  data.tar.gz: cf1689c54c26edb32c9ea46fccb9872cd2c239407401818cbf6cd1c3392ffe52907322a0b2a9a08e53637d42e5707e8415a11c88f666dd1d92006a5198330f3f

data/lib/quack_concurrency/concurrency_tool.rb

@@ -1,4 +1,6 @@
 module QuackConcurrency
+  
+  # @api private
   class ConcurrencyTool
     
     def setup_duck_types(supplied_classes)

data/lib/quack_concurrency/future.rb

@@ -1,6 +1,10 @@
 module QuackConcurrency
   class Future < ConcurrencyTool
     
+    # 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.
+    # @return [Future]
     def initialize(duck_types: nil)
       classes = setup_duck_types(duck_types)
       @condition_variable = classes[:condition_variable].new
@@ -10,17 +14,28 @@ module QuackConcurrency
       @complete = false
     end
     
-    def set(new_value = nil)
+    # 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
-        @value_set = true
         @complete = true
-        @value = new_value
         @condition_variable.broadcast
       end
       nil
     end
     
+    # Checks if future has a value or is canceled.
+    # @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
+    # @return value of the future
     def get
       @mutex.synchronize do
         @condition_variable.wait(@mutex) unless complete?
@@ -30,18 +45,20 @@ module QuackConcurrency
       end
     end
     
-    def cancel
+    # Sets the value of the future.
+    # @raise [Complete] if the future has already completed
+    # @param new_value value to assign to future
+    # @return [void]
+    def set(new_value = nil)
       @mutex.synchronize do
         raise Complete if @complete
+        @value_set = true
         @complete = true
+        @value = new_value
         @condition_variable.broadcast
       end
       nil
     end
     
-    def complete?
-      @complete
-    end
-    
   end
 end

data/lib/quack_concurrency/name.rb

@@ -1,4 +1,6 @@
 module QuackConcurrency
+  
+  # @api private
   class Name < String
     
     def initialize(*args)

data/lib/quack_concurrency/queue/error.rb

@@ -0,0 +1,6 @@
+module QuackConcurrency
+  class Queue
+    class Error < Error
+    end
+  end
+end

data/lib/quack_concurrency/queue.rb

@@ -1,6 +1,12 @@
 module QuackConcurrency
+  
+  # @note duck type for +::Thread::Queue+
   class Queue < ConcurrencyTool
   
+    # 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
@@ -10,11 +16,20 @@ module QuackConcurrency
       @closed = false
     end
     
+    # Removes all objects from the queue.
+    # @return [self]
     def clear
       @mutex.synchronize { @queue = [] }
       self
     end
     
+    # Closes the queue. A closed queue cannot be re-opened.
+    # After the call to close completes, the following are 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.
+    # @return [self]
     def close
       @mutex.synchronize do
         return if closed?
@@ -24,27 +39,41 @@ module QuackConcurrency
       self
     end
     
+    # Checks if queue is closed.
+    # @return [Boolean]
     def closed?
       @closed
     end
     
+    # Checks if queue is empty.
+    # @return [Boolean]
     def empty?
       @queue.empty?
     end
     
+    # Returns the length of the queue.
+    # @return [Integer]
     def length
       @queue.length
     end
     alias_method :size, :length
     
+    # Returns the number of threads waiting on the queue.
+    # @return [Integer]
     def num_waiting
       @waiting_count
     end
     
-    def pop
+    # 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] 
+    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
@@ -56,6 +85,8 @@ module QuackConcurrency
     alias_method :deq, :pop
     alias_method :shift, :pop
     
+    # Pushes the given object to the queue.
+    # @return [self]
     def push(item = nil)
       @mutex.synchronize do
         raise ClosedQueueError if closed?

data/lib/quack_concurrency/reentrant_mutex.rb

@@ -1,8 +1,13 @@
 # based off https://en.wikipedia.org/wiki/Reentrant_mutex
 
+
 module QuackConcurrency
   class ReentrantMutex < ConcurrencyTool
   
+    # Creates a new {ReentrantMutex} 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 [ReentrantMutex]
     def initialize(duck_types: nil)
       classes = setup_duck_types(duck_types)
       @condition_variable = classes[:condition_variable].new
@@ -11,6 +16,8 @@ module QuackConcurrency
       @lock_depth = 0
     end
     
+    # Locks this {ReentrantMutex}. Will block until available.
+    # @return [void]
     def lock
       @mutex.synchronize do
         @condition_variable.wait(@mutex) if @owner && @owner != caller
@@ -21,30 +28,43 @@ module QuackConcurrency
       nil
     end
     
+    # Checks if this {ReentrantMutex} is locked by some thread.
+    # @return [Boolean]
     def locked?
       !!@owner
     end
     
+    # Checks if this {ReentrantMutex} is locked by a thread other than the caller.
+    # @return [Boolean]
     def locked_out?
       @mutex.synchronize { locked? && @owner != caller }
     end
     
+    # Checks if this {ReentrantMutex} is locked by the calling thread.
+    # @return [Boolean]
     def owned?
       @owner == caller
     end
     
-    def sleep(*args)
+    # 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]
+    def sleep(timeout = nil)
       unlock
       # i would rather not need to get a ducktype for sleep so we will just take
       #   advantage of Mutex's sleep method that must take it into account already
       @mutex.synchronize do
-        @mutex.sleep(*args)
+        @mutex.sleep(timeout)
       end
       nil
     ensure
       lock unless owned?
     end
     
+    # Obtains a lock, runs the block, and releases the lock when the block completes.
+    # @return return value from yielded block
     def synchronize
       lock
       start_depth = @lock_depth
@@ -58,6 +78,8 @@ module QuackConcurrency
       unlock
     end
     
+    # Attempts to obtain the lock and returns immediately.
+    # @return [Boolean] returns if the lock was granted
     def try_lock
       @mutex.synchronize do
         return false if @owner && @owner != caller
@@ -67,6 +89,9 @@ module QuackConcurrency
       end
     end
     
+    # Releases the lock.
+    # @raise [Error] if {ReentrantMutex} wasn't locked by the calling thread
+    # @return [void]
     def unlock
       @mutex.synchronize do
         raise Error, 'can not unlock reentrant mutex, it is not locked' if @lock_depth == 0

data/lib/quack_concurrency/semaphore.rb

@@ -1,8 +1,14 @@
 module QuackConcurrency
   class Semaphore < ConcurrencyTool
   
+    # Gets total permit count
+    # @return [Integer]
     attr_reader :permit_count
     
+    # Creates a new {Semaphore} 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 [Semaphore]
     def initialize(permit_count = 1, duck_types: nil)
       classes = setup_duck_types(duck_types)
       @condition_variable = classes[:condition_variable].new
@@ -12,10 +18,14 @@ module QuackConcurrency
       @mutex = ReentrantMutex.new(duck_types: duck_types)
     end
     
+    # Check if a permit is available to be released.
+    # @return [Boolean]
     def permit_available?
       permits_available >= 1
     end
     
+    # Counts number of permits available to be released.
+    # @return [Integer]
     def permits_available
       @mutex.synchronize do
         raw_permits_available = @permit_count - @permits_used
@@ -23,6 +33,8 @@ module QuackConcurrency
       end
     end
     
+    # Returns a permit so it can be released again in the future.
+    # @return [void]
     def reacquire
       @mutex.synchronize do
         raise Error, 'can not reacquire a permit, no permits released right now' if @permits_used == 0
@@ -32,6 +44,9 @@ module QuackConcurrency
       nil
     end
     
+    # Releases a permit.
+    # @note Will block until a permit is available.
+    # @return [void]
     def release
       @mutex.synchronize do
         @condition_variable.wait(@mutex) unless permit_available?
@@ -41,6 +56,9 @@ module QuackConcurrency
       nil
     end
     
+    # Changes the permit count after {Semaphore} has been created.
+    # @raise [Error] if total permit count is reduced and not enough permits are available to remove
+    # @return [void]
     def set_permit_count(new_permit_count)
       verify_permit_count(new_permit_count)
       @mutex.synchronize do
@@ -53,6 +71,11 @@ module QuackConcurrency
       nil
     end
     
+    # Changes the permit count after {Semaphore} has been created.
+    # If total permit count is reduced and not enough permits are available to remove,
+    # it will change the count anyway but some permits will need to be reacquired
+    # before any can be released.
+    # @return [void]
     def set_permit_count!(new_permit_count)
       verify_permit_count(new_permit_count)
       @mutex.synchronize do
@@ -67,6 +90,8 @@ module QuackConcurrency
       nil
     end
     
+    # Releases a permit, runs the block, and reacquires the permit when the block completes.
+    # @return return value from yielded block
     def synchronize
       release
       begin
@@ -76,6 +101,8 @@ module QuackConcurrency
       end
     end
     
+    # Attempts to release a permit and returns immediately.
+    # @return [Boolean] returns if the permit was released
     def try_release
       @mutex.synchronize do
         if permit_available?

data/lib/quack_concurrency/waiter.rb

@@ -1,14 +1,25 @@
 module QuackConcurrency
   class Waiter < ConcurrencyTool
   
+    # Creates a new {Waiter} 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 [Waiter]
     def initialize(duck_types: nil)
       @queue = Queue.new(duck_types: duck_types)
     end
     
+    # Resumes next waiting thread.
+    # @param value value to pass to waiting thread
+    # @return [void]
     def resume(value = nil)
       @queue << value
+      nil
     end
     
+    # Waits for another thread to resume the calling thread.
+    # @note Will block until resumed.
+    # @return value passed from resuming thread
     def wait
       @queue.pop
     end

data/lib/quack_concurrency.rb

@@ -10,6 +10,7 @@ require 'quack_concurrency/semaphore'
 require 'quack_concurrency/waiter'
 require 'quack_concurrency/future/canceled'
 require 'quack_concurrency/future/complete'
+require 'quack_concurrency/queue/error'
 require 'quack_concurrency/reentrant_mutex/error'
 require 'quack_concurrency/semaphore/error'
 

data/spec/queue_spec.rb

@@ -47,6 +47,17 @@ RSpec.describe QuackConcurrency::Queue do
     
   end
   
+  describe "#pop" do
+  
+    context "when #pop is called with non_block set to true" do
+      it "should raise Error" do
+        queue = QuackConcurrency::Queue.new
+        expect{ queue.pop(true) }.to raise_error(QuackConcurrency::Queue::Error)
+      end
+    end
+    
+  end
+  
   describe "#close, #push" do
 
     context "when called when queue is closed" do

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: quack_concurrency
 version: !ruby/object:Gem::Version
-  version: 0.3.1
+  version: 0.4.0
 platform: ruby
 authors:
 - Rob Fors
@@ -29,6 +29,7 @@ files:
 - lib/quack_concurrency/future/complete.rb
 - lib/quack_concurrency/name.rb
 - lib/quack_concurrency/queue.rb
+- lib/quack_concurrency/queue/error.rb
 - lib/quack_concurrency/reentrant_mutex.rb
 - lib/quack_concurrency/reentrant_mutex/error.rb
 - lib/quack_concurrency/semaphore.rb