quack_concurrency 0.5.4 → 0.6.0

data/lib/quack_concurrency/safe_condition_variable.rb

@@ -0,0 +1,23 @@
+module QuackConcurrency
+
+  # {SafeConditionVariable} is similar to {ConditionVariable}.
+  #
+  # The key distinction is that every call to {#wait} can only be resumed via
+  # the {SafeConditionVariable} (not with +Thread#run+, +Thread#wakeup+, etc.)
+  class SafeConditionVariable < ConditionVariable
+
+    # #@!method wait
+    # Puts this thread to sleep until another thread resumes it via this {SafeConditionVariable}.
+    # @see ConditionVariable#wait
+
+    private
+
+    # Returns a waitable object for current thread.
+    # @api private
+    # @return [Waitable]
+    def waitable_for_current_thread
+      Waitable.new(self)
+    end
+
+  end
+end

data/lib/quack_concurrency/safe_condition_variable/waitable.rb

@@ -0,0 +1,21 @@
+module QuackConcurrency
+  class SafeConditionVariable
+
+    # @see ConditionVariable::Waitable
+    # Uses {SafeSleeper}s to ensure the thread can only be woken by this {SafeConditionVariable}.
+    class Waitable < ConditionVariable::Waitable
+
+      # Creates a new {Waitable}.
+      # @return [Waitable]
+      def initialize(condition_variable)
+        super(condition_variable)
+        @sleeper = SafeSleeper.new
+      end
+
+      # @!method wait
+      # Can only be resumed via {#resume}.
+      # @see ConditionVariable#wait
+
+    end
+  end
+end

data/lib/quack_concurrency/safe_sleeper.rb

@@ -0,0 +1,80 @@
+module QuackConcurrency
+
+  # A {SafeSleeper} can be used to safely sleep a thread or preemptively wake it.
+  #
+  # Unlike simply calling +Thread#sleep+, {#sleep} will ensure that only
+  # calling {#wake} on this {SafeSleeper} will wake the thread.
+  # Any call to +Thread#run+ directly, will be ignored.
+  # Threads are still be resumed if +Thread#raise+ is called which may cause
+  # problems so it should never be used.
+  # A thread can only be put to sleep and woken once for each {SafeSleeper}.
+  class SafeSleeper < Sleeper
+
+    # Creates a new {SafeSleeper} concurrency tool.
+    # @return [SafeSleeper]
+    def initialize
+      super
+      @state = :initial
+    end
+
+    # @see SafeSleeper#sleep
+    def sleep(timeout = nil)
+      timer do |start_time|
+        deadline = wake_deadline(start_time, timeout)
+        enforce_sleep_call_limit
+        @mutex.synchronize do
+          break if @state == :complete
+          @state == :sleep
+          wait(deadline)
+        ensure
+          @state = :complete
+        end
+      end
+    end
+
+    # @see SafeSleeper#wake
+    def wake
+      @mutex.synchronize do
+        enforce_wake_call_limit
+        @state = :complete
+        @condition_variable.signal
+      end
+      nil
+    end
+
+    private
+
+    # Put this thread to sleep and wait for it to be woken.
+    # Will wake if {#wake} is called.
+    # If called with a +deadline+ it will wake when +deadline+ is reached.
+    # @api private
+    # @param deadline [nil,Time] maximum time to sleep, +nil+ for forever
+    # @raise [Exception] any exception raised by +ConditionVariable#wait+ (eg. interrupts, +ThreadError+)
+    # @return [void]
+    def wait(deadline)
+      loop do
+        if deadline
+          remaining = deadline - Time.now
+          @condition_variable.wait(@mutex, remaining) if remaining > 0
+        else
+          @condition_variable.wait(@mutex)
+        end
+        break if @state == :complete
+        break if deadline && Time.now >= deadline
+      end
+    end
+
+    # Calculate the desired time to wake up.
+    # @api private
+    # @param start_time [nil,Time] time when the thread is put to sleep
+    # @param timeout [Numeric] desired time to sleep in seconds, +nil+ for forever
+    # @raise [TypeError] if +start_time+ is not +nil+ or a +Numeric+
+    # @raise [ArgumentError] if +start_time+ is negative
+    # @return [Time]
+    def wake_deadline(start_time, timeout)
+      timeout = process_timeout(timeout)
+      deadline = start_time + timeout if timeout
+    end
+
+  end
+end

data/lib/quack_concurrency/sleeper.rb

@@ -0,0 +1,100 @@
+module QuackConcurrency
+
+  # A {Sleeper} can be used to preemptively wake a thread that will be put to sleep in the future.
+  #
+  # A thread can only be put to sleep and woken once for each {Sleeper}.
+  class Sleeper
+
+    # Creates a new {Sleeper} concurrency tool.
+    # @return [Sleeper]
+    def initialize
+      @state = :initial
+      @mutex = ::Mutex.new
+      @condition_variable = ::ConditionVariable.new
+      @sleep_called = false
+      @wake_called = false
+    end
+
+    # Puts this thread to sleep.
+    # Will be skipped if {#wake} has already been called.
+    # If called without a timeout it will sleep forever.
+    # It can only be called once.
+    # @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 [RuntimeError] if already called once
+    # @raise [Exception] any exception raised by +ConditionVariable#wait+ (eg. interrupts, +ThreadError+)
+    # @return [Float] duration of time the thread was asleep in seconds
+    def sleep(timeout = nil)
+      timeout = process_timeout(timeout)
+      enforce_sleep_call_limit
+      @mutex.synchronize do
+        timer do
+          @condition_variable.wait(@mutex, timeout) unless @wake_called
+        end
+      end
+    end
+
+    # Wake it's sleeping thread, if one exists.
+    # It can only be called once.
+    # @raise [RuntimeError] if already called once
+    # @return [void]
+    def wake
+      @mutex.synchronize do
+        enforce_wake_call_limit
+        @condition_variable.signal
+      end
+      nil
+    end
+
+    private
+
+    # Ensure {#sleep} is not called more than once.
+    # Call this every time {#sleep} is called.
+    # @api private
+    # @raise [RuntimeError] if called more than once
+    # @return [void]
+    def enforce_sleep_call_limit
+      raise RuntimeError, '#sleep has already been called once' if @sleep_called
+      @sleep_called = true
+    end
+
+    # Ensure {#wake} is not called more than once.
+    # Call this every time {#wake} is called.
+    # @api private
+    # @raise [RuntimeError] if called more than once
+    # @return [void]
+    def enforce_wake_call_limit
+      raise RuntimeError, '#wake has already been called once' if @wake_called
+      @wake_called = true
+    end
+
+    # Calculate time elapsed when running a 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, converting to a acceptable value if necessary
+    # @api private
+    # @param timeout [nil,Numeric]
+    # @raise [TypeError] if +timeout+ is not +nil+ or +Numeric+
+    # @raise [ArgumentError] if +timeout+ is negative
+    # @return [nil,Numeric]
+    def process_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
+      timeout = nil if timeout == Float::INFINITY
+      timeout
+    end
+
+  end
+end

data/lib/quack_concurrency/waiter.rb

@@ -1,58 +1,67 @@
 module QuackConcurrency
-  
+
+  # {Waiter} is similar to {ConditionVariable}.
+  #
+  # A few differences include:
+  # * the ability to force any future request to {#wait} to return immediately
+  # * every call to {#wait} can only be resumed via the {Waiter}
+  #   (not with +Thread#run+, +Thread#wakeup+, etc.)
+  # * {#wait} does not accept a mutex
+  # * some methods have been renamed to be more intuitive
   # @api private
   class Waiter
-  
+
     # Creates a new {Waiter} concurrency tool.
     # @return [Waiter]
     def initialize
-      @condition_variable = UninterruptibleConditionVariable.new
-      @resume_all_forever = false
+      @condition_variable = SafeConditionVariable.new
+      @resume_all_indefinitely = false
       @mutex = ::Mutex.new
     end
-    
+
+    # Checks if any threads are waiting on it.
+    # @return [Boolean]
     def any_waiting_threads?
       @condition_variable.any_waiting_threads?
     end
-    
-    # Resumes all current and future waiting Thread.
+
+    # Resumes all threads waiting on it.
     # @return [void]
     def resume_all
       @condition_variable.broadcast
-      nil
     end
-    
-    # Resumes all current and future waiting Thread.
+
+    # Resumes all threads waiting on it and will cause
+    #   any future calls to {#wait} to return immediately. 
     # @return [void]
-    def resume_all_forever
+    def resume_all_indefinitely
       @mutex.synchronize do
-        @resume_all_forever = true
+        @resume_all_indefinitely = true
         resume_all
       end
-      nil
     end
-    
-    # Resumes next waiting Thread if one exists.
+
+    # Resumes next thread waiting on it if one exists.
     # @return [void]
-    def resume_one
+    def resume_next
       @condition_variable.signal
-      nil
     end
-    
-    # Waits for another Thread to resume the calling Thread.
+
+    # Puts this thread to sleep until another thread resumes it via this {Waiter}.
     # @note Will block until resumed.
     # @return [void]
     def wait
       @mutex.synchronize do
-        return if @resume_all_forever
+        return if @resume_all_indefinitely
         @condition_variable.wait(@mutex)
       end
-      nil
     end
-    
+
+    # Returns the number of threads waiting on it.
+    # @return [Integer]
     def waiting_threads_count
       @condition_variable.waiting_threads_count
     end
-    
+
   end
 end

data/spec/condition_variable_spec.rb

@@ -0,0 +1,216 @@
+require 'quack_concurrency'
+
+describe QuackConcurrency::ConditionVariable do
+
+  describe "::new" do
+  
+    context "when called with no arguments" do
+      it "should return a ConditionVariable" do
+        condition_variable = QuackConcurrency::ConditionVariable.new
+        expect(condition_variable).to be_a(QuackConcurrency::ConditionVariable)
+      end
+    end
+
+  end
+
+  describe "#any_waiting_threads?" do
+
+    context "when called with waiting threads" do
+      it "should return true" do
+        condition_variable = QuackConcurrency::ConditionVariable.new
+        mutex = Mutex.new
+        thread = Thread.new { mutex.synchronize { condition_variable.wait(mutex) } }
+        sleep 1
+        expect(condition_variable.any_waiting_threads?).to be true
+        condition_variable.broadcast
+        thread.join
+      end
+    end
+
+    context "when called with no waiting threads" do
+      it "should return false" do
+        condition_variable = QuackConcurrency::ConditionVariable.new
+        expect(condition_variable.any_waiting_threads?).to be false
+      end
+    end
+
+  end
+
+  describe "#broadcast" do
+
+    context "when called with waiting threads" do
+      it "should resume all threads currently waiting" do
+        condition_variable = QuackConcurrency::ConditionVariable.new
+        mutex = ::Mutex.new
+        thread1 = Thread.new { mutex.synchronize { condition_variable.wait(mutex) } }
+        thread2 = Thread.new { mutex.synchronize { condition_variable.wait(mutex) } }
+        sleep 1
+        condition_variable.broadcast
+        sleep 1
+        expect(thread1.alive?).to be false
+        expect(thread2.alive?).to be false
+      end
+    end
+
+    context "when called with no waiting threads" do
+      it "should not raise an error" do
+        condition_variable = QuackConcurrency::ConditionVariable.new
+        expect{ condition_variable.broadcast }.not_to raise_error
+      end
+    end
+
+  end
+
+  describe "#signal" do
+
+    context "when called with waiting threads" do
+      it "should resume the next thread currently waiting" do
+        condition_variable = QuackConcurrency::ConditionVariable.new
+        mutex = Mutex.new
+        values = []
+        Thread.new { mutex.synchronize { condition_variable.wait(mutex); values << 1 } }
+        Thread.new { sleep 1; mutex.synchronize { condition_variable.wait(mutex); values << 2 } }
+        Thread.new { sleep 2; mutex.synchronize { condition_variable.wait(mutex); values << 3 } }
+        sleep 3
+        condition_variable.signal
+        condition_variable.signal
+        condition_variable.signal
+        sleep 1
+        expect(values).to eq [1, 2, 3]
+      end
+    end
+
+    context "when called with no waiting threads" do
+      it "should not raise an error" do
+        condition_variable = QuackConcurrency::ConditionVariable.new
+        expect{ condition_variable.signal }.not_to raise_error
+      end
+    end
+
+  end
+
+  describe "#wait" do
+
+    context "when called without a timeout" do
+      it "should block until #broadcast or #signal are called" do
+        condition_variable = QuackConcurrency::ConditionVariable.new
+        mutex = Mutex.new
+        thread1 = Thread.new { mutex.synchronize { condition_variable.wait(mutex) } }
+        thread2 = Thread.new { mutex.synchronize { condition_variable.wait(mutex) } }
+        sleep 1
+        expect(thread1.alive?).to be true
+        expect(thread2.alive?).to be true
+        condition_variable.broadcast
+        sleep 1
+        expect(thread1.alive?).to be false
+        expect(thread2.alive?).to be false
+      end
+      context "and before Thread#run" do
+        it "should return after Thread#run is called" do
+          condition_variable = QuackConcurrency::ConditionVariable.new
+          mutex = Mutex.new
+          thread = Thread.new { mutex.synchronize { condition_variable.wait(mutex) } }
+          sleep 1
+          thread.run
+          sleep 1
+          expect(thread.alive?).to be false
+        end
+      end
+    end
+
+    context "when called with a timeout" do
+      context "of nil" do
+        it "should return only after #broadcast or #signal are called" do
+          condition_variable = QuackConcurrency::ConditionVariable.new
+          mutex = Mutex.new
+          thread = Thread.new { mutex.synchronize { condition_variable.wait(mutex) } }
+          sleep 1
+          expect(thread.alive?).to be true
+          condition_variable.broadcast
+          sleep 1
+          expect(thread.alive?).to be false
+        end
+      end
+      context "of Float::INFINITY" do
+        it "should return only after #broadcast or #signal are called" do
+          condition_variable = QuackConcurrency::ConditionVariable.new
+          mutex = Mutex.new
+          thread = Thread.new { mutex.synchronize { condition_variable.wait(mutex) } }
+          sleep 1
+          expect(thread.alive?).to be true
+          condition_variable.broadcast
+          sleep 1
+          expect(thread.alive?).to be false
+        end
+      end
+      context "of non Numeric value" do
+        it "should raise TypeError" do
+          condition_variable = QuackConcurrency::ConditionVariable.new
+          mutex = Mutex.new
+          expect{ mutex.synchronize { condition_variable.wait(mutex, '1') } }.to raise_error(TypeError)
+        end
+      end
+      context "of negative Numeric value" do
+        it "should raise ArgumentError" do
+          condition_variable = QuackConcurrency::ConditionVariable.new
+          mutex = Mutex.new
+          expect{ mutex.synchronize { condition_variable.wait(mutex, -1) } }.to raise_error(ArgumentError)
+        end
+      end
+      context "of positive Integer" do
+        it "should block until timeout reached" do
+          condition_variable = QuackConcurrency::ConditionVariable.new
+          mutex = Mutex.new
+          thread = Thread.new { mutex.synchronize { condition_variable.wait(mutex, 2) } }
+          sleep 1
+          expect(thread.alive?).to be true
+          sleep 2
+          expect(thread.alive?).to be false
+        end
+      end
+      context "and Thread#run is called before timeout is reached" do
+        it "should return after Thread#run is called" do
+          condition_variable = QuackConcurrency::ConditionVariable.new
+          mutex = Mutex.new
+          thread = Thread.new { mutex.synchronize { condition_variable.wait(mutex, 3) } }
+          sleep 1
+          thread.run
+          sleep 1
+          expect(thread.alive?).to be false
+        end
+      end
+    end
+
+  end
+
+  describe "#waiting_threads_count" do
+
+    context "when called" do
+      it "should return a Integer" do
+        condition_variable = QuackConcurrency::ConditionVariable.new
+        expect(condition_variable.waiting_threads_count).to be_a(Integer)
+      end
+    end
+
+    context "when called with no waiting threads" do
+      it "should return 0" do
+        condition_variable = QuackConcurrency::ConditionVariable.new
+        expect(condition_variable.waiting_threads_count).to eq(0)
+      end
+    end
+
+    context "when called with one waiting thread" do
+      it "should return 1" do
+        condition_variable = QuackConcurrency::ConditionVariable.new
+        mutex = Mutex.new
+        thread = Thread.new { mutex.synchronize { condition_variable.wait(mutex) } }
+        sleep 1
+        expect(condition_variable.waiting_threads_count).to eq(1)
+        condition_variable.broadcast
+        thread.join
+      end
+    end
+
+  end
+
+end