Better documentation of ThreadPoolExecutor.

Author: jdantonio

lib/concurrent/executor/executor_service.rb

@@ -95,15 +95,18 @@ def serialized?
     end
   end
 
-  # @api private
+  # @!visibility private
   class AbstractExecutorService < Synchronization::Object
     include ExecutorService
 
     # The set of possible fallback policies that may be set at thread pool creation.
     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.
     def initialize(*args, &block)
       super(&nil)
       synchronize { ns_initialize(*args, &block) }
@@ -170,10 +173,22 @@ 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

lib/concurrent/executor/fixed_thread_pool.rb

@@ -24,9 +24,6 @@ module Concurrent
   #
   #   The API and behavior of this class are based on Java's `FixedThreadPool`
   #
-  #   @see Concurrent::RubyFixedThreadPool
-  #   @see Concurrent::JavaFixedThreadPool
-  #
   # @!macro [attach] thread_pool_options
   #
   #   Thread pools support several configuration options:
@@ -77,12 +74,6 @@ module Concurrent
   #   @note Failure to properly shutdown a thread pool can lead to unpredictable results.
   #     Please read *Shutting Down Thread Pools* for more information.
   #
-  #   @note When running on the JVM (JRuby) this class will inherit from `JavaFixedThreadPool`.
-  #     On all other platforms it will inherit from `RubyFixedThreadPool`.
-  #
-  #   @see Concurrent::RubyFixedThreadPool
-  #   @see Concurrent::JavaFixedThreadPool
-  #
   #   @see http://docs.oracle.com/javase/tutorial/essential/concurrency/pools.html Java Tutorials: Thread Pools
   #   @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

lib/concurrent/executor/java_thread_pool_executor.rb

@@ -5,53 +5,28 @@ module Concurrent
 
     # @!macro thread_pool_executor
     # @!macro thread_pool_options
-    # @api private
+    # @!visibility private
     class JavaThreadPoolExecutor < JavaExecutorService
 
-      # Default maximum number of threads that will be created in the pool.
+      # @!macro thread_pool_executor_constant_default_max_pool_size
       DEFAULT_MAX_POOL_SIZE = java.lang.Integer::MAX_VALUE # 2147483647
 
-      # Default minimum number of threads that will be retained in the pool.
+      # @!macro thread_pool_executor_constant_default_min_pool_size
       DEFAULT_MIN_POOL_SIZE = 0
 
-      # Default maximum number of tasks that may be added to the task queue.
+      # @!macro thread_pool_executor_constant_default_max_queue_size
       DEFAULT_MAX_QUEUE_SIZE = 0
 
-      # Default maximum number of seconds a thread in the pool may remain idle
-      # before being reclaimed.
+      # @!macro thread_pool_executor_constant_default_thread_timeout
       DEFAULT_THREAD_IDLETIMEOUT = 60
 
-      # The maximum number of threads that may be created in the pool.
+      # @!macro thread_pool_executor_attr_reader_max_length
       attr_reader :max_length
 
-      # 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 thread_pool_executor_attr_reader_max_queue
       attr_reader :max_queue
 
-      # Create a new thread pool.
-      #
-      # @param [Hash] opts the options which configure the thread pool
-      #
-      # @option opts [Integer] :max_threads (DEFAULT_MAX_POOL_SIZE) the maximum
-      #   number of threads to be created
-      # @option opts [Integer] :min_threads (DEFAULT_MIN_POOL_SIZE) the minimum
-      #   number of threads to be retained
-      # @option opts [Integer] :idletime (DEFAULT_THREAD_IDLETIMEOUT) the maximum
-      #   number of seconds a thread may be idle before being reclaimed
-      # @option opts [Integer] :max_queue (DEFAULT_MAX_QUEUE_SIZE) the maximum
-      #   number of tasks allowed in the work queue at any one time; a value of
-      #   zero means the queue may grow without bound
-      # @option opts [Symbol] :fallback_policy (:abort) the policy for handling new
-      #   tasks that are received when the queue size has reached
-      #   `max_queue` or the executir has shut down
-      #
-      # @raise [ArgumentError] if `:max_threads` is less than one
-      # @raise [ArgumentError] if `:min_threads` is less than zero
-      # @raise [ArgumentError] if `:fallback_policy` is not one of the values specified
-      #   in `FALLBACK_POLICIES`
-      #
-      # @see http://docs.oracle.com/javase/7/docs/api/java/util/concurrent/ThreadPoolExecutor.html
+      # @!macro thread_pool_executor_method_initialize
       def initialize(opts = {})
         super(opts)
       end
@@ -61,73 +36,52 @@ def can_overflow?
         @max_queue != 0
       end
 
-      # The minimum number of threads that may be retained in the pool.
-      #
-      # @return [Integer] the min_length
+      # @!macro thread_pool_executor_attr_reader_min_length
       def min_length
         @executor.getCorePoolSize
       end
 
-      # The maximum number of threads that may be created in the pool.
-      #
-      # @return [Integer] the max_length
+      # @!macro thread_pool_executor_attr_reader_max_length
       def max_length
         @executor.getMaximumPoolSize
       end
 
-      # The number of threads currently in the pool.
-      #
-      # @return [Integer] the length
+      # @!macro thread_pool_executor_attr_reader_length
       def length
         @executor.getPoolSize
       end
 
-      # The largest number of threads that have been created in the pool since construction.
-      #
-      # @return [Integer] the largest_length
+      # @!macro thread_pool_executor_attr_reader_largest_length
       def largest_length
         @executor.getLargestPoolSize
       end
 
-      # The number of tasks that have been scheduled for execution on the pool since construction.
-      #
-      # @return [Integer] the scheduled_task_count
+      # @!macro thread_pool_executor_attr_reader_scheduled_task_count
       def scheduled_task_count
         @executor.getTaskCount
       end
 
-      # The number of tasks that have been completed by the pool since construction.
-      #
-      # @return [Integer] the completed_task_count
+      # @!macro thread_pool_executor_attr_reader_completed_task_count
       def completed_task_count
         @executor.getCompletedTaskCount
       end
 
-      # The number of seconds that a thread may be idle before being reclaimed.
-      #
-      # @return [Integer] the idletime
+      # @!macro thread_pool_executor_attr_reader_idletime
       def idletime
         @executor.getKeepAliveTime(java.util.concurrent.TimeUnit::SECONDS)
       end
 
-      # The number of tasks in the queue awaiting execution.
-      #
-      # @return [Integer] the queue_length
+      # @!macro thread_pool_executor_attr_reader_queue_length
       def queue_length
         @executor.getQueue.size
       end
 
-      # 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] the remaining_capacity
+      # @!macro thread_pool_executor_attr_reader_remaining_capacity
       def remaining_capacity
         @max_queue == 0 ? -1 : @executor.getQueue.remainingCapacity
       end
 
-      # Is the thread pool running?
-      #
-      # @return [Boolean] `true` when running, `false` when shutting down or shutdown
+      # @!macro executor_service_method_running_question
       def running?
         super && !@executor.isTerminating
       end

lib/concurrent/executor/ruby_thread_pool_executor.rb

@@ -9,68 +9,43 @@ module Concurrent
 
   # @!macro thread_pool_executor
   # @!macro thread_pool_options
-  # @api private
+  # @!visibility private
   class RubyThreadPoolExecutor < RubyExecutorService
 
-    # Default maximum number of threads that will be created in the pool.
+    # @!macro thread_pool_executor_constant_default_max_pool_size
     DEFAULT_MAX_POOL_SIZE      = 2_147_483_647 # java.lang.Integer::MAX_VALUE
 
-    # Default minimum number of threads that will be retained in the pool.
+    # @!macro thread_pool_executor_constant_default_min_pool_size
     DEFAULT_MIN_POOL_SIZE      = 0
 
-    # Default maximum number of tasks that may be added to the task queue.
+    # @!macro thread_pool_executor_constant_default_max_queue_size
     DEFAULT_MAX_QUEUE_SIZE     = 0
 
-    # Default maximum number of seconds a thread in the pool may remain idle
-    # before being reclaimed.
+    # @!macro thread_pool_executor_constant_default_thread_timeout
     DEFAULT_THREAD_IDLETIMEOUT = 60
 
-    # The maximum number of threads that may be created in the pool.
+    # @!macro thread_pool_executor_attr_reader_max_length
     attr_reader :max_length
 
-    # The minimum number of threads that may be retained in the pool.
+    # @!macro thread_pool_executor_attr_reader_min_length
     attr_reader :min_length
 
-    # The largest number of threads that have been created in the pool since construction.
+    # @!macro thread_pool_executor_attr_reader_largest_length
     attr_reader :largest_length
 
-    # The number of tasks that have been scheduled for execution on the pool since construction.
+    # @!macro thread_pool_executor_attr_reader_scheduled_task_count
     attr_reader :scheduled_task_count
 
-    # The number of tasks that have been completed by the pool since construction.
+    # @!macro thread_pool_executor_attr_reader_completed_task_count
     attr_reader :completed_task_count
 
-    # The number of seconds that a thread may be idle before being reclaimed.
+    # @!macro thread_pool_executor_attr_reader_idletime
     attr_reader :idletime
 
-    # 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 thread_pool_executor_attr_reader_max_queue
     attr_reader :max_queue
 
-    # Create a new thread pool.
-    #
-    # @param [Hash] opts the options which configure the thread pool
-    #
-    # @option opts [Integer] :max_threads (DEFAULT_MAX_POOL_SIZE) the maximum
-    #   number of threads to be created
-    # @option opts [Integer] :min_threads (DEFAULT_MIN_POOL_SIZE) the minimum
-    #   number of threads to be retained
-    # @option opts [Integer] :idletime (DEFAULT_THREAD_IDLETIMEOUT) the maximum
-    #   number of seconds a thread may be idle before being reclaimed
-    # @option opts [Integer] :max_queue (DEFAULT_MAX_QUEUE_SIZE) the maximum
-    #   number of tasks allowed in the work queue at any one time; a value of
-    #   zero means the queue may grow without bound
-    # @option opts [Symbol] :fallback_policy (:abort) the policy for handling new
-    #   tasks that are received when the queue size has reached
-    #   `max_queue` or the executor has shut down
-    #
-    # @raise [ArgumentError] if `:max_threads` is less than one
-    # @raise [ArgumentError] if `:min_threads` is less than zero
-    # @raise [ArgumentError] if `:fallback_policy` is not one of the values specified
-    #   in `FALLBACK_POLICIES`
-    #
-    # @see http://docs.oracle.com/javase/7/docs/api/java/util/concurrent/ThreadPoolExecutor.html
+    # @!macro thread_pool_executor_method_initialize
     def initialize(opts = {})
       super(opts)
     end
@@ -80,24 +55,17 @@ def can_overflow?
       synchronize { ns_limited_queue? }
     end
 
-    # The number of threads currently in the pool.
-    #
-    # @return [Integer] the length
+    # @!macro thread_pool_executor_attr_reader_length
     def length
       synchronize { @pool.length }
     end
 
-    # The number of tasks in the queue awaiting execution.
-    #
-    # @return [Integer] the queue_length
+    # @!macro thread_pool_executor_attr_reader_queue_length
     def queue_length
       synchronize { @queue.length }
     end
 
-    # 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] the remaining_capacity
+    # @!macro thread_pool_executor_attr_reader_remaining_capacity
     def remaining_capacity
       synchronize do
         if ns_limited_queue?
@@ -108,22 +76,22 @@ def remaining_capacity
       end
     end
 
-    # @api private
+    # @!visibility private
     def remove_busy_worker(worker)
       synchronize { ns_remove_busy_worker worker }
     end
 
-    # @api private
+    # @!visibility private
     def ready_worker(worker)
       synchronize { ns_ready_worker worker }
     end
 
-    # @api private
+    # @!visibility private
     def worker_not_old_enough(worker)
       synchronize { ns_worker_not_old_enough worker }
     end
 
-    # @api private
+    # @!visibility private
     def worker_died(worker)
       synchronize { ns_worker_died worker }
     end
@@ -303,6 +271,7 @@ def ns_prune_pool
       @next_gc_time = Concurrent.monotonic_time + @gc_interval
     end
 
+    # @!visibility private
     class Worker
       include Concern::Logging