Executors now follow new subclass declaration convention.

Author: jdantonio

lib/concurrent/executor/cached_thread_pool.rb

@@ -4,37 +4,41 @@ module Concurrent
 
   if Concurrent.on_jruby?
     require 'concurrent/executor/java_cached_thread_pool'
-    # @!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
-    #   pools are particularly suited to applications that perform a high volume of
-    #   short-lived tasks.
-    #
-    #   On creation a `CachedThreadPool` has zero running threads. New threads are
-    #   created on the pool as new operations are `#post`. The size of the pool
-    #   will grow until `#max_length` threads are in the pool or until the number
-    #   of threads exceeds the number of running and pending operations. When a new
-    #   operation is post to the pool the first available idle thread will be tasked
-    #   with the new operation.
-    #
-    #   Should a thread crash for any reason the thread will immediately be removed
-    #   from the pool. Similarly, threads which remain idle for an extended period
-    #   of time will be killed and reclaimed. Thus these thread pools are very
-    #   efficient at reclaiming unused resources.
-    #
-    #   The API and behavior of this class are based on Java's `CachedThreadPool`
-    #
-    #   @see Concurrent::RubyCachedThreadPool
-    #   @see Concurrent::JavaCachedThreadPool
-    #
-    # @!macro thread_pool_options
-    class CachedThreadPool < JavaCachedThreadPool
-    end
-  else
-    # @!macro cached_thread_pool
-    # @!macro thread_pool_options
-    class CachedThreadPool < RubyCachedThreadPool
-    end
+  end
+
+  CachedThreadPoolImplementation = case
+                                   when Concurrent.on_jruby?
+                                     JavaCachedThreadPool
+                                   else
+                                     RubyCachedThreadPool
+                                   end
+  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
+  #   pools are particularly suited to applications that perform a high volume of
+  #   short-lived tasks.
+  #
+  #   On creation a `CachedThreadPool` has zero running threads. New threads are
+  #   created on the pool as new operations are `#post`. The size of the pool
+  #   will grow until `#max_length` threads are in the pool or until the number
+  #   of threads exceeds the number of running and pending operations. When a new
+  #   operation is post to the pool the first available idle thread will be tasked
+  #   with the new operation.
+  #
+  #   Should a thread crash for any reason the thread will immediately be removed
+  #   from the pool. Similarly, threads which remain idle for an extended period
+  #   of time will be killed and reclaimed. Thus these thread pools are very
+  #   efficient at reclaiming unused resources.
+  #
+  #   The API and behavior of this class are based on Java's `CachedThreadPool`
+  #
+  #   @see Concurrent::RubyCachedThreadPool
+  #   @see Concurrent::JavaCachedThreadPool
+  #
+  # @!macro thread_pool_options
+  class CachedThreadPool < CachedThreadPoolImplementation
   end
 end

lib/concurrent/executor/fixed_thread_pool.rb

@@ -3,88 +3,90 @@
 module Concurrent
 
   if Concurrent.on_jruby?
-
     require 'concurrent/executor/java_fixed_thread_pool'
+  end
+
+  FixedThreadPoolImplementation = case
+                                     when Concurrent.on_jruby?
+                                       JavaFixedThreadPool
+                                     else
+                                       RubyFixedThreadPool
+                                     end
+  private_constant :FixedThreadPoolImplementation
 
-    # @!macro [attach] fixed_thread_pool
-    #
-    #   A thread pool with a set number of threads. The number of threads in the pool
-    #   is set on construction and remains constant. When all threads are busy new
-    #   tasks `#post` to the thread pool are enqueued until a thread becomes available.
-    #   Should a thread crash for any reason the thread will immediately be removed
-    #   from the pool and replaced.
-    #
-    #   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:
-    #
-    #   * `idletime`: The number of seconds that a thread may be idle before being reclaimed.
-    #   * `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`.
-    #   * `auto_terminate`: When true (default) an `at_exit` handler will be registered which
-    #     will stop the thread pool when the application exits. See below for more information
-    #     on shutting down thread pools.
-    #   * `fallback_policy`: The policy defining how rejected tasks are handled.
-    #
-    #   Three fallback policies are supported:
-    #
-    #   * `:abort`: Raise a `RejectedExecutionError` exception and discard the task.
-    #   * `:discard`: Discard the task and return false.
-    #   * `:caller_runs`: Execute the task on the calling thread.
-    #
-    #   **Shutting Down Thread Pools**
-    #
-    #   Killing a thread pool while tasks are still being processed, either by calling
-    #   the `#kill` method or at application exit, will have unpredictable results. There
-    #   is no way for the thread pool to know what resources are being used by the
-    #   in-progress tasks. When those tasks are killed the impact on those resources
-    #   cannot be predicted. The *best* practice is to explicitly shutdown all thread
-    #   pools using the provided methods:
-    #
-    #   * Call `#shutdown` to initiate an orderly termination of all in-progress tasks
-    #   * Call `#wait_for_termination` with an appropriate timeout interval an allow
-    #     the orderly shutdown to complete
-    #   * Call `#kill` *only when* the thread pool fails to shutdown in the allotted time
-    #
-    #   On some runtime platforms (most notably the JVM) the application will not
-    #   exit until all thread pools have been shutdown. To prevent applications from
-    #   "hanging" on exit all thread pools include an `at_exit` handler that will
-    #   stop the thread pool when the application exists. This handler uses a brute
-    #   force method to stop the pool and makes no guarantees regarding resources being
-    #   used by any tasks still running. Registration of this `at_exit` handler can be
-    #   prevented by setting the thread pool's constructor `:auto_terminate` option to
-    #   `false` when the thread pool is created. All thread pools support this option.
-    #
-    #   ```ruby
-    #   pool1 = Concurrent::FixedThreadPool.new(5) # an `at_exit` handler will be registered
-    #   pool2 = Concurrent::FixedThreadPool.new(5, auto_terminate: false) # prevent `at_exit` handler registration
-    #   ```
-    #
-    #   @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 `JavaThreadPoolExecutor`.
-    #     On all other platforms it will inherit from `RubyThreadPoolExecutor`.
-    #
-    #   @see Concurrent::RubyThreadPoolExecutor
-    #   @see Concurrent::JavaThreadPoolExecutor
-    #
-    #   @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
-    #   @see http://ruby-doc.org//core-2.2.0/Kernel.html#method-i-at_exit Kernel#at_exit
-    class FixedThreadPool < JavaFixedThreadPool
-    end
-  else
-    # @!macro fixed_thread_pool
-    # @!macro thread_pool_options
-    class FixedThreadPool < RubyFixedThreadPool
-    end
+  # @!macro [attach] fixed_thread_pool
+  #
+  #   A thread pool with a set number of threads. The number of threads in the pool
+  #   is set on construction and remains constant. When all threads are busy new
+  #   tasks `#post` to the thread pool are enqueued until a thread becomes available.
+  #   Should a thread crash for any reason the thread will immediately be removed
+  #   from the pool and replaced.
+  #
+  #   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:
+  #
+  #   * `idletime`: The number of seconds that a thread may be idle before being reclaimed.
+  #   * `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`.
+  #   * `auto_terminate`: When true (default) an `at_exit` handler will be registered which
+  #     will stop the thread pool when the application exits. See below for more information
+  #     on shutting down thread pools.
+  #   * `fallback_policy`: The policy defining how rejected tasks are handled.
+  #
+  #   Three fallback policies are supported:
+  #
+  #   * `:abort`: Raise a `RejectedExecutionError` exception and discard the task.
+  #   * `:discard`: Discard the task and return false.
+  #   * `:caller_runs`: Execute the task on the calling thread.
+  #
+  #   **Shutting Down Thread Pools**
+  #
+  #   Killing a thread pool while tasks are still being processed, either by calling
+  #   the `#kill` method or at application exit, will have unpredictable results. There
+  #   is no way for the thread pool to know what resources are being used by the
+  #   in-progress tasks. When those tasks are killed the impact on those resources
+  #   cannot be predicted. The *best* practice is to explicitly shutdown all thread
+  #   pools using the provided methods:
+  #
+  #   * Call `#shutdown` to initiate an orderly termination of all in-progress tasks
+  #   * Call `#wait_for_termination` with an appropriate timeout interval an allow
+  #     the orderly shutdown to complete
+  #   * Call `#kill` *only when* the thread pool fails to shutdown in the allotted time
+  #
+  #   On some runtime platforms (most notably the JVM) the application will not
+  #   exit until all thread pools have been shutdown. To prevent applications from
+  #   "hanging" on exit all thread pools include an `at_exit` handler that will
+  #   stop the thread pool when the application exists. This handler uses a brute
+  #   force method to stop the pool and makes no guarantees regarding resources being
+  #   used by any tasks still running. Registration of this `at_exit` handler can be
+  #   prevented by setting the thread pool's constructor `:auto_terminate` option to
+  #   `false` when the thread pool is created. All thread pools support this option.
+  #
+  #   ```ruby
+  #   pool1 = Concurrent::FixedThreadPool.new(5) # an `at_exit` handler will be registered
+  #   pool2 = Concurrent::FixedThreadPool.new(5, auto_terminate: false) # prevent `at_exit` handler registration
+  #   ```
+  #
+  #   @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
+  #   @see http://ruby-doc.org//core-2.2.0/Kernel.html#method-i-at_exit Kernel#at_exit
+  class FixedThreadPool < FixedThreadPoolImplementation
   end
 end

lib/concurrent/executor/ruby_thread_pool_executor.rb

@@ -128,6 +128,7 @@ def worker_died(worker)
 
     protected
 
+    # @!visibility private
     def ns_initialize(opts)
       @min_length      = opts.fetch(:min_threads, DEFAULT_MIN_POOL_SIZE).to_i
       @max_length      = opts.fetch(:max_threads, DEFAULT_MAX_POOL_SIZE).to_i
@@ -155,10 +156,12 @@ def ns_initialize(opts)
       @next_gc_time = Concurrent.monotonic_time + @gc_interval
     end
 
+    # @!visibility private
     def ns_limited_queue?
       @max_queue != 0
     end
 
+    # @!visibility private
     def ns_execute(*args, &task)
       if ns_assign_worker(*args, &task) || ns_enqueue(*args, &task)
         @scheduled_task_count += 1
@@ -172,6 +175,7 @@ def ns_execute(*args, &task)
 
     alias_method :execute, :ns_execute
 
+    # @!visibility private
     def ns_shutdown_execution
       if @pool.empty?
         # nothing to do
@@ -187,7 +191,7 @@ def ns_shutdown_execution
 
     alias_method :shutdown_execution, :ns_shutdown_execution
 
-    # @api private
+    # @!visibility private
     def ns_kill_execution
       # TODO log out unprocessed tasks in queue
       # TODO try to shutdown first?
@@ -200,6 +204,8 @@ def ns_kill_execution
 
     # tries to assign task to a worker, tries to get one from @ready or to create new one
     # @return [true, false] if task is assigned to a worker
+    #
+    # @!visibility private
     def ns_assign_worker(*args, &task)
       # keep growing if the pool is not at the minimum yet
       worker = (@ready.pop if @pool.size >= @min_length) || ns_add_busy_worker
@@ -213,6 +219,8 @@ def ns_assign_worker(*args, &task)
 
     # tries to enqueue task
     # @return [true, false] if enqueued
+    #
+    # @!visibility private
     def ns_enqueue(*args, &task)
       if !ns_limited_queue? || @queue.size < @max_queue
         @queue << [task, args]
@@ -222,6 +230,7 @@ def ns_enqueue(*args, &task)
       end
     end
 
+    # @!visibility private
     def ns_worker_died(worker)
       ns_remove_busy_worker worker
       replacement_worker = ns_add_busy_worker
@@ -230,6 +239,8 @@ def ns_worker_died(worker)
 
     # creates new worker which has to receive work to do after it's added
     # @return [nil, Worker] nil of max capacity is reached
+    #
+    # @!visibility private
     def ns_add_busy_worker
       return if @pool.size >= @max_length
 
@@ -239,6 +250,8 @@ def ns_add_busy_worker
     end
 
     # handle ready worker, giving it new job or assigning back to @ready
+    #
+    # @!visibility private
     def ns_ready_worker(worker, success = true)
       @completed_task_count += 1 if success
       task_and_args         = @queue.shift
@@ -255,20 +268,26 @@ def ns_ready_worker(worker, success = true)
     end
 
     # returns back worker to @ready which was not idle for enough time
+    #
+    # @!visibility private
     def ns_worker_not_old_enough(worker)
       # let's put workers coming from idle_test back to the start (as the oldest worker)
       @ready.unshift(worker)
       true
     end
 
     # removes a worker which is not in not tracked in @ready
+    #
+    # @!visibility private
     def ns_remove_busy_worker(worker)
       @pool.delete(worker)
       stopped_event.set if @pool.empty? && !running?
       true
     end
 
     # try oldest worker if it is idle for enough time, it's returned back at the start
+    #
+    # @!visibility private
     def ns_prune_pool
       return if @pool.size <= @min_length
 
@@ -345,5 +364,7 @@ def run_task(pool, task, args)
         throw :stop
       end
     end
+
+    private_constant :Worker
   end
 end