Better documentation of Executors.

Author: jdantonio

lib/concurrent/executor/cached_thread_pool.rb

@@ -15,6 +15,7 @@ module Concurrent
   private_constant :CachedThreadPoolImplementation
 
   # @!macro [attach] cached_thread_pool
+  #
   #   A thread pool that dynamically grows and shrinks to fit the current workload.
   #   New threads are created as needed, existing threads are reused, and threads
   #   that remain idle for too long are killed and removed from the pool. These
@@ -35,11 +36,7 @@ module Concurrent
   #
   #   The API and behavior of this class are based on Java's `CachedThreadPool`
   #
-  #   @see Concurrent::RubyCachedThreadPool
-  #   @see Concurrent::JavaCachedThreadPool
-  #
   # @!macro thread_pool_options
-  #
   # @!macro thread_pool_executor_public_api
   class CachedThreadPool < CachedThreadPoolImplementation
 

lib/concurrent/executor/executor.rb

@@ -3,7 +3,7 @@
 
 module Concurrent
 
-  # @api private
+  # @!visibility private
   module Executor
     extend Concern::Deprecation
 

lib/concurrent/executor/executor_service.rb

@@ -7,57 +7,88 @@
 
 module Concurrent
 
-  # @api private
+  # @!macro [new] executor_service_method_post
+  #
+  #   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 [new] executor_service_method_left_shift
+  #
+  #   Submit a task to the executor for asynchronous processing.
+  #
+  #   @param [Proc] task the asynchronous task to perform
+  #
+  #   @return [self] returns itself
+
+  # @!macro [new] executor_service_method_can_overflow_question
+  #
+  #   Does the task queue have a maximum size?
+  #
+  #   @return [Boolean] True if the task queue has a maximum size else false.
+
+  # @!macro [new] executor_service_method_serialized_question
+  #
+  #   Does this executor guarantee serialization of its operations?
+  #
+  #   @return [Boolean] True if the executor guarantees that all operations
+  #     will be post in the order they are received and no two operations may
+  #     occur simultaneously. Else false.
+
+
+
+
+
+  # @!macro [new] executor_service_public_api
+  #
+  #   @!method post(*args, &task)
+  #     @!macro executor_service_method_post
+  #
+  #   @!method <<(task)
+  #     @!macro executor_service_method_left_shift
+  #
+  #   @!method can_overflow?
+  #     @!macro executor_service_method_can_overflow_question
+  #
+  #   @!method serialized?
+  #     @!macro executor_service_method_serialized_question
+
+
+
+
+
+  # @!macro executor_service_public_api
+  # @!visibility private
   module ExecutorService
     include Concern::Logging
     include Concern::Deprecation
 
-    # @!macro [attach] executor_service_method_post
-    #
-    #   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_service_method_post
     def post(*args, &task)
       raise NotImplementedError
     end
 
-    # @!macro [attach] executor_service_method_left_shift
-    #
-    #   Submit a task to the executor for asynchronous processing.
-    #
-    #   @param [Proc] task the asynchronous task to perform
-    #
-    #   @return [self] returns itself
+    # @!macro executor_service_method_left_shift
     def <<(task)
       post(&task)
       self
     end
 
-    # @!macro [attach] executor_service_method_can_overflow_question
-    #
-    #   Does the task queue have a maximum size?
-    #
-    #   @return [Boolean] True if the task queue has a maximum size else false.
+    # @!macro executor_service_method_can_overflow_question
     #
     # @note Always returns `false`
     def can_overflow?
       false
     end
 
-    # @!macro [attach] executor_service_method_serialized_question
-    #
-    #   Does this executor guarantee serialization of its operations?
-    #
-    #   @return [Boolean] True if the executor guarantees that all operations
-    #     will be post in the order they are received and no two operations may
-    #     occur simultaneously. Else false.
+    # @!macro executor_service_method_serialized_question
     #
     # @note Always returns `false`
     def serialized?
@@ -83,7 +114,7 @@ def serialized?
   #   foo.is_a? Concurrent::SerialExecutor  #=> true
   #   foo.serialized?                       #=> true
   #
-  # @api private
+  # @!visibility private
   module SerialExecutorService
     include ExecutorService
 
@@ -95,6 +126,110 @@ def serialized?
     end
   end
 
+
+
+
+
+  # @!macro [new] executor_service_attr_reader_fallback_policy
+  #   @return [Symbol] The fallback policy in effect. Either `:abort`, `:discard`, or `:caller_runs`.
+
+  # @!macro [new] executor_service_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.
+
+  # @!macro [new] executor_service_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.
+
+  # @!macro [new] executor_service_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).
+  #
+  #   @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 [new] executor_service_method_running_question
+  #
+  #   Is the executor running?
+  #
+  #   @return [Boolean] `true` when running, `false` when shutting down or shutdown
+
+  # @!macro [new] executor_service_method_shuttingdown_question
+  #
+  #   Is the executor shuttingdown?
+  #
+  #   @return [Boolean] `true` when not running and not shutdown, else `false`
+
+  # @!macro [new] executor_service_method_shutdown_question
+  #
+  #   Is the executor shutdown?
+  #
+  #   @return [Boolean] `true` when shutdown, `false` when shutting down or running
+
+  # @!macro [new] executor_service_method_auto_terminate_question
+  #
+  #   Is the executor auto-terminate when the application exits?
+  #
+  #   @return [Boolean] `true` when auto-termination is enabled else `false`.
+
+  # @!macro [new] executor_service_method_auto_terminate_setter
+  #
+  #   Set the auto-terminate behavior for this executor.
+  #
+  #   @param [Boolean] value The new auto-terminate value to set for this executor.
+  #
+  #   @return [Boolean] `true` when auto-termination is enabled else `false`.
+
+
+
+
+
+  # @!macro [new] abstract_executor_service_public_api
+  #
+  #   @!macro executor_service_public_api
+  #
+  #   @!attribute [r] fallback_policy
+  #     @!macro executor_service_attr_reader_fallback_policy
+  #
+  #   @!method shutdown
+  #     @!macro executor_service_method_shutdown
+  #
+  #   @!method kill
+  #     @!macro executor_service_method_kill
+  #
+  #   @!method wait_for_termination(timeout = nil)
+  #     @!macro executor_service_method_wait_for_termination
+  #
+  #   @!method running?
+  #     @!macro executor_service_method_running_question
+  #
+  #   @!method shuttingdown?
+  #     @!macro executor_service_method_shuttingdown_question
+  #
+  #   @!method shutdown?
+  #     @!macro executor_service_method_shutdown_question
+  #
+  #   @!method auto_terminate?
+  #     @!macro executor_service_method_auto_terminate_question
+  #
+  #   @!method auto_terminate=(value)
+  #     @!macro executor_service_method_auto_terminate_setter
+
+
+
+
+
+  # @!macro abstract_executor_service_public_api
   # @!visibility private
   class AbstractExecutorService < Synchronization::Object
     include ExecutorService
@@ -103,7 +238,6 @@ class AbstractExecutorService < Synchronization::Object
     FALLBACK_POLICIES = [:abort, :discard, :caller_runs].freeze
 
     # @!macro [attach] executor_service_attr_reader_fallback_policy
-    #   @return [Symbol] The fallback policy in effect. Either `:abort`, `:discard`, or `:caller_runs`.
     attr_reader :fallback_policy
 
     # Create a new thread pool.
@@ -113,82 +247,41 @@ def initialize(*args, &block)
     end
 
     # @!macro [attach] executor_service_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
       raise NotImplementedError
     end
 
     # @!macro [attach] executor_service_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
       raise NotImplementedError
     end
 
     # @!macro [attach] executor_service_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).
-    #
-    #   @param [Integer] timeout the maximum number of seconds to wait for shutdown to complete
-    #
-    #   @return [Boolean] `true` if shutdown complete or false on `timeout`
     def wait_for_termination(timeout = nil)
       raise NotImplementedError
     end
 
     # @!macro [attach] executor_service_method_running_question
-    #
-    #   Is the executor running?
-    #
-    #   @return [Boolean] `true` when running, `false` when shutting down or shutdown
     def running?
       synchronize { ns_running? }
     end
 
     # @!macro [attach] executor_service_method_shuttingdown_question
-    #
-    #   Is the executor shuttingdown?
-    #
-    #   @return [Boolean] `true` when not running and not shutdown, else `false`
     def shuttingdown?
       synchronize { ns_shuttingdown? }
     end
 
     # @!macro [attach] executor_service_method_shutdown_question
-    #
-    #   Is the executor shutdown?
-    #
-    #   @return [Boolean] `true` when shutdown, `false` when shutting down or running
     def shutdown?
       synchronize { ns_shutdown? }
     end
 
     # @!macro [attach] executor_service_method_auto_terminate_question
-    #
-    #   Is the executor auto-terminate when the application exits?
-    #
-    #   @return [Boolean] `true` when auto-termination is enabled else `false`.
     def auto_terminate?
       synchronize { ns_auto_terminate? }
     end
 
     # @!macro [attach] executor_service_method_auto_terminate_setter
-    #
-    #   Set the auto-terminate behavior for this executor.
-    #
-    #   @param [Boolean] value The new auto-terminate value to set for this executor.
-    #
-    #   @return [Boolean] `true` when auto-termination is enabled else `false`.
     def auto_terminate=(value)
       synchronize { self.ns_auto_terminate = value }
     end
@@ -265,7 +358,8 @@ def terminate_at_exit
     end
   end
 
-  # @api private
+  # @!macro abstract_executor_service_public_api
+  # @!visibility private
   class RubyExecutorService < AbstractExecutorService
 
     def initialize(*args, &block)
@@ -333,7 +427,8 @@ def ns_shutdown?
 
   if Concurrent.on_jruby?
 
-    # @api private
+    # @!macro abstract_executor_service_public_api
+    # @!visibility private
     class JavaExecutorService < AbstractExecutorService
       java_import 'java.lang.Runnable'