Better documentation of Fixed and Cached thread pools.

Author: jdantonio

lib/concurrent/executor/cached_thread_pool.rb

@@ -39,6 +39,22 @@ module Concurrent
   #   @see Concurrent::JavaCachedThreadPool
   #
   # @!macro thread_pool_options
+  #
+  # @!macro thread_pool_executor_public_api
   class CachedThreadPool < CachedThreadPoolImplementation
+
+    # @!macro [new] cached_thread_pool_method_initialize
+    #
+    #   Create a new thread pool.
+    #
+    #   @param [Hash] opts the options defining pool behavior.
+    #   @option opts [Symbol] :fallback_policy (`:abort`) the fallback policy
+    #
+    #   @raise [ArgumentError] if `fallback_policy` is not a known policy
+    #
+    #   @see http://docs.oracle.com/javase/8/docs/api/java/util/concurrent/Executors.html#newCachedThreadPool--
+
+    # @!method initialize(opts = {})
+    #   @!macro cached_thread_pool_method_initialize
   end
 end

lib/concurrent/executor/fixed_thread_pool.rb

@@ -14,6 +14,154 @@ module Concurrent
                                   end
   private_constant :FixedThreadPoolImplementation
 
+  # @!macro [new] thread_pool_executor_constant_default_max_pool_size
+  #   Default maximum number of threads that will be created in the pool.
+
+  # @!macro [new] thread_pool_executor_constant_default_min_pool_size
+  #   Default minimum number of threads that will be retained in the pool.
+
+  # @!macro [new] thread_pool_executor_constant_default_max_queue_size
+  #   Default maximum number of tasks that may be added to the task queue.
+
+  # @!macro [new] thread_pool_executor_constant_default_thread_timeout
+  #   Default maximum number of seconds a thread in the pool may remain idle
+  #   before being reclaimed.
+
+  # @!macro [new] thread_pool_executor_attr_reader_max_length
+  #   The maximum number of threads that may be created in the pool.
+  #   @return [Integer] The maximum number of threads that may be created in the pool.
+
+  # @!macro [new] thread_pool_executor_attr_reader_min_length
+  #   The minimum number of threads that may be retained in the pool.
+  #   @return [Integer] The minimum number of threads that may be retained in the pool.
+
+  # @!macro [new] thread_pool_executor_attr_reader_largest_length
+  #   The largest number of threads that have been created in the pool since construction.
+  #   @return [Integer] The largest number of threads that have been created in the pool since construction.
+
+  # @!macro [new] thread_pool_executor_attr_reader_scheduled_task_count
+  #   The number of tasks that have been scheduled for execution on the pool since construction.
+  #   @return [Integer] The number of tasks that have been scheduled for execution on the pool since construction.
+
+  # @!macro [new] thread_pool_executor_attr_reader_completed_task_count
+  #   The number of tasks that have been completed by the pool since construction.
+  #   @return [Integer] The number of tasks that have been completed by the pool since construction.
+
+  # @!macro [new] thread_pool_executor_attr_reader_idletime
+  #   The number of seconds that a thread may be idle before being reclaimed.
+  #   @return [Integer] The number of seconds that a thread may be idle before being reclaimed.
+
+  # @!macro [new] thread_pool_executor_attr_reader_max_queue
+  #   The maximum number of tasks that may be waiting in the work queue at any one time.
+  #   When the queue size reaches `max_queue` subsequent tasks will be rejected in
+  #   accordance with the configured `fallback_policy`.
+  #
+  #   @return [Integer] The maximum number of tasks that may be waiting in the work queue at any one time.
+  #     When the queue size reaches `max_queue` subsequent tasks will be rejected in
+  #     accordance with the configured `fallback_policy`.
+
+  # @!macro [new] thread_pool_executor_attr_reader_length
+  #   The number of threads currently in the pool.
+  #   @return [Integer] The number of threads currently in the pool.
+
+  # @!macro [new] thread_pool_executor_attr_reader_queue_length
+  #   The number of tasks in the queue awaiting execution.
+  #   @return [Integer] The number of tasks in the queue awaiting execution.
+
+  # @!macro [new] thread_pool_executor_attr_reader_remaining_capacity
+  #   Number of tasks that may be enqueued before reaching `max_queue` and rejecting
+  #   new tasks. A value of -1 indicates that the queue may grow without bound.
+  #
+  #   @return [Integer] Number of tasks that may be enqueued before reaching `max_queue` and rejecting
+  #     new tasks. A value of -1 indicates that the queue may grow without bound.
+
+
+
+
+
+  # @!macro [new] thread_pool_executor_public_api
+  #
+  #   @!attribute [r] fallback_policy
+  #     @!macro executor_service_attr_reader_fallback_policy
+  #
+  #   @!attribute [r] max_length
+  #     @!macro thread_pool_executor_attr_reader_max_length
+  #
+  #   @!attribute [r] min_length
+  #     @!macro thread_pool_executor_attr_reader_min_length
+  #
+  #   @!attribute [r] largest_length
+  #     @!macro thread_pool_executor_attr_reader_largest_length
+  #
+  #   @!attribute [r] scheduled_task_count
+  #     @!macro thread_pool_executor_attr_reader_scheduled_task_count
+  #
+  #   @!attribute [r] completed_task_count
+  #     @!macro thread_pool_executor_attr_reader_completed_task_count
+  #
+  #   @!attribute [r] idletime
+  #     @!macro thread_pool_executor_attr_reader_idletime
+  #
+  #   @!attribute [r] max_queue
+  #     @!macro thread_pool_executor_attr_reader_max_queue
+  #
+  #   @!attribute [r] length
+  #     @!macro thread_pool_executor_attr_reader_length
+  #
+  #   @!attribute [r] queue_length
+  #     @!macro thread_pool_executor_attr_reader_queue_length
+  #
+  #   @!attribute [r] remaining_capacity
+  #     @!macro thread_pool_executor_attr_reader_remaining_capacity
+  #
+  #   @!method can_overflow?
+  #     @!macro executor_service_method_can_overflow_question
+  #
+  #   @!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 [new] fixed_thread_pool_method_initialize
+  #
+  #   Create a new thread pool.
+  #
+  #   @param [Integer] num_threads the number of threads to allocate
+  #   @param [Hash] opts the options defining pool behavior.
+  #   @option opts [Symbol] :fallback_policy (`:abort`) the fallback policy
+  #
+  #   @raise [ArgumentError] if `num_threads` is less than or equal to zero
+  #   @raise [ArgumentError] if `fallback_policy` is not a known policy
+  #
+  #   @see http://docs.oracle.com/javase/8/docs/api/java/util/concurrent/Executors.html#newFixedThreadPool-int-
+
+
+
+
+
   # @!macro [attach] fixed_thread_pool
   #
   #   A thread pool with a set number of threads. The number of threads in the pool
@@ -26,6 +174,8 @@ module Concurrent
   #
   # @!macro [attach] thread_pool_options
   #
+  #   **Thread Pool Options**
+  #
   #   Thread pools support several configuration options:
   #
   #   * `idletime`: The number of seconds that a thread may be idle before being reclaimed.
@@ -78,6 +228,11 @@ module Concurrent
   #   @see http://docs.oracle.com/javase/7/docs/api/java/util/concurrent/Executors.html Java Executors class
   #   @see http://docs.oracle.com/javase/8/docs/api/java/util/concurrent/ExecutorService.html Java ExecutorService interface
   #   @see http://ruby-doc.org//core-2.2.0/Kernel.html#method-i-at_exit Kernel#at_exit
+  #
+  # @!macro thread_pool_executor_public_api
   class FixedThreadPool < FixedThreadPoolImplementation
+
+    # @!method initialize(num_threads, opts = {})
+    #   @!macro fixed_thread_pool_method_initialize
   end
 end

lib/concurrent/executor/java_cached_thread_pool.rb

@@ -6,17 +6,11 @@ module Concurrent
 
     # @!macro cached_thread_pool
     # @!macro thread_pool_options
-    # @api private
+    # @!macro thread_pool_executor_public_api
+    # @!visibility private
     class JavaCachedThreadPool < JavaThreadPoolExecutor
 
-      # Create a new thread pool.
-      #
-      # @param [Hash] opts the options defining pool behavior.
-      # @option opts [Symbol] :fallback_policy (`:abort`) the fallback policy
-      #
-      # @raise [ArgumentError] if `fallback_policy` is not a known policy
-      #
-      # @see http://docs.oracle.com/javase/8/docs/api/java/util/concurrent/Executors.html#newCachedThreadPool--
+      # @!macro cached_thread_pool_method_initialize
       def initialize(opts = {})
         defaults  = { idletime: DEFAULT_THREAD_IDLETIMEOUT }
         overrides = { min_threads:     0,

lib/concurrent/executor/java_fixed_thread_pool.rb

@@ -6,18 +6,11 @@ module Concurrent
 
     # @!macro fixed_thread_pool
     # @!macro thread_pool_options
-    # @api private
+    # @!macro thread_pool_executor_public_api
+    # @!visibility private
     class JavaFixedThreadPool < JavaThreadPoolExecutor
 
-      # Create a new thread pool.
-      #
-      # @param [Hash] opts the options defining pool behavior.
-      # @option opts [Symbol] :fallback_policy (`:abort`) the fallback policy
-      #
-      # @raise [ArgumentError] if `num_threads` is less than or equal to zero
-      # @raise [ArgumentError] if `fallback_policy` is not a known policy
-      #
-      # @see http://docs.oracle.com/javase/8/docs/api/java/util/concurrent/Executors.html#newFixedThreadPool-int-
+      # @!macro fixed_thread_pool_method_initialize
       def initialize(num_threads, opts = {})
         raise ArgumentError.new('number of threads must be greater than zero') if num_threads.to_i < 1
         defaults  = { max_queue:   DEFAULT_MAX_QUEUE_SIZE,

lib/concurrent/executor/ruby_cached_thread_pool.rb

@@ -4,15 +4,11 @@ module Concurrent
 
   # @!macro cached_thread_pool
   # @!macro thread_pool_options
-  # @api private
+  # @!macro thread_pool_executor_public_api
+  # @!visibility private
   class RubyCachedThreadPool < RubyThreadPoolExecutor
 
-    # Create a new thread pool.
-    #
-    # @param [Hash] opts the options defining pool behavior.
-    # @option opts [Symbol] :fallback_policy (`:abort`) the fallback policy
-    #
-    # @raise [ArgumentError] if `fallback_policy` is not a known policy
+    # @!macro cached_thread_pool_method_initialize
     def initialize(opts = {})
       defaults  = { idletime: DEFAULT_THREAD_IDLETIMEOUT }
       overrides = { min_threads:     0,

lib/concurrent/executor/ruby_fixed_thread_pool.rb

@@ -4,17 +4,11 @@ module Concurrent
 
   # @!macro fixed_thread_pool
   # @!macro thread_pool_options
-  # @api private
+  # @!macro thread_pool_executor_public_api
+  # @!visibility private
   class RubyFixedThreadPool < RubyThreadPoolExecutor
 
-    # Create a new thread pool.
-    #
-    # @param [Integer] num_threads the number of threads to allocate
-    # @param [Hash] opts the options defining pool behavior.
-    # @option opts [Symbol] :fallback_policy (`:abort`) the fallback policy
-    #
-    # @raise [ArgumentError] if `num_threads` is less than or equal to zero
-    # @raise [ArgumentError] if `fallback_policy` is not a known policy
+    # @!macro fixed_thread_pool_method_initialize
     def initialize(num_threads, opts = {})
       raise ArgumentError.new('number of threads must be greater than zero') if num_threads.to_i < 1
       defaults  = { max_queue:   DEFAULT_MAX_QUEUE_SIZE,