concurrent-ruby 0.7.0-java

data/lib/concurrent/errors.rb

@@ -0,0 +1,30 @@
+module Concurrent
+
+  # Raised when errors occur during configuration.
+  ConfigurationError = Class.new(StandardError)
+
+  # Raised when a lifecycle method (such as `stop`) is called in an improper
+  # sequence or when the object is in an inappropriate state.
+  LifecycleError = Class.new(StandardError)
+
+  # Raised when an object's methods are called when it has not been
+  # properly initialized.
+  InitializationError = Class.new(StandardError)
+
+  # Raised when an object with a start/stop lifecycle has been started an
+  # excessive number of times. Often used in conjunction with a restart
+  # policy or strategy.
+  MaxRestartFrequencyError = Class.new(StandardError)
+
+  # Raised when an attempt is made to modify an immutable object
+  # (such as an `IVar`) after its final state has been set.
+  MultipleAssignmentError = Class.new(StandardError)
+
+  # Raised by an `Executor` when it is unable to process a given task,
+  # possibly because of a reject policy or other internal error.
+  RejectedExecutionError = Class.new(StandardError)
+
+  # Raised when an operation times out.
+  TimeoutError = Class.new(StandardError)
+
+end

data/lib/concurrent/exchanger.rb

@@ -0,0 +1,34 @@
+module Concurrent
+  class Exchanger
+
+    EMPTY = Object.new
+
+    def initialize(opts = {})
+      @first = MVar.new(EMPTY, opts)
+      @second = MVar.new(MVar::EMPTY, opts)
+    end
+
+    # @param [Object] value the value to exchange with an other thread
+    # @param [Numeric] timeout the maximum time in second to wait for one other thread. nil (default value) means no timeout
+    # @return [Object] the value exchanged by the other thread; nil if timed out
+    def exchange(value, timeout = nil)
+      first = @first.take(timeout)
+      if first == MVar::TIMEOUT
+        nil
+      elsif first == EMPTY
+        @first.put value
+        second = @second.take timeout
+        if second == MVar::TIMEOUT
+          nil
+        else
+          second
+        end
+      else
+        @first.put EMPTY
+        @second.put value
+        first
+      end
+    end
+
+  end
+end

data/lib/concurrent/executor/cached_thread_pool.rb

@@ -0,0 +1,44 @@
+require 'concurrent/executor/ruby_cached_thread_pool'
+
+module Concurrent
+
+  if RUBY_PLATFORM == 'java'
+    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`
+    #
+    #   @note When running on the JVM (JRuby) this class will inherit from `JavaCachedThreadPool`.
+    #     On all other platforms it will inherit from `RubyCachedThreadPool`.
+    #
+    #   @see Concurrent::RubyCachedThreadPool
+    #   @see Concurrent::JavaCachedThreadPool
+    #
+    #   @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
+    class CachedThreadPool < JavaCachedThreadPool
+    end
+  else
+    # @!macro cached_thread_pool
+    class CachedThreadPool < RubyCachedThreadPool
+    end
+  end
+end

data/lib/concurrent/executor/executor.rb

@@ -0,0 +1,282 @@
+require 'concurrent/errors'
+require 'concurrent/logging'
+require 'concurrent/atomic/event'
+
+module Concurrent
+
+  module Executor
+    
+    # @!macro [attach] executor_module_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.
+    #
+    # @note Always returns `false`
+    def can_overflow?
+      false
+    end
+
+    # @!macro [attach] executor_module_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.
+    #
+    # @note Always returns `false`
+    def serialized?
+      false
+    end
+  end
+
+  # Indicates that the including `Executor` or `ExecutorService` guarantees
+  # that all operations will occur in the order they are post and that no
+  # two operations may occur simultaneously. This module provides no
+  # functionality and provides no guarantees. That is the responsibility
+  # of the including class. This module exists solely to allow the including
+  # object to be interrogated for its serialization status.
+  #
+  # @example
+  #   class Foo
+  #     include Concurrent::SerialExecutor
+  #   end
+  #
+  #   foo = Foo.new
+  #
+  #   foo.is_a? Concurrent::Executor       #=> true
+  #   foo.is_a? Concurrent::SerialExecutor #=> true
+  #   foo.serialized?                      #=> true
+  module SerialExecutor
+    include Executor
+
+    # @!macro executor_module_method_serialized_question
+    #
+    # @note Always returns `true`
+    def serialized?
+      true
+    end
+  end
+
+  module RubyExecutor
+    include Executor
+    include Logging
+
+    # @!macro [attach] executor_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
+    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
+
+    # @!macro [attach] executor_method_left_shift
+    #
+    #   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
+
+    # @!macro [attach] executor_method_running_question
+    #
+    #   Is the executor running?
+    #
+    #   @return [Boolean] `true` when running, `false` when shutting down or shutdown
+    def running?
+      ! stop_event.set?
+    end
+
+    # @!macro [attach] executor_method_shuttingdown_question
+    #
+    #   Is the executor shuttingdown?
+    #
+    #   @return [Boolean] `true` when not running and not shutdown, else `false`
+    def shuttingdown?
+      ! (running? || shutdown?)
+    end
+
+    # @!macro [attach] executor_method_shutdown_question
+    #
+    #   Is the executor shutdown?
+    #
+    #   @return [Boolean] `true` when shutdown, `false` when shutting down or running
+    def shutdown?
+      stopped_event.set?
+    end
+
+    # @!macro [attach] executor_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.
+    def shutdown
+      mutex.synchronize do
+        break unless running?
+        stop_event.set
+        shutdown_execution
+      end
+      true
+    end
+
+    # @!macro [attach] executor_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.
+    def kill
+      mutex.synchronize do
+        break if shutdown?
+        stop_event.set
+        kill_execution
+        stopped_event.set
+      end
+      true
+    end
+
+    # @!macro [attach] executor_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`
+    def wait_for_termination(timeout = nil)
+      stopped_event.wait(timeout)
+    end
+
+    protected
+
+    attr_reader :mutex, :stop_event, :stopped_event
+
+    # @!macro [attach] executor_method_init_executor
+    #
+    #   Initialize the executor by creating and initializing all the
+    #   internal synchronization objects.
+    def init_executor
+      @mutex = Mutex.new
+      @stop_event = Event.new
+      @stopped_event = Event.new
+    end
+
+    # @!macro [attach] executor_method_execute
+    def execute(*args, &task)
+      raise NotImplementedError
+    end
+
+    # @!macro [attach] executor_method_shutdown_execution
+    # 
+    #   Callback method called when an orderly shutdown has completed.
+    #   The default behavior is to signal all waiting threads.
+    def shutdown_execution
+      stopped_event.set
+    end
+
+    # @!macro [attach] executor_method_kill_execution
+    #
+    #   Callback method called when the executor has been killed.
+    #   The default behavior is to do nothing.
+    def kill_execution
+      # do nothing
+    end
+  end
+
+  if RUBY_PLATFORM == 'java'
+
+    module JavaExecutor
+      include Executor
+      java_import 'java.lang.Runnable'
+
+      # @!macro executor_method_post
+      def post(*args)
+        raise ArgumentError.new('no block given') unless block_given?
+        if running?
+          executor_submit = @executor.java_method(:submit, [Runnable.java_class])
+          executor_submit.call { yield(*args) }
+          true
+        else
+          false
+        end
+      rescue Java::JavaUtilConcurrent::RejectedExecutionException
+        raise RejectedExecutionError
+      end
+
+      # @!macro executor_method_left_shift
+      def <<(task)
+        post(&task)
+        self
+      end
+
+      # @!macro executor_method_running_question
+      def running?
+        ! (shuttingdown? || shutdown?)
+      end
+
+      # @!macro executor_method_shuttingdown_question
+      def shuttingdown?
+        if @executor.respond_to? :isTerminating
+          @executor.isTerminating
+        else
+          false
+        end
+      end
+
+      # @!macro executor_method_shutdown_question
+      def shutdown?
+        @executor.isShutdown || @executor.isTerminated
+      end
+
+      # @!macro executor_method_wait_for_termination
+      def wait_for_termination(timeout = nil)
+        if timeout.nil?
+          ok = @executor.awaitTermination(60, java.util.concurrent.TimeUnit::SECONDS) until ok
+          true
+        else
+          @executor.awaitTermination(1000 * timeout, java.util.concurrent.TimeUnit::MILLISECONDS)
+        end
+      end
+
+      # @!macro executor_method_shutdown
+      def shutdown
+        @executor.shutdown
+        nil
+      end
+
+      # @!macro executor_method_kill
+      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/executor/fixed_thread_pool.rb

@@ -0,0 +1,33 @@
+require 'concurrent/executor/ruby_fixed_thread_pool'
+
+module Concurrent
+
+  if RUBY_PLATFORM == 'java'
+    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.
+    #   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`
+    #
+    #   @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
+    #   @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
+    class FixedThreadPool < JavaFixedThreadPool
+    end
+  else
+    # @!macro fixed_thread_pool
+    class FixedThreadPool < RubyFixedThreadPool
+    end
+  end
+end

data/lib/concurrent/executor/immediate_executor.rb

@@ -0,0 +1,65 @@
+require 'concurrent/atomic/event'
+require 'concurrent/executor/executor'
+
+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
+    include SerialExecutor
+
+    # Creates a new executor
+    def initialize
+      @stopped = Concurrent::Event.new
+    end
+
+    # @!macro executor_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_method_left_shift
+    def <<(task)
+      post(&task)
+      self
+    end
+
+    # @!macro executor_method_running_question
+    def running?
+      ! shutdown?
+    end
+
+    # @!macro executor_method_shuttingdown_question
+    def shuttingdown?
+      false
+    end
+
+    # @!macro executor_method_shutdown_question
+    def shutdown?
+      @stopped.set?
+    end
+
+    # @!macro executor_method_shutdown
+    def shutdown
+      @stopped.set
+      true
+    end
+    alias_method :kill, :shutdown
+
+    # @!macro executor_method_wait_for_termination
+    def wait_for_termination(timeout = nil)
+      @stopped.wait(timeout)
+    end
+  end
+end