Rename 'overflow_policy' to 'fallback_policy'.

This reflects its broader scope (e.g. deciding how to handle tasks after shutdown).

Author: rkday

lib/concurrent/executor/executor.rb

@@ -5,10 +5,11 @@
 module Concurrent
 
   module Executor
-    # The policy defining how rejected tasks (tasks received once the queue size reaches
-    # the configured `max_queue`) are handled. Must be one of the values specified in
-    # `OVERFLOW_POLICIES`.
-    attr_reader :overflow_policy
+    # The policy defining how rejected tasks (tasks received once the
+    # queue size reaches the configured `max_queue`, or after the
+    # executor has shut down) are handled. Must be one of the values
+    # specified in `FALLBACK_POLICIES`.
+    attr_reader :fallback_policy
 
     # @!macro [attach] executor_module_method_can_overflow_question
     #
@@ -21,14 +22,14 @@ def can_overflow?
       false
     end
 
-    # Handler which executes the `overflow_policy` once the queue size
+    # Handler which executes the `fallback_policy` once the queue size
     # reaches `max_queue`.
     #
     # @param [Array] args the arguments to the task which is being handled.
     #
     # @!visibility private
-    def handle_overflow(*args)
-      case @overflow_policy
+    def handle_fallback(*args)
+      case @fallback_policy
       when :abort
         raise RejectedExecutionError
       when :discard
@@ -42,7 +43,7 @@ def handle_overflow(*args)
         end
         true
       else
-        fail "Unknown overflow policy #{@overflow_policy}"
+        fail "Unknown fallback policy #{@fallback_policy}"
       end
     end
 
@@ -92,8 +93,8 @@ module RubyExecutor
     include Executor
     include Logging
 
-    # The set of possible overflow policies that may be set at thread pool creation.
-    OVERFLOW_POLICIES          = [:abort, :discard, :caller_runs]
+    # The set of possible fallback policies that may be set at thread pool creation.
+    FALLBACK_POLICIES          = [:abort, :discard, :caller_runs]
 
     # @!macro [attach] executor_method_post
     #
@@ -111,7 +112,7 @@ def post(*args, &task)
       raise ArgumentError.new('no block given') unless block_given?
       mutex.synchronize do
         # If the executor is shut down, reject this task
-        return handle_overflow(*args, &task) unless running?
+        return handle_fallback(*args, &task) unless running?
         execute(*args, &task)
         true
       end
@@ -243,8 +244,8 @@ module JavaExecutor
       include Executor
       java_import 'java.lang.Runnable'
 
-      # The set of possible overflow policies that may be set at thread pool creation.
-      OVERFLOW_POLICIES = {
+      # The set of possible fallback policies that may be set at thread pool creation.
+      FALLBACK_POLICIES = {
         abort: java.util.concurrent.ThreadPoolExecutor::AbortPolicy,
         discard: java.util.concurrent.ThreadPoolExecutor::DiscardPolicy,
         caller_runs: java.util.concurrent.ThreadPoolExecutor::CallerRunsPolicy
@@ -253,7 +254,7 @@ module JavaExecutor
       # @!macro executor_method_post
       def post(*args)
         raise ArgumentError.new('no block given') unless block_given?
-        return handle_overflow(*args, &task) unless running?
+        return handle_fallback(*args, &task) unless running?
         executor_submit = @executor.java_method(:submit, [Runnable.java_class])
         executor_submit.call { yield(*args) }
         true

lib/concurrent/executor/java_cached_thread_pool.rb

@@ -10,19 +10,19 @@ class JavaCachedThreadPool < JavaThreadPoolExecutor
       # Create a new thread pool.
       #
       # @param [Hash] opts the options defining pool behavior.
-      # @option opts [Symbol] :overflow_policy (`:abort`) the overflow policy
+      # @option opts [Symbol] :fallback_policy (`:abort`) the fallback policy
       #
-      # @raise [ArgumentError] if `overflow_policy` is not a known 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--
       def initialize(opts = {})
-        @overflow_policy = opts.fetch(:overflow_policy, :abort)
+        @fallback_policy = opts.fetch(:fallback_policy, opts.fetch(:overflow_policy, :abort))
         @max_queue = 0
 
-        raise ArgumentError.new("#{@overflow_policy} is not a valid overflow policy") unless OVERFLOW_POLICIES.keys.include?(@overflow_policy)
+        raise ArgumentError.new("#{@fallback_policy} is not a valid fallback policy") unless FALLBACK_POLICIES.keys.include?(@fallback_policy)
 
         @executor = java.util.concurrent.Executors.newCachedThreadPool
-        @executor.setRejectedExecutionHandler(OVERFLOW_POLICIES[@overflow_policy].new)
+        @executor.setRejectedExecutionHandler(FALLBACK_POLICIES[@fallback_policy].new)
 
         set_shutdown_hook
       end

lib/concurrent/executor/java_fixed_thread_pool.rb

@@ -10,10 +10,10 @@ class JavaFixedThreadPool < JavaThreadPoolExecutor
       # Create a new thread pool.
       #
       # @param [Hash] opts the options defining pool behavior.
-      # @option opts [Symbol] :overflow_policy (`:abort`) the overflow policy
+      # @option opts [Symbol] :fallback_policy (`:abort`) the fallback policy
       #
       # @raise [ArgumentError] if `num_threads` is less than or equal to zero
-      # @raise [ArgumentError] if `overflow_policy` is not a known 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#newFixedThreadPool-int-
       def initialize(num_threads, opts = {})
@@ -25,14 +25,14 @@ def initialize(num_threads, opts = {})
         super(opts)
 
 
-        #@overflow_policy = opts.fetch(:overflow_policy, :abort)
+        #@fallback_policy = opts.fetch(:fallback_policy, :abort)
         #@max_queue = 0
         #
         #raise ArgumentError.new('number of threads must be greater than zero') if num_threads < 1
-        #raise ArgumentError.new("#{@overflow_policy} is not a valid overflow policy") unless OVERFLOW_POLICIES.keys.include?(@overflow_policy)
+        #raise ArgumentError.new("#{@fallback_policy} is not a valid fallback policy") unless FALLBACK_POLICIES.keys.include?(@fallback_policy)
         #
         #@executor = java.util.concurrent.Executors.newFixedThreadPool(num_threads)
-        #@executor.setRejectedExecutionHandler(OVERFLOW_POLICIES[@overflow_policy].new)
+        #@executor.setRejectedExecutionHandler(FALLBACK_POLICIES[@FALLBACK_policy].new)
 
         set_shutdown_hook
       end

lib/concurrent/executor/java_single_thread_executor.rb

@@ -10,16 +10,17 @@ class JavaSingleThreadExecutor
 
       # Create a new thread pool.
       #
-      # @option opts [Symbol] :overflow_policy (:discard) the policy for handling new
-      #   tasks that are received when the queue size has reached `max_queue`
+      # @option opts [Symbol] :fallback_policy (:discard) the policy
+      #   for handling new tasks that are received when the queue size
+      #   has reached `max_queue` or after the executor has shut down
       #
       # @see http://docs.oracle.com/javase/tutorial/essential/concurrency/pools.html
       # @see http://docs.oracle.com/javase/7/docs/api/java/util/concurrent/Executors.html
       # @see http://docs.oracle.com/javase/8/docs/api/java/util/concurrent/ExecutorService.html
       def initialize(opts = {})
         @executor = java.util.concurrent.Executors.newSingleThreadExecutor
-        @overflow_policy = opts.fetch(:overflow_policy, :discard)
-        raise ArgumentError.new("#{@overflow_policy} is not a valid overflow policy") unless OVERFLOW_POLICIES.keys.include?(@overflow_policy)
+        @fallback_policy = opts.fetch(:fallback_policy, :discard)
+        raise ArgumentError.new("#{@fallback_policy} is not a valid fallback policy") unless FALLBACK_POLICIES.keys.include?(@fallback_policy)
         set_shutdown_hook
       end
     end

lib/concurrent/executor/java_thread_pool_executor.rb

@@ -25,14 +25,9 @@ class JavaThreadPoolExecutor
 
       # 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 `overflow_policy`.
+      # accordance with the configured `fallback_policy`.
       attr_reader :max_queue
 
-      # The policy defining how rejected tasks (tasks received once the queue size reaches
-      # the configured `max_queue`) are handled. Must be one of the values specified in
-      # `OVERFLOW_POLICIES`.
-      attr_reader :overflow_policy
-
       # Create a new thread pool.
       #
       # @param [Hash] opts the options which configure the thread pool
@@ -45,27 +40,28 @@ class JavaThreadPoolExecutor
       #   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 bounnd
-      # @option opts [Symbol] :overflow_policy (:abort) the policy for handling new
-      #   tasks that are received when the queue size has reached `max_queue`
+      #   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 `:overflow_policy` is not one of the values specified
-      #   in `OVERFLOW_POLICIES`
+      # @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
       def 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
         idletime = opts.fetch(:idletime, DEFAULT_THREAD_IDLETIMEOUT).to_i
         @max_queue = opts.fetch(:max_queue, DEFAULT_MAX_QUEUE_SIZE).to_i
-        @overflow_policy = opts.fetch(:overflow_policy, :abort)
+        @fallback_policy = opts.fetch(:fallback_policy, opts.fetch(:overflow_policy, :abort))
 
         raise ArgumentError.new('max_threads must be greater than zero') if max_length <= 0
         raise ArgumentError.new('min_threads cannot be less than zero') if min_length < 0
         raise ArgumentError.new('min_threads cannot be more than max_threads') if min_length > max_length
-        raise ArgumentError.new("#{@overflow_policy} is not a valid overflow policy") unless OVERFLOW_POLICIES.keys.include?(@overflow_policy)
+        raise ArgumentError.new("#{fallback_policy} is not a valid fallback policy") unless FALLBACK_POLICIES.include?(@fallback_policy)
 
         if @max_queue == 0
           queue = java.util.concurrent.LinkedBlockingQueue.new
@@ -76,7 +72,7 @@ def initialize(opts = {})
         @executor = java.util.concurrent.ThreadPoolExecutor.new(
           min_length, max_length,
           idletime, java.util.concurrent.TimeUnit::SECONDS,
-          queue, OVERFLOW_POLICIES[@overflow_policy].new)
+          queue, FALLBACK_POLICIES[@fallback_policy].new)
 
         set_shutdown_hook
       end

lib/concurrent/executor/ruby_cached_thread_pool.rb

@@ -8,18 +8,18 @@ class RubyCachedThreadPool < RubyThreadPoolExecutor
     # Create a new thread pool.
     #
     # @param [Hash] opts the options defining pool behavior.
-    #   number of seconds a thread may be idle before it is reclaimed
+    # @option opts [Symbol] :fallback_policy (`:abort`) the fallback policy
     #
-    # @raise [ArgumentError] if `overflow_policy` is not a known policy
+    # @raise [ArgumentError] if `fallback_policy` is not a known policy
     def initialize(opts = {})
-      overflow_policy = opts.fetch(:overflow_policy, :abort)
+      fallback_policy = opts.fetch(:fallback_policy, opts.fetch(:overflow_policy, :abort))
 
-      raise ArgumentError.new("#{overflow_policy} is not a valid overflow policy") unless OVERFLOW_POLICIES.include?(overflow_policy)
+      raise ArgumentError.new("#{fallback_policy} is not a valid fallback policy") unless FALLBACK_POLICIES.include?(fallback_policy)
 
       opts = opts.merge(
         min_threads: 0,
         max_threads: DEFAULT_MAX_POOL_SIZE,
-        overflow_policy: overflow_policy,
+        fallback_policy: fallback_policy,
         max_queue: DEFAULT_MAX_QUEUE_SIZE,
         idletime: DEFAULT_THREAD_IDLETIMEOUT
       )

lib/concurrent/executor/ruby_fixed_thread_pool.rb

@@ -9,20 +9,20 @@ class RubyFixedThreadPool < RubyThreadPoolExecutor
     #
     # @param [Integer] num_threads the number of threads to allocate
     # @param [Hash] opts the options defining pool behavior.
-    # @option opts [Symbol] :overflow_policy (`:abort`) the overflow policy
+    # @option opts [Symbol] :fallback_policy (`:abort`) the fallback policy
     #
     # @raise [ArgumentError] if `num_threads` is less than or equal to zero
-    # @raise [ArgumentError] if `overflow_policy` is not a known policy
+    # @raise [ArgumentError] if `fallback_policy` is not a known policy
     def initialize(num_threads, opts = {})
-      overflow_policy = opts.fetch(:overflow_policy, :abort)
+      fallback_policy = opts.fetch(:fallback_policy, opts.fetch(:overflow_policy, :abort))
 
       raise ArgumentError.new('number of threads must be greater than zero') if num_threads < 1
-      raise ArgumentError.new("#{overflow_policy} is not a valid overflow policy") unless OVERFLOW_POLICIES.include?(overflow_policy)
+      raise ArgumentError.new("#{fallback_policy} is not a valid fallback policy") unless FALLBACK_POLICIES.include?(fallback_policy)
 
       opts = {
         min_threads: num_threads,
         max_threads: num_threads,
-        overflow_policy: overflow_policy,
+        fallback_policy: fallback_policy,
         max_queue: DEFAULT_MAX_QUEUE_SIZE,
         idletime: DEFAULT_THREAD_IDLETIMEOUT,
       }.merge(opts)

lib/concurrent/executor/ruby_single_thread_executor.rb

@@ -9,17 +9,18 @@ class RubySingleThreadExecutor
 
     # Create a new thread pool.
     #
-    # @option opts [Symbol] :overflow_policy (:discard) the policy for handling new
-    #   tasks that are received when the queue size has reached `max_queue`
+    # @option opts [Symbol] :fallback_policy (:discard) the policy for
+    #   handling new tasks that are received when the queue size has
+    #   reached `max_queue` or after the executor has shut down
     #
     # @see http://docs.oracle.com/javase/tutorial/essential/concurrency/pools.html
     # @see http://docs.oracle.com/javase/7/docs/api/java/util/concurrent/Executors.html
     # @see http://docs.oracle.com/javase/8/docs/api/java/util/concurrent/ExecutorService.html
     def initialize(opts = {})
       @queue = Queue.new
       @thread = nil
-      @overflow_policy = opts.fetch(:overflow_policy, :discard)
-      raise ArgumentError.new("#{@overflow_policy} is not a valid overflow policy") unless OVERFLOW_POLICIES.include?(@overflow_policy)
+      @fallback_policy = opts.fetch(:fallback_policy, :discard)
+      raise ArgumentError.new("#{@fallback_policy} is not a valid fallback policy") unless FALLBACK_POLICIES.include?(@fallback_policy)
       init_executor
     end
 

lib/concurrent/executor/ruby_thread_pool_executor.rb

@@ -43,7 +43,7 @@ class RubyThreadPoolExecutor
 
     # 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 `overflow_policy`.
+    # accordance with the configured `fallback_policy`.
     attr_reader :max_queue
 
     # Create a new thread pool.
@@ -58,26 +58,27 @@ class RubyThreadPoolExecutor
     #   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 bounnd
-    # @option opts [Symbol] :overflow_policy (:abort) the policy for handling new
-    #   tasks that are received when the queue size has reached `max_queue`
+    #   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 `:overflow_policy` is not one of the values specified
-    #   in `OVERFLOW_POLICIES`
+    # @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
     def 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
       @idletime        = opts.fetch(:idletime, DEFAULT_THREAD_IDLETIMEOUT).to_i
       @max_queue       = opts.fetch(:max_queue, DEFAULT_MAX_QUEUE_SIZE).to_i
-      @overflow_policy = opts.fetch(:overflow_policy, :abort)
+      @fallback_policy = opts.fetch(:fallback_policy, opts.fetch(:overflow_policy, :abort))
 
       raise ArgumentError.new('max_threads must be greater than zero') if @max_length <= 0
       raise ArgumentError.new('min_threads cannot be less than zero') if @min_length < 0
-      raise ArgumentError.new("#{overflow_policy} is not a valid overflow policy") unless OVERFLOW_POLICIES.include?(@overflow_policy)
+      raise ArgumentError.new("#{fallback_policy} is not a valid fallback policy") unless FALLBACK_POLICIES.include?(@fallback_policy)
       raise ArgumentError.new('min_threads cannot be more than max_threads') if min_length > max_length
 
       init_executor
@@ -161,7 +162,7 @@ def execute(*args, &task)
         @scheduled_task_count += 1
         @queue << [args, task]
       else
-        handle_overflow(*args, &task) if @max_queue != 0 && @queue.length >= @max_queue
+        handle_fallback(*args, &task) if @max_queue != 0 && @queue.length >= @max_queue
       end
     end
 

lib/concurrent/executor/thread_pool_executor.rb

@@ -40,13 +40,13 @@ module Concurrent
     #   * `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 `overflow_policy`.
-    #   * `overflow_policy`: The policy defining how rejected tasks are handled.    #
+    #     rejected in accordance with the configured `fallback_policy`.
+    #   * `fallback_policy`: The policy defining how rejected tasks are handled.    #
     #
-    #   Three overflow policies are supported:
+    #   Three fallback policies are supported:
     #
     #   * `:abort`: Raise a `RejectedExecutionError` exception and discard the task.
-    #   * `:discard`: Silently discard the task and return `nil` as the task result.
+    #   * `:discard`: Discard the task and return false.
     #   * `:caller_runs`: Execute the task on the calling thread.
     #
     #   {include:file:doc/thread_pools.md}