Better docs and minor function renaming.

Author: jdantonio

lib/concurrent/delay.rb

@@ -41,6 +41,14 @@ class Delay
     include Obligation
     include ExecutorOptions
 
+    # NOTE: Because the global thread pools are lazy-loaded with these objects
+    # there is a performance hit every time we post a new task to one of these
+    # thread pools. Subsequently it is critical that `Delay` perform as fast
+    # as possible post-completion. This class has been highly optimized using
+    # the benchmark script `examples/lazy_and_delay.rb`. Do NOT attempt to
+    # DRY-up this class or perform other refactoring with running the
+    # benchmarks and ensuring that performance is not negatively impacted.
+
     # Create a new `Delay` in the `:pending` state.
     #
     # @yield the delayed operation to perform
@@ -153,6 +161,8 @@ def reconfigure(&block)
 
     # @!visibility private
     def execute_task_once # :nodoc:
+      # this function has been optimized for performance and
+      # should not be modified without running new benchmarks
       mutex.lock
       execute = @computing = true unless @computing
       task    = @task

lib/concurrent/obligation.rb

@@ -10,62 +10,96 @@ module Obligation
     include Dereferenceable
 
     # Has the obligation been fulfilled?
+    #
     # @return [Boolean]
     def fulfilled?
       state == :fulfilled
     end
     alias_method :realized?, :fulfilled?
 
     # Has the obligation been rejected?
+    #
     # @return [Boolean]
     def rejected?
       state == :rejected
     end
 
     # Is obligation completion still pending?
+    #
     # @return [Boolean]
     def pending?
       state == :pending
     end
 
     # Is the obligation still unscheduled?
+    #
     # @return [Boolean]
     def unscheduled?
       state == :unscheduled
     end
 
-    def completed?
+    # Has the obligation completed processing?
+    #
+    # @return [Boolean]
+    def complete?
       [:fulfilled, :rejected].include? state
     end
 
+    # Has the obligation completed processing?
+    #
+    # @return [Boolean]
+    #
+    # @deprecated
+    def completed?
+      warn '[DEPRECATED] Use #complete? instead'
+      complete?
+    end
+
+    # Is the obligation still awaiting completion of processing?
+    #
+    # @return [Boolean]
     def incomplete?
       [:unscheduled, :pending].include? state
     end
 
+    # The current value of the obligation. Will be `nil` while the state is
+    # pending or the operation has been rejected.
+    #
+    # @param [Numeric] timeout the maximum time in seconds to wait.
     # @return [Object] see Dereferenceable#deref
     def value(timeout = nil)
       wait timeout
       deref
     end
 
-    # wait until Obligation is #complete?
-    # @param [Numeric] timeout the maximum time in second to wait.
+    # Wait until obligation is complete or the timeout has been reached.
+    #
+    # @param [Numeric] timeout the maximum time in seconds to wait.
     # @return [Obligation] self
     def wait(timeout = nil)
       event.wait(timeout) if timeout != 0 && incomplete?
       self
     end
 
-    # wait until Obligation is #complete?
-    # @param [Numeric] timeout the maximum time in second to wait.
+    # Wait until obligation is complete or the timeout is reached. Will re-raise
+    # any exceptions raised during processing (but will not raise an exception
+    # on timeout).
+    #
+    # @param [Numeric] timeout the maximum time in seconds to wait.
     # @return [Obligation] self
-    # @raise [Exception] when #rejected? it raises #reason
-    def no_error!(timeout = nil)
+    # @raise [Exception] raises the reason when rejected
+    def wait!(timeout = nil)
       wait(timeout).tap { raise self if rejected? }
     end
+    alias_method :no_error!, :wait!
 
-    # @raise [Exception] when #rejected? it raises #reason
+    # The current value of the obligation. Will be `nil` while the state is
+    # pending or the operation has been rejected. Will re-raise any exceptions
+    # raised during processing (but will not raise an exception on timeout).
+    #
+    # @param [Numeric] timeout the maximum time in seconds to wait.
     # @return [Object] see Dereferenceable#deref
+    # @raise [Exception] raises the reason when rejected
     def value!(timeout = nil)
       wait(timeout)
       if rejected?
@@ -75,13 +109,21 @@ def value!(timeout = nil)
       end
     end
 
+    # The current state of the obligation.
+    #
+    # @return [Symbol] the current state
     def state
       mutex.lock
       @state
     ensure
       mutex.unlock
     end
 
+    # If an exception was raised during processing this will return the
+    # exception object. Will return `nil` when the state is pending or if
+    # the obligation has been successfully fulfilled.
+    #
+    # @return [Exception] the exception raised during processing or `nil`
     def reason
       mutex.lock
       @reason
@@ -134,8 +176,8 @@ def state=(value) # :nodoc:
       mutex.unlock
     end
 
-    # atomic compare and set operation
-    # state is set to next_state only if current state is == expected_current
+    # Atomic compare and set operation
+    # State is set to `next_state` only if `current state == expected_current`.
     #
     # @param [Symbol] next_state
     # @param [Symbol] expected_current

spec/concurrent/actor_spec.rb

@@ -144,7 +144,7 @@ def on_message(message)
           envelope = subject.ask!('a')
           expect(envelope).to be_a_kind_of Envelope
           expect(envelope.message).to eq 'a'
-          expect(envelope.ivar).to be_completed
+          expect(envelope.ivar).to be_complete
           expect(envelope.ivar.value).to eq envelope
           expect(envelope.sender).to eq Thread.current
           terminate_actors subject

spec/concurrent/obligation_spec.rb

@@ -22,7 +22,7 @@ def initialize
     shared_examples :incomplete do
 
       it 'should be not completed' do
-        expect(obligation).not_to be_completed
+        expect(obligation).not_to be_complete
       end
 
       it 'should be incomplete' do
@@ -79,7 +79,7 @@ def initialize
       end
 
       it 'should be completed' do
-        expect(obligation).to be_completed
+        expect(obligation).to be_complete
       end
 
       it 'should be not incomplete' do
@@ -156,7 +156,7 @@ def initialize
       end
 
       it 'should be completed' do
-        expect(obligation).to be_completed
+        expect(obligation).to be_complete
       end
 
       it 'should be not incomplete' do

yardoc

@@ -1 +1 @@
-Subproject commit db7483b80f6efb7df9930f0031508d7e2eb6bad0
+Subproject commit 5aff4706f70d757c15830edd66d74759ff364eda