concurrent-ruby 0.8.0 → 0.9.0.pre2

data/lib/concurrent/edge.rb

@@ -0,0 +1,30 @@
+module Concurrent
+
+  # A submodule for unstable, highly experimental features that are likely to
+  # change often and which may never become part of the core gem. Also for
+  # new, experimental version of abstractions already in the core gem.
+  #
+  # Most new features should start in this module, clearly indicating the
+  # experimental and unstable nature of the feature. Once a feature becomes
+  # more stable and is a candidate for inclusion in the core gem it should
+  # be moved up to the `Concurrent` module, where it would reside once merged
+  # into the core gem.
+  #
+  # The only exception to this is for features which *replace* features from
+  # the core gem in ways that are breaking and not backward compatible. These
+  # features should remain in this module until merged into the core gem. This
+  # will prevent namespace collisions.
+  #
+  # This file should *never* be used as a global `require` for all files within
+  # the edge gem. Because these features are experimental users should always
+  # explicitly require only what they need.
+  #
+  # @!macro [attach] edge_warning
+  #   @api Edge
+  #   @note **Edge Feature:** Edge features are under active development and may
+  #     change frequently. They are not expected to keep backward compatibility.
+  #     They may also lack tests and documentation. Use with caution.
+  module Edge
+
+  end
+end

data/lib/concurrent/errors.rb

@@ -3,10 +3,16 @@ module Concurrent
   # Raised when errors occur during configuration.
   ConfigurationError = Class.new(StandardError)
 
+  # Raised when an asynchronous operation is cancelled before execution.
+  CancelledOperationError = 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 attempt is made to violate an immutability guarantee.
+  ImmutabilityError = Class.new(StandardError)
+
   # Raised when an object's methods are called when it has not been
   # properly initialized.
   InitializationError = Class.new(StandardError)
@@ -24,6 +30,10 @@ module Concurrent
   # possibly because of a reject policy or other internal error.
   RejectedExecutionError = Class.new(StandardError)
 
+  # Raised when any finite resource, such as a lock counter, exceeds its
+  # maximum limit/threshold.
+  ResourceLimitError = Class.new(StandardError)
+
   # Raised when an operation times out.
   TimeoutError = Class.new(StandardError)
 

data/lib/concurrent/exchanger.rb

@@ -1,15 +1,39 @@
 module Concurrent
+
+  # A synchronization point at which threads can pair and swap elements within
+  # pairs. Each thread presents some object on entry to the exchange method,
+  # matches with a partner thread, and receives its partner's object on return.
+  #
+  # Uses `MVar` to manage synchronization of the individual elements.
+  # Since `MVar` is also a `Dereferenceable`, the exchanged values support all
+  # dereferenceable options. The constructor options hash will be passed to
+  # the `MVar` constructors.
+  # 
+  # @see Concurrent::MVar
+  # @see Concurrent::Concern::Dereferenceable
+  # @see http://docs.oracle.com/javase/7/docs/api/java/util/concurrent/Exchanger.html java.util.concurrent.Exchanger
+  #
+  # @!macro edge_warning
   class Exchanger
 
     EMPTY = Object.new
 
+    # Create a new `Exchanger` object.
+    #
+    # @param [Hash] opts the options controlling how the managed references
+    #   will be processed
     def initialize(opts = {})
       @first = MVar.new(EMPTY, opts)
       @second = MVar.new(MVar::EMPTY, opts)
     end
 
+    # Waits for another thread to arrive at this exchange point (unless the
+    # current thread is interrupted), and then transfers the given object to
+    # it, receiving its object in return.
+    #
     # @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
+    # @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)

data/lib/concurrent/executor/cached_thread_pool.rb

@@ -2,43 +2,56 @@ require 'concurrent/executor/ruby_cached_thread_pool'
 
 module Concurrent
 
-  if RUBY_PLATFORM == 'java'
+  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.
+  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`
+  #
+  # @!macro thread_pool_options
+  # @!macro thread_pool_executor_public_api
+  class CachedThreadPool < CachedThreadPoolImplementation
+
+    # @!macro [new] cached_thread_pool_method_initialize
     #
-    #   The API and behavior of this class are based on Java's `CachedThreadPool`
+    #   Create a new thread pool.
     #
-    #   @note When running on the JVM (JRuby) this class will inherit from `JavaCachedThreadPool`.
-    #     On all other platforms it will inherit from `RubyCachedThreadPool`.
+    #   @param [Hash] opts the options defining pool behavior.
+    #   @option opts [Symbol] :fallback_policy (`:abort`) the fallback policy
     #
-    #   @see Concurrent::RubyCachedThreadPool
-    #   @see Concurrent::JavaCachedThreadPool
+    #   @raise [ArgumentError] if `fallback_policy` is not a known policy
     #
-    #   @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
+    #   @see http://docs.oracle.com/javase/8/docs/api/java/util/concurrent/Executors.html#newCachedThreadPool--
+
+    # @!method initialize(opts = {})
+    #   @!macro cached_thread_pool_method_initialize
   end
 end

data/lib/concurrent/executor/executor.rb

@@ -1,319 +1,66 @@
-require 'concurrent/errors'
-require 'concurrent/logging'
-require 'concurrent/atomic/event'
+require 'concurrent/executor/executor_service'
+require 'concurrent/concern/deprecation'
 
 module Concurrent
 
+  # @!visibility private
   module Executor
-    # 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
+    extend Concern::Deprecation
 
-    # @!macro [attach] executor_module_method_can_overflow_question
+    # Get the requested `Executor` based on the values set in the options hash.
     #
-    #   Does the task queue have a maximum size?
+    # @param [Hash] opts the options defining the requested executor
+    # @option opts [Executor] :executor when set use the given `Executor` instance.
+    #   Three special values are also supported: `:fast` returns the global fast executor,
+    #   `:io` returns the global io executor, and `:immediate` returns a new
+    #   `ImmediateExecutor` object.
     #
-    #   @return [Boolean] True if the task queue has a maximum size else false.
-    #
-    # @note Always returns `false`
-    def can_overflow?
-      false
-    end
-
-    # 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.
+    # @return [Executor, nil] the requested thread pool, or nil when no option specified
     #
     # @!visibility private
-    def handle_fallback(*args)
-      case @fallback_policy
-      when :abort
-        raise RejectedExecutionError
-      when :discard
-        false
-      when :caller_runs
-        begin
-          yield(*args)
-        rescue => ex
-          # let it fail
-          log DEBUG, ex
-        end
-        true
-      else
-        fail "Unknown fallback policy #{@fallback_policy}"
-      end
-    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
-
-    # 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
-    #
-    #   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
-        # If the executor is shut down, reject this task
-        return handle_fallback(*args, &task) 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'
-
-      # 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
-      }.freeze
-
-      # @!macro executor_method_post
-      def post(*args, &task)
-        raise ArgumentError.new('no block given') unless block_given?
-        return handle_fallback(*args, &task) unless running?
-        executor_submit = @executor.java_method(:submit, [Runnable.java_class])
-        executor_submit.call { yield(*args) }
-        true
-      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
+    def self.executor_from_options(opts = {}) # :nodoc:
+      case
+      when opts.key?(:executor)
+        if opts[:executor].nil?
+          nil
         else
-          false
+          executor(opts[:executor])
         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)
+      when opts.key?(:operation) || opts.key?(:task)
+        if opts[:operation] == true || opts[:task] == false
+          deprecated 'use `executor: :fast` instead'
+          return Concurrent.global_fast_executor
         end
-      end
 
-      # @!macro executor_method_shutdown
-      def shutdown
-        @executor.shutdown
-        nil
-      end
+        if opts[:operation] == false || opts[:task] == true
+          deprecated 'use `executor: :io` instead'
+          return Concurrent.global_io_executor
+        end
 
-      # @!macro executor_method_kill
-      def kill
-        @executor.shutdownNow
+        raise ArgumentError.new("executor '#{opts[:executor]}' not recognized")
+      else
         nil
       end
+    end
 
-      protected
-
-      def set_shutdown_hook
-        # without this the process may fail to exit
-        at_exit { self.kill }
+    def self.executor(executor_identifier)
+      case executor_identifier
+      when :fast
+        Concurrent.global_fast_executor
+      when :io
+        Concurrent.global_io_executor
+      when :immediate
+        Concurrent.global_immediate_executor
+      when :operation
+        deprecated 'use `executor: :fast` instead'
+        Concurrent.global_fast_executor
+      when :task
+        deprecated 'use `executor: :io` instead'
+        Concurrent.global_io_executor
+      when Concurrent::ExecutorService
+        executor_identifier
+      else
+        raise ArgumentError, "executor not recognized by '#{executor_identifier}'"
       end
     end
   end