concurrent-ruby 0.6.0.pre.1 → 0.6.0.pre.2

data/lib/concurrent/executor/executor.rb

@@ -0,0 +1,222 @@
+require 'concurrent/atomic/event'
+
+module Concurrent
+
+  # An exception class raised when the maximum queue size is reached and the
+  # `overflow_policy` is set to `:abort`.
+  RejectedExecutionError = Class.new(StandardError)
+
+  module Executor
+
+    # 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
+    def post(*args, &task)
+      raise ArgumentError.new('no block given') unless block_given?
+      mutex.synchronize do
+        return false unless running?
+        execute(*args, &task)
+        true
+      end
+    end
+
+    # Submit a task to the executor for asynchronous processing.
+    #
+    # @param [Proc] task the asynchronous task to perform
+    #
+    # @return [self] returns itself
+    def <<(task)
+      post(&task)
+      self
+    end
+
+    # Is the executor running?
+    #
+    # @return [Boolean] `true` when running, `false` when shutting down or shutdown
+    def running?
+      ! stop_event.set?
+    end
+
+    # Is the executor shuttingdown?
+    #
+    # @return [Boolean] `true` when not running and not shutdown, else `false`
+    def shuttingdown?
+      ! (running? || shutdown?)
+    end
+
+    # Is the executor shutdown?
+    #
+    # @return [Boolean] `true` when shutdown, `false` when shutting down or running
+    def shutdown?
+      stopped_event.set?
+    end
+
+    # 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.
+    def shutdown
+      mutex.synchronize do
+        break unless running?
+        stop_event.set
+        shutdown_execution
+      end
+      true
+    end
+
+    # 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.
+    def kill
+      mutex.synchronize do
+        break if shutdown?
+        stop_event.set
+        kill_execution
+        stopped_event.set
+      end
+      true
+    end
+
+    # 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`
+    def wait_for_termination(timeout = nil)
+      stopped_event.wait(timeout)
+    end
+
+    protected
+
+    attr_reader :mutex, :stop_event, :stopped_event
+
+    def init_executor
+      @mutex = Mutex.new
+      @stop_event = Event.new
+      @stopped_event = Event.new
+    end
+
+    def execute(*args, &task)
+      raise NotImplementedError
+    end
+
+    def shutdown_execution
+      stopped_event.set
+    end
+
+    def kill_execution
+      # do nothing
+    end
+  end
+
+  if RUBY_PLATFORM == 'java'
+
+    module JavaExecutor
+
+      # 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
+      def post(*args)
+        raise ArgumentError.new('no block given') unless block_given?
+        if running?
+          @executor.submit{ yield(*args) }
+          true
+        else
+          false
+        end
+      rescue Java::JavaUtilConcurrent::RejectedExecutionException => ex
+        raise RejectedExecutionError
+      end
+
+      # Submit a task to the executor for asynchronous processing.
+      #
+      # @param [Proc] task the asynchronous task to perform
+      #
+      # @return [self] returns itself
+      def <<(task)
+        post(&task)
+        self
+      end
+
+      # Is the executor running?
+      #
+      # @return [Boolean] `true` when running, `false` when shutting down or shutdown
+      def running?
+        ! (shuttingdown? || shutdown?)
+      end
+
+      # Is the executor shuttingdown?
+      #
+      # @return [Boolean] `true` when not running and not shutdown, else `false`
+      def shuttingdown?
+        if @executor.respond_to? :isTerminating
+          @executor.isTerminating
+        else
+          false
+        end
+      end
+
+      # Is the executor shutdown?
+      #
+      # @return [Boolean] `true` when shutdown, `false` when shutting down or running
+      def shutdown?
+        @executor.isShutdown || @executor.isTerminated
+      end
+
+      # 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`
+      def wait_for_termination(timeout)
+        @executor.awaitTermination(1000 * timeout, java.util.concurrent.TimeUnit::MILLISECONDS)
+      end
+
+      # 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
+      # executor is not running.
+      def shutdown
+        @executor.shutdown
+        nil
+      end
+
+      # 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 executor is
+      # not running.
+      def kill
+        @executor.shutdownNow
+        nil
+      end
+
+      protected
+
+      def set_shutdown_hook
+        # without this the process may fail to exit
+        at_exit { self.kill }
+      end
+    end
+  end
+end

data/lib/concurrent/{fixed_thread_pool.rb → executor/fixed_thread_pool.rb}

@@ -1,21 +1,21 @@
-require 'concurrent/ruby_fixed_thread_pool'
+require 'concurrent/executor/ruby_fixed_thread_pool'
 
 module Concurrent
 
   if RUBY_PLATFORM == 'java'
-    require 'concurrent/java_fixed_thread_pool'
+    require 'concurrent/executor/java_fixed_thread_pool'
     # @!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.
+    #   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+
+    #   The API and behavior of this class are based on Java's `FixedThreadPool`
     #
-    #   @note When running on the JVM (JRuby) this class will inherit from +JavaFixedThreadPool+.
-    #     On all other platforms it will inherit from +RubyFixedThreadPool+.
+    #   @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
@@ -23,7 +23,6 @@ module Concurrent
     #   @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
-    #   @see http://stackoverflow.com/questions/17957382/fixedthreadpool-vs-fixedthreadpool-the-lesser-of-two-evils
     class FixedThreadPool < JavaFixedThreadPool
     end
   else

data/lib/concurrent/{immediate_executor.rb → executor/immediate_executor.rb}

@@ -1,14 +1,14 @@
 module Concurrent
   class ImmediateExecutor
 
-    def post(*args, &block)
+    def post(*args, &task)
       raise ArgumentError.new('no block given') unless block_given?
-      block.call(*args)
-      return true
+      task.call(*args)
+      true
     end
 
-    def <<(block)
-      post(&block)
+    def <<(task)
+      post(&task)
       self
     end
   end

data/lib/concurrent/executor/java_cached_thread_pool.rb

@@ -0,0 +1,31 @@
+if RUBY_PLATFORM == 'java'
+
+  require 'concurrent/executor/java_thread_pool_executor'
+
+  module Concurrent
+
+    # @!macro cached_thread_pool
+    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
+      #
+      # @raise [ArgumentError] if `overflow_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)
+        @max_queue = 0
+
+        raise ArgumentError.new("#{@overflow_policy} is not a valid overflow policy") unless OVERFLOW_POLICIES.keys.include?(@overflow_policy)
+
+        @executor = java.util.concurrent.Executors.newCachedThreadPool
+        @executor.setRejectedExecutionHandler(OVERFLOW_POLICIES[@overflow_policy].new)
+
+        set_shutdown_hook
+      end
+    end
+  end
+end

data/lib/concurrent/{java_fixed_thread_pool.rb → executor/java_fixed_thread_pool.rb}

@@ -1,6 +1,6 @@
 if RUBY_PLATFORM == 'java'
 
-  require 'concurrent/java_thread_pool_executor'
+  require 'concurrent/executor/java_thread_pool_executor'
 
   module Concurrent
 
@@ -10,10 +10,10 @@ if RUBY_PLATFORM == 'java'
       # 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] :overflow_policy (`:abort`) the overflow 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 `num_threads` is less than or equal to zero
+      # @raise [ArgumentError] if `overflow_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 = {})
@@ -23,14 +23,10 @@ if RUBY_PLATFORM == 'java'
         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)
 
-        @executor = java.util.concurrent.ThreadPoolExecutor.new(
-          num_threads, num_threads,
-          @max_queue, java.util.concurrent.TimeUnit::SECONDS,
-          java.util.concurrent.LinkedBlockingQueue.new,
-          OVERFLOW_POLICIES[@overflow_policy].new)
+        @executor = java.util.concurrent.Executors.newFixedThreadPool(num_threads)
+        @executor.setRejectedExecutionHandler(OVERFLOW_POLICIES[@overflow_policy].new)
 
-        # without this the process may fail to exit
-        at_exit { self.kill }
+        set_shutdown_hook
       end
     end
   end

data/lib/concurrent/executor/java_single_thread_executor.rb

@@ -0,0 +1,21 @@
+if RUBY_PLATFORM == 'java'
+  require_relative 'executor'
+
+  module Concurrent
+
+    # @!macro single_thread_executor
+    class JavaSingleThreadExecutor
+      include JavaExecutor
+
+      # Create a new thread pool.
+      #
+      # @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
+        set_shutdown_hook
+      end
+    end
+  end
+end

data/lib/concurrent/{java_thread_pool_executor.rb → executor/java_thread_pool_executor.rb}

@@ -1,26 +1,26 @@
 if RUBY_PLATFORM == 'java'
+  require_relative 'executor'
 
   module Concurrent
 
-    RejectedExecutionError = Class.new(StandardError) unless defined? RejectedExecutionError
-
     # @!macro thread_pool_executor
     class JavaThreadPoolExecutor
+      include JavaExecutor
 
-      # The maximum number of threads that will be created in the pool
-      # (unless overridden during construction).
+      # Default maximum number of threads that will be created in the pool.
       DEFAULT_MAX_POOL_SIZE = java.lang.Integer::MAX_VALUE # 2147483647
 
-      # The minimum number of threads that will be created in the pool
-      # (unless overridden during construction).
+      # Default minimum number of threads that will be retained in the pool.
       DEFAULT_MIN_POOL_SIZE = 0
 
+      # Default maximum number of tasks that may be added to the task queue.
       DEFAULT_MAX_QUEUE_SIZE = 0
 
-      # The maximum number of seconds a thread in the pool may remain idle before
-      # being reclaimed (unless overridden during construction).
+      # Default maximum number of seconds a thread in the pool may remain idle
+      # before being reclaimed.
       DEFAULT_THREAD_IDLETIMEOUT = 60
 
+      # The set of possible overflow policies that may be set at thread pool creation.
       OVERFLOW_POLICIES = {
         abort: java.util.concurrent.ThreadPoolExecutor::AbortPolicy,
         discard: java.util.concurrent.ThreadPoolExecutor::DiscardPolicy,
@@ -30,12 +30,37 @@ if RUBY_PLATFORM == 'java'
       # The maximum number of threads that may be created in the pool.
       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 `overflow_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
+      #
+      # @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 bounnd
+      # @option opts [Symbol] :overflow_policy (:abort) the policy for handling new
+      #   tasks that are received when the queue size has reached `max_queue`
+      #
+      # @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`
+      #
       # @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
@@ -61,43 +86,70 @@ if RUBY_PLATFORM == 'java'
           idletime, java.util.concurrent.TimeUnit::SECONDS,
           queue, OVERFLOW_POLICIES[@overflow_policy].new)
 
-        # without this the process may fail to exit
-        at_exit { self.kill }
+        set_shutdown_hook
       end
 
+      # The minimum number of threads that may be retained in the pool.
+      #
+      # @return [Integer] the 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
       def max_length
         @executor.getMaximumPoolSize
       end
 
+      # The number of threads currently in the pool.
+      #
+      # @return [Integer] the length
       def length
         @executor.getPoolSize
       end
       alias_method :current_length, :length
 
+      # The largest number of threads that have been created in the pool since construction.
+      #
+      # @return [Integer] the 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
       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
       def completed_task_count
         @executor.getCompletedTaskCount
       end
 
+      # The number of seconds that a thread may be idle before being reclaimed.
+      #
+      # @return [Integer] the 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
       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
       def remaining_capacity
         @max_queue == 0 ? -1 : @executor.getQueue.remainingCapacity
       end
@@ -113,81 +165,18 @@ if RUBY_PLATFORM == 'java'
 
       # Is the thread pool running?
       #
-      # @return [Boolean] +true+ when running, +false+ when shutting down or shutdown
+      # @return [Boolean] `true` when running, `false` when shutting down or shutdown
       def running?
-        ! (@executor.isShutdown || @executor.isTerminated || @executor.isTerminating)
-      end
-
-      # Is the thread pool shutdown?
-      #
-      # @return [Boolean] +true+ when shutdown, +false+ when shutting down or running
-      def shutdown?
-        @executor.isShutdown
-      end
-
-      # Block until thread pool 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+
-      def wait_for_termination(timeout)
-        @executor.awaitTermination(timeout.to_i, java.util.concurrent.TimeUnit::SECONDS)
-      end
-
-      # Submit a task to the thread pool 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 thread pool
-      #   is not running
-      #
-      # @raise [ArgumentError] if no task is given
-      def post(*args)
-        raise ArgumentError.new('no block given') unless block_given?
-        if running?
-          @executor.submit{ yield(*args) }
-          true
-        else
-          false
-        end
-      rescue Java::JavaUtilConcurrent::RejectedExecutionException => ex
-        raise RejectedExecutionError
-      end
-
-      # Submit a task to the thread pool for asynchronous processing.
-      #
-      # @param [Proc] task the asynchronous task to perform
-      #
-      # @return [self] returns itself
-      def <<(task)
-        @executor.submit(&task)
-      rescue Java::JavaUtilConcurrent::RejectedExecutionException => ex
-        raise RejectedExecutionError
+        super && ! @executor.isTerminating
       end
 
       # 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.
       def shutdown
-        @executor.shutdown
-        @executor.getQueue.clear
-        return nil
-      end
-
-      # 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.
-      def kill
-        @executor.shutdownNow
+        super
         @executor.getQueue.clear
-        return nil
+        nil
       end
     end
   end