o-concurrent-ruby 1.1.11

data/lib/concurrent-ruby/concurrent/executor/abstract_executor_service.rb

@@ -0,0 +1,131 @@
+require 'concurrent/errors'
+require 'concurrent/concern/deprecation'
+require 'concurrent/executor/executor_service'
+require 'concurrent/synchronization'
+
+module Concurrent
+
+  # @!macro abstract_executor_service_public_api
+  # @!visibility private
+  class AbstractExecutorService < Synchronization::LockableObject
+    include ExecutorService
+    include Concern::Deprecation
+
+    # The set of possible fallback policies that may be set at thread pool creation.
+    FALLBACK_POLICIES = [:abort, :discard, :caller_runs].freeze
+
+    # @!macro executor_service_attr_reader_fallback_policy
+    attr_reader :fallback_policy
+
+    attr_reader :name
+
+    # Create a new thread pool.
+    def initialize(opts = {}, &block)
+      super(&nil)
+      synchronize do
+        @auto_terminate = opts.fetch(:auto_terminate, true)
+        @name = opts.fetch(:name) if opts.key?(:name)
+        ns_initialize(opts, &block)
+      end
+    end
+
+    def to_s
+      name ? "#{super[0..-2]} name: #{name}>" : super
+    end
+
+    # @!macro executor_service_method_shutdown
+    def shutdown
+      raise NotImplementedError
+    end
+
+    # @!macro executor_service_method_kill
+    def kill
+      raise NotImplementedError
+    end
+
+    # @!macro executor_service_method_wait_for_termination
+    def wait_for_termination(timeout = nil)
+      raise NotImplementedError
+    end
+
+    # @!macro executor_service_method_running_question
+    def running?
+      synchronize { ns_running? }
+    end
+
+    # @!macro executor_service_method_shuttingdown_question
+    def shuttingdown?
+      synchronize { ns_shuttingdown? }
+    end
+
+    # @!macro executor_service_method_shutdown_question
+    def shutdown?
+      synchronize { ns_shutdown? }
+    end
+
+    # @!macro executor_service_method_auto_terminate_question
+    def auto_terminate?
+      synchronize { @auto_terminate }
+    end
+
+    # @!macro executor_service_method_auto_terminate_setter
+    def auto_terminate=(value)
+      deprecated "Method #auto_terminate= has no effect. Set :auto_terminate option when executor is initialized."
+    end
+
+    private
+
+    # Returns an action which executes the `fallback_policy` once the queue
+    # size reaches `max_queue`. The reason for the indirection of an action
+    # is so that the work can be deferred outside of synchronization.
+    #
+    # @param [Array] args the arguments to the task which is being handled.
+    #
+    # @!visibility private
+    def fallback_action(*args)
+      case fallback_policy
+      when :abort
+        lambda { raise RejectedExecutionError }
+      when :discard
+        lambda { false }
+      when :caller_runs
+        lambda {
+          begin
+            yield(*args)
+          rescue => ex
+            # let it fail
+            log DEBUG, ex
+          end
+          true
+        }
+      else
+        lambda { fail "Unknown fallback policy #{fallback_policy}" }
+      end
+    end
+
+    def ns_execute(*args, &task)
+      raise NotImplementedError
+    end
+
+    # @!macro executor_service_method_ns_shutdown_execution
+    #
+    #   Callback method called when an orderly shutdown has completed.
+    #   The default behavior is to signal all waiting threads.
+    def ns_shutdown_execution
+      # do nothing
+    end
+
+    # @!macro executor_service_method_ns_kill_execution
+    #
+    #   Callback method called when the executor has been killed.
+    #   The default behavior is to do nothing.
+    def ns_kill_execution
+      # do nothing
+    end
+
+    def ns_auto_terminate?
+      @auto_terminate
+    end
+
+  end
+end

data/lib/concurrent-ruby/concurrent/executor/cached_thread_pool.rb

@@ -0,0 +1,62 @@
+require 'concurrent/utility/engine'
+require 'concurrent/executor/thread_pool_executor'
+
+module Concurrent
+
+  # 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`
+  #
+  # @!macro thread_pool_options
+  class CachedThreadPool < ThreadPoolExecutor
+
+    # @!macro 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--
+    def initialize(opts = {})
+      defaults  = { idletime: DEFAULT_THREAD_IDLETIMEOUT }
+      overrides = { min_threads: 0,
+                    max_threads: DEFAULT_MAX_POOL_SIZE,
+                    max_queue:   DEFAULT_MAX_QUEUE_SIZE }
+      super(defaults.merge(opts).merge(overrides))
+    end
+
+    private
+
+    # @!macro cached_thread_pool_method_initialize
+    # @!visibility private
+    def ns_initialize(opts)
+      super(opts)
+      if Concurrent.on_jruby?
+        @max_queue          = 0
+        @executor           = java.util.concurrent.Executors.newCachedThreadPool(
+            DaemonThreadFactory.new(ns_auto_terminate?))
+        @executor.setRejectedExecutionHandler(FALLBACK_POLICY_CLASSES[@fallback_policy].new)
+        @executor.setKeepAliveTime(opts.fetch(:idletime, DEFAULT_THREAD_IDLETIMEOUT), java.util.concurrent.TimeUnit::SECONDS)
+      end
+    end
+  end
+end

data/lib/concurrent-ruby/concurrent/executor/executor_service.rb

@@ -0,0 +1,185 @@
+require 'concurrent/concern/logging'
+
+module Concurrent
+
+  ###################################################################
+
+  # @!macro 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_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_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_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_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_attr_reader_fallback_policy
+  #   @return [Symbol] The fallback policy in effect. Either `:abort`, `:discard`, or `:caller_runs`.
+
+  # @!macro 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 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 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 executor_service_method_running_question
+  #
+  #   Is the executor running?
+  #
+  #   @return [Boolean] `true` when running, `false` when shutting down or shutdown
+
+  # @!macro executor_service_method_shuttingdown_question
+  #
+  #   Is the executor shuttingdown?
+  #
+  #   @return [Boolean] `true` when not running and not shutdown, else `false`
+
+  # @!macro executor_service_method_shutdown_question
+  #
+  #   Is the executor shutdown?
+  #
+  #   @return [Boolean] `true` when shutdown, `false` when shutting down or running
+
+  # @!macro 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 executor_service_method_auto_terminate_setter
+  #
+  #
+  #   Set the auto-terminate behavior for this executor.
+  #   @deprecated Has no effect
+  #   @param [Boolean] value The new auto-terminate value to set for this executor.
+  #   @return [Boolean] `true` when auto-termination is enabled else `false`.
+
+  ###################################################################
+
+  # @!macro 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 executor_service_public_api
+  # @!visibility private
+  module ExecutorService
+    include Concern::Logging
+
+    # @!macro executor_service_method_post
+    def post(*args, &task)
+      raise NotImplementedError
+    end
+
+    # @!macro executor_service_method_left_shift
+    def <<(task)
+      post(&task)
+      self
+    end
+
+    # @!macro executor_service_method_can_overflow_question
+    #
+    # @note Always returns `false`
+    def can_overflow?
+      false
+    end
+
+    # @!macro executor_service_method_serialized_question
+    #
+    # @note Always returns `false`
+    def serialized?
+      false
+    end
+  end
+end

data/lib/concurrent-ruby/concurrent/executor/fixed_thread_pool.rb

@@ -0,0 +1,220 @@
+require 'concurrent/utility/engine'
+require 'concurrent/executor/thread_pool_executor'
+
+module Concurrent
+
+  # @!macro thread_pool_executor_constant_default_max_pool_size
+  #   Default maximum number of threads that will be created in the pool.
+
+  # @!macro thread_pool_executor_constant_default_min_pool_size
+  #   Default minimum number of threads that will be retained in the pool.
+
+  # @!macro thread_pool_executor_constant_default_max_queue_size
+  #   Default maximum number of tasks that may be added to the task queue.
+
+  # @!macro thread_pool_executor_constant_default_thread_timeout
+  #   Default maximum number of seconds a thread in the pool may remain idle
+  #   before being reclaimed.
+
+  # @!macro thread_pool_executor_constant_default_synchronous
+  #   Default value of the :synchronous option.
+
+  # @!macro 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 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 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 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 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 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 thread_pool_executor_attr_reader_synchronous
+  #   Whether or not a value of 0 for :max_queue option means the queue must perform direct hand-off or rather unbounded queue.
+  #   @return [true, false]
+
+  # @!macro 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 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 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 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 thread_pool_executor_method_prune_pool
+  #   Prune the thread pool of unneeded threads
+  #
+  #   What is being pruned is controlled by the min_threads and idletime
+  #   parameters passed at pool creation time
+  #
+  #   This is a no-op on some pool implementation (e.g. the Java one).  The Ruby
+  #   pool will auto-prune each time a new job is posted. You will need to call
+  #   this method explicitely in case your application post jobs in bursts (a
+  #   lot of jobs and then nothing for long periods)
+
+  # @!macro thread_pool_executor_public_api
+  #
+  #   @!macro abstract_executor_service_public_api
+  #
+  #   @!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 prune_pool
+  #     @!macro thread_pool_executor_method_prune_pool
+
+
+
+
+  # @!macro 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.
+  #   * `name`: The name of the executor (optional). Printed in the executor's `#to_s` output and
+  #     a `<name>-worker-<id>` name is given to its threads if supported by used Ruby
+  #     implementation. `<id>` is uniq for each thread.
+  #   * `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` and no new threads can be created,
+  #     subsequent tasks will be rejected in accordance with the configured `fallback_policy`.
+  #   * `auto_terminate`: When true (default), the threads started will be marked as daemon.
+  #   * `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 threads can be marked as daemon according to the
+  #   `:auto_terminate` option.
+  #
+  #   ```ruby
+  #   pool1 = Concurrent::FixedThreadPool.new(5) # threads will be marked as daemon
+  #   pool2 = Concurrent::FixedThreadPool.new(5, auto_terminate: false) # mark threads as non-daemon
+  #   ```
+  #
+  #   @note Failure to properly shutdown a thread pool can lead to unpredictable results.
+  #     Please read *Shutting Down Thread Pools* for more information.
+  #
+  #   @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 https://docs.oracle.com/javase/8/docs/api/java/lang/Thread.html#setDaemon-boolean-
+
+
+
+
+
+  # @!macro fixed_thread_pool
+  #
+  #   A thread pool that reuses a fixed number of threads operating off an unbounded queue.
+  #   At any point, at most `num_threads` will be active processing tasks. 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`
+  #
+  # @!macro thread_pool_options
+  class FixedThreadPool < ThreadPoolExecutor
+
+    # @!macro 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-
+    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,
+                    idletime:    DEFAULT_THREAD_IDLETIMEOUT }
+      overrides = { min_threads: num_threads,
+                    max_threads: num_threads }
+      super(defaults.merge(opts).merge(overrides))
+    end
+  end
+end

data/lib/concurrent-ruby/concurrent/executor/immediate_executor.rb

@@ -0,0 +1,66 @@
+require 'concurrent/atomic/event'
+require 'concurrent/executor/abstract_executor_service'
+require 'concurrent/executor/serial_executor_service'
+
+module Concurrent
+
+  # An executor service which runs all operations on the current thread,
+  # blocking as necessary. Operations are performed in the order they are
+  # received and no two operations can be performed simultaneously.
+  #
+  # This executor service exists mainly for testing an debugging. When used
+  # it immediately runs every `#post` operation on the current thread, blocking
+  # that thread until the operation is complete. This can be very beneficial
+  # during testing because it makes all operations deterministic.
+  #
+  # @note Intended for use primarily in testing and debugging.
+  class ImmediateExecutor < AbstractExecutorService
+    include SerialExecutorService
+
+    # Creates a new executor
+    def initialize
+      @stopped = Concurrent::Event.new
+    end
+
+    # @!macro executor_service_method_post
+    def post(*args, &task)
+      raise ArgumentError.new('no block given') unless block_given?
+      return false unless running?
+      task.call(*args)
+      true
+    end
+
+    # @!macro executor_service_method_left_shift
+    def <<(task)
+      post(&task)
+      self
+    end
+
+    # @!macro executor_service_method_running_question
+    def running?
+      ! shutdown?
+    end
+
+    # @!macro executor_service_method_shuttingdown_question
+    def shuttingdown?
+      false
+    end
+
+    # @!macro executor_service_method_shutdown_question
+    def shutdown?
+      @stopped.set?
+    end
+
+    # @!macro executor_service_method_shutdown
+    def shutdown
+      @stopped.set
+      true
+    end
+    alias_method :kill, :shutdown
+
+    # @!macro executor_service_method_wait_for_termination
+    def wait_for_termination(timeout = nil)
+      @stopped.wait(timeout)
+    end
+  end
+end