Better documentation of RubyExecutor and JavaExecutor.

Author: jdantonio

lib/concurrent/executor/executor.rb

@@ -14,16 +14,18 @@ module RubyExecutor
     include Executor
     include Logging
 
-    # Submit a task to the executor for asynchronous processing.
+    # @!macro [attach] executor_method_post
     #
-    # @param [Array] args zero or more arguments to be passed to the task
+    #   Submit a task to the executor for asynchronous processing.
     #
-    # @yield the asynchronous task to perform
+    #   @param [Array] args zero or more arguments to be passed to the task
     #
-    # @return [Boolean] `true` if the task is queued, `false` if the executor
-    #   is not running
+    #   @yield the asynchronous task to perform
     #
-    # @raise [ArgumentError] if no task is given
+    #   @return [Boolean] `true` if the task is queued, `false` if the executor
+    #     is not running
+    #
+    #   @raise [ArgumentError] if no task is given
     def post(*args, &task)
       raise ArgumentError.new('no block given') unless block_given?
       mutex.synchronize do
@@ -33,40 +35,50 @@ def post(*args, &task)
       end
     end
 
-    # Submit a task to the executor for asynchronous processing.
+    # @!macro [attach] executor_method_left_shift
+    #
+    #   Submit a task to the executor for asynchronous processing.
     #
-    # @param [Proc] task the asynchronous task to perform
+    #   @param [Proc] task the asynchronous task to perform
     #
-    # @return [self] returns itself
+    #   @return [self] returns itself
     def <<(task)
       post(&task)
       self
     end
 
-    # Is the executor running?
+    # @!macro [attach] executor_method_running_question
+    #
+    #   Is the executor running?
     #
-    # @return [Boolean] `true` when running, `false` when shutting down or shutdown
+    #   @return [Boolean] `true` when running, `false` when shutting down or shutdown
     def running?
       ! stop_event.set?
     end
 
-    # Is the executor shuttingdown?
+    # @!macro [attach] executor_method_shuttingdown_question
     #
-    # @return [Boolean] `true` when not running and not shutdown, else `false`
+    #   Is the executor shuttingdown?
+    #
+    #   @return [Boolean] `true` when not running and not shutdown, else `false`
     def shuttingdown?
       ! (running? || shutdown?)
     end
 
-    # Is the executor shutdown?
+    # @!macro [attach] executor_method_shutdown_question
+    #
+    #   Is the executor shutdown?
     #
-    # @return [Boolean] `true` when shutdown, `false` when shutting down or running
+    #   @return [Boolean] `true` when shutdown, `false` when shutting down or running
     def shutdown?
       stopped_event.set?
     end
 
-    # Begin an orderly shutdown. Tasks already in the queue will be executed,
-    # but no new tasks will be accepted. Has no additional effect if the
-    # thread pool is not running.
+    # @!macro [attach] executor_method_shutdown
+    #
+    #   Begin an orderly shutdown. Tasks already in the queue will be executed,
+    #   but no new tasks will be accepted. Has no additional effect if the
+    #   thread pool is not running.
     def shutdown
       mutex.synchronize do
         break unless running?
@@ -76,10 +88,12 @@ def shutdown
       true
     end
 
-    # Begin an immediate shutdown. In-progress tasks will be allowed to
-    # complete but enqueued tasks will be dismissed and no new tasks
-    # will be accepted. Has no additional effect if the thread pool is
-    # not running.
+    # @!macro [attach] executor_method_kill
+    #
+    #   Begin an immediate shutdown. In-progress tasks will be allowed to
+    #   complete but enqueued tasks will be dismissed and no new tasks
+    #   will be accepted. Has no additional effect if the thread pool is
+    #   not running.
     def kill
       mutex.synchronize do
         break if shutdown?
@@ -90,15 +104,17 @@ def kill
       true
     end
 
-    # Block until executor shutdown is complete or until `timeout` seconds have
-    # passed.
+    # @!macro [attach] executor_method_wait_for_termination
+    #
+    #   Block until executor shutdown is complete or until `timeout` seconds have
+    #   passed.
     #
-    # @note Does not initiate shutdown or termination. Either `shutdown` or `kill`
-    #   must be called before this method (or on another thread).
+    #   @note Does not initiate shutdown or termination. Either `shutdown` or `kill`
+    #     must be called before this method (or on another thread).
     #
-    # @param [Integer] timeout the maximum number of seconds to wait for shutdown to complete
+    #   @param [Integer] timeout the maximum number of seconds to wait for shutdown to complete
     #
-    # @return [Boolean] `true` if shutdown complete or false on `timeout`
+    #   @return [Boolean] `true` if shutdown complete or false on `timeout`
     def wait_for_termination(timeout = nil)
       stopped_event.wait(timeout)
     end
@@ -107,20 +123,33 @@ def wait_for_termination(timeout = nil)
 
     attr_reader :mutex, :stop_event, :stopped_event
 
+    # @!macro [attach] executor_method_init_executor
+    #
+    #   Initialize the executor by creating and initializing all the
+    #   internal synchronization objects.
     def init_executor
       @mutex = Mutex.new
       @stop_event = Event.new
       @stopped_event = Event.new
     end
 
+    # @!macro [attach] executor_method_execute
     def execute(*args, &task)
       raise NotImplementedError
     end
 
+    # @!macro [attach] executor_method_shutdown_execution
+    # 
+    #   Callback method called when an orderly shutdown has completed.
+    #   The default behavior is to signal all waiting threads.
     def shutdown_execution
       stopped_event.set
     end
 
+    # @!macro [attach] executor_method_kill_execution
+    #
+    #   Callback method called when the executor has been killed.
+    #   The default behavior is to do nothing.
     def kill_execution
       # do nothing
     end
@@ -131,16 +160,7 @@ def kill_execution
     module JavaExecutor
       include Executor
 
-      # Submit a task to the executor for asynchronous processing.
-      #
-      # @param [Array] args zero or more arguments to be passed to the task
-      #
-      # @yield the asynchronous task to perform
-      #
-      # @return [Boolean] `true` if the task is queued, `false` if the executor
-      #   is not running
-      #
-      # @raise [ArgumentError] if no task is given
+      # @!macro executor_method_post
       def post(*args)
         raise ArgumentError.new('no block given') unless block_given?
         if running?
@@ -153,26 +173,18 @@ def post(*args)
         raise RejectedExecutionError
       end
 
-      # Submit a task to the executor for asynchronous processing.
-      #
-      # @param [Proc] task the asynchronous task to perform
-      #
-      # @return [self] returns itself
+      # @!macro executor_method_left_shift
       def <<(task)
         post(&task)
         self
       end
 
-      # Is the executor running?
-      #
-      # @return [Boolean] `true` when running, `false` when shutting down or shutdown
+      # @!macro executor_method_running_question
       def running?
         ! (shuttingdown? || shutdown?)
       end
 
-      # Is the executor shuttingdown?
-      #
-      # @return [Boolean] `true` when not running and not shutdown, else `false`
+      # @!macro executor_method_shuttingdown_question
       def shuttingdown?
         if @executor.respond_to? :isTerminating
           @executor.isTerminating
@@ -181,38 +193,23 @@ def shuttingdown?
         end
       end
 
-      # Is the executor shutdown?
-      #
-      # @return [Boolean] `true` when shutdown, `false` when shutting down or running
+      # @!macro executor_method_shutdown_question
       def shutdown?
         @executor.isShutdown || @executor.isTerminated
       end
 
-      # Block until executor shutdown is complete or until `timeout` seconds have
-      # passed.
-      #
-      # @note Does not initiate shutdown or termination. Either `shutdown` or `kill`
-      #   must be called before this method (or on another thread).
-      #
-      # @param [Integer] timeout the maximum number of seconds to wait for shutdown to complete
-      #
-      # @return [Boolean] `true` if shutdown complete or false on `timeout`
+      # @!macro executor_method_wait_for_termination
       def wait_for_termination(timeout)
         @executor.awaitTermination(1000 * timeout, java.util.concurrent.TimeUnit::MILLISECONDS)
       end
 
-      # Begin an orderly shutdown. Tasks already in the queue will be executed,
-      # but no new tasks will be accepted. Has no additional effect if the
-      # executor is not running.
+      # @!macro executor_method_shutdown
       def shutdown
         @executor.shutdown
         nil
       end
 
-      # Begin an immediate shutdown. In-progress tasks will be allowed to
-      # complete but enqueued tasks will be dismissed and no new tasks
-      # will be accepted. Has no additional effect if the executor is
-      # not running.
+      # @!macro executor_method_kill
       def kill
         @executor.shutdownNow
         nil