Updated docs for TimerSet, ScheduledTask, and Concurrent#timer.

Author: jdantonio

lib/concurrent/executor/timer_set.rb

@@ -8,7 +8,10 @@ module Concurrent
 
   # Executes a collection of tasks, each after a given delay. A master task
   # monitors the set and schedules each task for execution at the appropriate
-  # time. Tasks are run on the global task pool or on the supplied executor.
+  # time. Tasks are run on the global thread pool or on the supplied executor.
+  # Each task is represented as a `ScheduledTask`.
+  #
+  # @see Concurrent::ScheduledTask
   #
   # @!macro monotonic_clock_warning
   class TimerSet < RubyExecutorService
@@ -30,15 +33,16 @@ def initialize(opts = {})
     # delay is less than 1/100th of a second the task will be immediately post
     # to the executor.
     #
-    # @param [Float] delay the number of seconds to wait for before executing the task
+    # @param [Float] delay the number of seconds to wait for before executing the task.
+    # @param [Array<Object>] args the arguments passed to the task on execution.
     #
-    # @yield the task to be performed
+    # @yield the task to be performed.
     #
-    # @return [Concurrent::TimerSet::Task, false] IVar representing the task if the post
-    #   is successful; false after shutdown
+    # @return [Concurrent::ScheduledTask, false] IVar representing the task if the post
+    #   is successful; false after shutdown.
     #
-    # @raise [ArgumentError] if the intended execution time is not in the future
-    # @raise [ArgumentError] if no block is given
+    # @raise [ArgumentError] if the intended execution time is not in the future.
+    # @raise [ArgumentError] if no block is given.
     #
     # @!macro deprecated_scheduling_by_clock_time
     def post(delay, *args, &task)
@@ -65,6 +69,9 @@ def kill
 
     protected
 
+    # Initialize the object.
+    #
+    # @param [Hash] opts the options to create the object with.
     # @!visibility private
     def ns_initialize(opts)
       @queue          = PriorityQueue.new(order: :min)
@@ -74,14 +81,21 @@ def ns_initialize(opts)
       self.auto_terminate = opts.fetch(:auto_terminate, true)
     end
 
+    # Post the task to the internal queue.
+    #
+    # @note This is intended as a callback method from ScheduledTask
+    #   only. It is not intended to be used directly. Post a task
+    #   by using the `SchedulesTask#execute` method.
+    #
+    # @!visibility private
     def post_task(task)
       synchronize{ ns_post_task(task) }
     end
 
     # @!visibility private
     def ns_post_task(task)
       return false unless ns_running?
-      if (task.original_delay) <= 0.01
+      if (task.initial_delay) <= 0.01
         task.executor.post{ task.process_task }
       else
         @queue.push(task)
@@ -94,15 +108,17 @@ def ns_post_task(task)
 
     # Remove the given task from the queue.
     #
-    # @note This is intended as a callback method from Task only.
-    #   It is not intended to be used directly. Cancel a task by
-    #   using the `Task#cancel` method.
+    # @note This is intended as a callback method from `ScheduledTask`
+    #   only. It is not intended to be used directly. Cancel a task
+    #   by using the `ScheduledTask#cancel` method.
     #
     # @!visibility private
     def remove_task(task)
       synchronize{ @queue.delete(task) }
     end
 
+    # `ExecutorServic` callback called during shutdown.
+    #
     # @!visibility private
     def shutdown_execution
       @queue.clear

lib/concurrent/scheduled_task.rb

@@ -12,6 +12,7 @@ module Concurrent
   # whereas a `ScheduledTask` is set to execute after a specified delay. This
   # implementation is loosely based on Java's
   # [ScheduledExecutorService](http://docs.oracle.com/javase/7/docs/api/java/util/concurrent/ScheduledExecutorService.html). 
+  # It is a more feature-rich variant of {Concurrent.timer}.
   # 
   # The *intended* schedule time of task execution is set on object construction
   # with the `delay` argument. The delay is a numeric (floating point or integer)
@@ -135,19 +136,29 @@ module Concurrent
   #   #>> The task completed at 2013-11-07 12:26:09 -0500 with value 'What does the fox say?'
   #
   # @!macro monotonic_clock_warning
+  #
+  # @see Concurrent.timer
   class ScheduledTask < IVar
     include Comparable
 
+    # The executor on which to execute the task.
+    # @!visibility private
     attr_reader :executor
 
     # Schedule a task for execution at a specified future time.
     #
-    # @yield the task to be performed
-    #
     # @param [Float] delay the number of seconds to wait for before executing the task
     #
+    # @yield the task to be performed
+    #
     # @!macro executor_and_deref_options
     #
+    # @option opts [object, Array] :args zero or more arguments to be passed the task
+    #   block on execution
+    #
+    # @raise [ArgumentError] When no block is given
+    # @raise [ArgumentError] When given a time that is in the past
+    #
     # @!macro [attach] deprecated_scheduling_by_clock_time
     #
     #   @note Scheduling is now based on a monotonic clock. This makes the timer much
@@ -158,8 +169,7 @@ def initialize(delay, opts = {}, &task)
       raise ArgumentError.new('no block given') unless block_given?
       super(IVar::NO_VALUE, opts, &nil)
       synchronize do
-        @original_delay = delay
-        ns_set_delay_and_time!(delay) # may raise exception
+        @delay = calculate_delay!(delay) # may raise exception
         ns_set_state(:unscheduled)
         @parent = opts.fetch(:timer_set, Concurrent.global_timer_set)
         @args = get_arguments_from(opts)
@@ -170,20 +180,33 @@ def initialize(delay, opts = {}, &task)
       end
     end
 
-    def original_delay
+    # The `delay` value given at instanciation.
+    #
+    # @return [Float] the initial delay.
+    def initial_delay
       synchronize { @delay }
     end
 
-    # @deprecated
+    # The `delay` value given at instanciation.
+    #
+    # @return [Float] the initial delay.
+    #
+    # @deprecated use {#initial_delay} instead
     def delay
-      warn '[DEPRECATED] use #original_delay instead'
-      original_delay
+      warn '[DEPRECATED] use #initial_delay instead'
+      initial_delay
     end
 
+    # The monotonic time at which the the task is scheduled to be executed.
+    # 
+    # @return [Float] the schedule time or nil if `unscheduled`
     def schedule_time
       synchronize { @time }
     end
 
+    # Comparator which orders by schedule time.
+    #
+    # @!visibility private
     def <=>(other)
       self.schedule_time <=> other.schedule_time
     end
@@ -206,7 +229,7 @@ def processing?
     #
     # @return [Boolean] true if the task is in the given state else false
     #
-    # @deprecated
+    # @deprecated Use {#processing?} instead.
     def in_progress?
       warn '[DEPRECATED] use #processing? instead'
       processing?
@@ -215,8 +238,7 @@ def in_progress?
     # Cancel this task and prevent it from executing. A task can only be
     # cancelled if it is pending or unscheduled.
     #
-    # @return [Boolean] true if task execution is successfully cancelled
-    #   else false
+    # @return [Boolean] true if successfully cancelled else false
     def cancel
       if compare_and_set_state(:cancelled, :pending, :unscheduled)
         complete(false, nil, CancelledOperationError.new)
@@ -229,23 +251,34 @@ def cancel
     end
 
     # Cancel this task and prevent it from executing. A task can only be
-    # cancelled if it is pending or unscheduled.
+    # cancelled if it is `:pending` or `:unscheduled`.
     #
-    # @return [Boolean] true if task execution is successfully cancelled
-    #   else false
+    # @return [Boolean] true if successfully cancelled else false
     #
-    # @deprecated
+    # @deprecated Use {#cancel} instead.
     def stop
       warn '[DEPRECATED] use #cancel instead'
       cancel
     end
 
+    # Reschedule the task using the original delay and the current time.
+    # A task can only be reset while it is `:pending`.
+    #
+    # @return [Boolean] true if successfully rescheduled else false
     def reset
       synchronize{ ns_reschedule(@delay) }
     end
 
+    # Reschedule the task using the given delay and the current time.
+    # A task can only be reset while it is `:pending`.
+    #
+    # @param [Float] delay the number of seconds to wait for before executing the task
+    #
+    # @return [Boolean] true if successfully rescheduled else false
+    #
+    # @raise [ArgumentError] When given a time that is in the past
     def reschedule(delay)
-      synchronize{ ns_reschedule(delay) }
+      synchronize{ ns_reschedule(calculate_delay!(delay)) }
     end
 
     # Execute an `:unscheduled` `ScheduledTask`. Immediately sets the state to `:pending`
@@ -255,7 +288,7 @@ def reschedule(delay)
     # @return [ScheduledTask] a reference to `self`
     def execute
       if compare_and_set_state(:pending, :unscheduled)
-        synchronize{ ns_reschedule(@original_delay, false) }
+        synchronize{ ns_schedule(@delay) }
       end
       self
     end
@@ -276,6 +309,8 @@ def self.execute(delay, opts = {}, &task)
       new(delay, opts, &task).execute
     end
 
+    # Execute the task.
+    #
     # @!visibility private
     def process_task
       safe_execute(@task, @args)
@@ -285,20 +320,33 @@ def process_task
 
     protected
 
-    def ns_set_delay_and_time!(delay)
-      @delay = calculate_delay!(delay)
+    # Schedule the task using the given delay and the current time.
+    #
+    # @param [Float] delay the number of seconds to wait for before executing the task
+    #
+    # @return [Boolean] true if successfully rescheduled else false
+    #
+    # @!visibility private
+    def ns_schedule(delay)
+      @delay = delay
       @time = Concurrent.monotonic_time + @delay
+      @parent.send(:post_task, self)
     end
 
-    def ns_reschedule(delay, fail_if_cannot_remove = true)
+    # Reschedule the task using the given delay and the current time.
+    # A task can only be reset while it is `:pending`.
+    #
+    # @param [Float] delay the number of seconds to wait for before executing the task
+    #
+    # @return [Boolean] true if successfully rescheduled else false
+    #
+    # @!visibility private
+    def ns_reschedule(delay)
       return false unless ns_check_state?(:pending)
-      ns_set_delay_and_time!(delay)
-      removed = @parent.send(:remove_task, self)
-      return false if fail_if_cannot_remove && !removed
-      @parent.send(:post_task, self)
+      @parent.send(:remove_task, self) && ns_schedule(delay)
     end
 
-    # Schedule a task to be executed after a given delay (in seconds).
+    # Calculate the actual delay in seconds based on the given delay.
     #
     # @param [Float] delay the number of seconds to wait for before executing the task
     #

lib/concurrent/utility/timer.rb

@@ -5,11 +5,18 @@ module Concurrent
 
   # Perform the given operation asynchronously after the given number of seconds.
   #
+  # This is a convenience method for posting tasks to the global timer set.
+  # It is intended to be simple and easy to use. For greater control use
+  # either `TimerSet` or `ScheduledTask` directly.
+  #
   # @param [Fixnum] seconds the interval in seconds to wait before executing the task
   #
   # @yield the task to execute
   #
-  # @return [Concurrent::TimerSet::Task] IVar representing the task
+  # @return [Concurrent::ScheduledTask] IVar representing the task
+  #
+  # @see Concurrent::ScheduledTask
+  # @see Concurrent::TimerSet
   #
   # @!macro monotonic_clock_warning
   def timer(seconds, *args, &block)

spec/concurrent/executor/timer_set_spec.rb

@@ -252,14 +252,14 @@ module Concurrent
       end
 
       it 'reschdules a pending and unpost task when given a valid time' do
-        original_delay = 10
+        initial_delay = 10
         rescheduled_delay = 20
         expect(queue).to receive(:push).twice.with(any_args).and_call_original
-        task = subject.post(original_delay){ nil }
+        task = subject.post(initial_delay){ nil }
         original_schedule = task.schedule_time
         success = task.reschedule(rescheduled_delay)
         expect(success).to be true
-        expect(task.original_delay).to be_within(0.01).of(rescheduled_delay)
+        expect(task.initial_delay).to be_within(0.01).of(rescheduled_delay)
         expect(task.schedule_time).to be > original_schedule
       end
 
@@ -323,9 +323,9 @@ module Concurrent
     context 'task resetting' do
 
       it 'calls #reschedule with the original delay' do
-        original_delay = 10
-        task = subject.post(original_delay){ nil }
-        expect(task).to receive(:ns_reschedule).with(original_delay)
+        initial_delay = 10
+        task = subject.post(initial_delay){ nil }
+        expect(task).to receive(:ns_reschedule).with(initial_delay)
         task.reset
       end
     end

spec/concurrent/scheduled_task_spec.rb

@@ -66,7 +66,7 @@ def trigger_observable(observable)
         Timecop.freeze do
           now = Time.now
           task = ScheduledTask.new(expected){ nil }.execute
-          expect(task.original_delay).to be_within(0.1).of(expected)
+          expect(task.initial_delay).to be_within(0.1).of(expected)
         end
       end
 
@@ -75,7 +75,7 @@ def trigger_observable(observable)
         expected = 60 * 10
         schedule = Time.now + expected
         task = ScheduledTask.new(schedule){ nil }.execute
-        expect(task.original_delay).to be_within(0.1).of(expected)
+        expect(task.initial_delay).to be_within(0.1).of(expected)
       end
 
       it 'raises an exception when seconds is less than zero' do
@@ -165,7 +165,7 @@ def trigger_observable(observable)
 
       it 'uses the :executor from the options' do
         latch = Concurrent::CountDownLatch.new
-        executor = Concurrent::ImmediateExecutor.new
+        executor = Concurrent::SingleThreadExecutor.new
         expect(executor).to receive(:post).once.with(any_args).and_call_original
         task = ScheduledTask.execute(0.1, executor: executor) do
           latch.count_down