concurrent-ruby 0.8.0 → 0.9.0.pre2

data/lib/concurrent/configuration.rb

@@ -1,128 +1,274 @@
 require 'thread'
-require 'concurrent/delay'
+require 'concurrent/atomics'
 require 'concurrent/errors'
-require 'concurrent/atomic'
-require 'concurrent/executor/immediate_executor'
-require 'concurrent/executor/thread_pool_executor'
-require 'concurrent/executor/timer_set'
-require 'concurrent/utility/processor_count'
+require 'concurrent/executors'
+require 'concurrent/concern/deprecation'
+require 'concurrent/concern/logging'
+require 'concurrent/utility/at_exit'
+require 'concurrent/utility/processor_counter'
 
 module Concurrent
-  extend Logging
+  extend Concern::Logging
+  extend Concern::Deprecation
 
-  # A gem-level configuration object.
-  class Configuration
+  # Suppresses all output when used for logging.
+  NULL_LOGGER = lambda { |level, progname, message = nil, &block| }
 
-    # a proc defining how to log messages, its interface has to be:
-    #   lambda { |level, progname, message = nil, &block| _ }
-    attr_accessor :logger
+  # @!visibility private
+  GLOBAL_LOGGER = AtomicReference.new(NULL_LOGGER)
+  private_constant :GLOBAL_LOGGER
+
+  # @!visibility private
+  GLOBAL_FAST_EXECUTOR = Delay.new { Concurrent.new_fast_executor(auto_terminate: true) }
+  private_constant :GLOBAL_FAST_EXECUTOR
+
+  # @!visibility private
+  GLOBAL_IO_EXECUTOR = Delay.new { Concurrent.new_io_executor(auto_terminate: true) }
+  private_constant :GLOBAL_IO_EXECUTOR
 
-    # defines if executors should be auto-terminated in at_exit callback
-    attr_accessor :auto_terminate
+  # @!visibility private
+  GLOBAL_TIMER_SET = Delay.new { TimerSet.new(auto_terminate: true) }
+  private_constant :GLOBAL_TIMER_SET
+
+  # @!visibility private
+  GLOBAL_IMMEDIATE_EXECUTOR = ImmediateExecutor.new
+  private_constant :GLOBAL_IMMEDIATE_EXECUTOR
+
+  def self.global_logger
+    GLOBAL_LOGGER.value
+  end
+
+  def self.global_logger=(value)
+    GLOBAL_LOGGER.value = value
+  end
+
+  # @return [Logger] Logger with provided level and output.
+  def self.create_stdlib_logger(level = Logger::FATAL, output = $stderr)
+    logger           = Logger.new(output)
+    logger.level     = level
+    logger.formatter = lambda do |severity, datetime, progname, msg|
+      formatted_message = case msg
+                          when String
+                            msg
+                          when Exception
+                            format "%s (%s)\n%s",
+                                   msg.message, msg.class, (msg.backtrace || []).join("\n")
+                          else
+                            msg.inspect
+                          end
+      format "[%s] %5s -- %s: %s\n",
+             datetime.strftime('%Y-%m-%d %H:%M:%S.%L'),
+             severity,
+             progname,
+             formatted_message
+    end
+    logger
+  end
+
+  # Use logger created by #create_stdlib_logger to log concurrent-ruby messages.
+  def self.use_stdlib_logger(level = Logger::FATAL, output = $stderr)
+    logger = create_stdlib_logger level, output
+    Concurrent.global_logger = lambda do |level, progname, message = nil, &block|
+      logger.add level, message, progname, &block
+    end
+  end
+
+  # Disables AtExit hooks including pool auto-termination hooks.
+  # When disabled it will be the application
+  # programmer's responsibility to ensure that the hooks
+  # are shutdown properly prior to application exit
+  # by calling {AtExit.run} method.
+  #
+  # @note this option should be needed only because of `at_exit` ordering
+  #   issues which may arise when running some of the testing frameworks.
+  #   E.g. Minitest's test-suite runs itself in `at_exit` callback which
+  #   executes after the pools are already terminated. Then auto termination
+  #   needs to be disabled and called manually after test-suite ends.
+  # @note This method should *never* be called
+  #   from within a gem. It should *only* be used from within the main
+  #   application and even then it should be used only when necessary.
+  # @see AtExit
+  def self.disable_at_exit_hooks!
+    AtExit.enabled = false
+  end
+
+  def self.disable_executor_auto_termination!
+    deprecated_method 'disable_executor_auto_termination!', 'disable_at_exit_hooks!'
+    disable_at_exit_hooks!
+  end
+
+  # @return [true,false]
+  # @see .disable_executor_auto_termination!
+  def self.disable_executor_auto_termination?
+    deprecated_method 'disable_executor_auto_termination?', 'Concurrent::AtExit.enabled?'
+    AtExit.enabled?
+  end
+
+  # terminates all pools and blocks until they are terminated
+  # @see .disable_executor_auto_termination!
+  def self.terminate_pools!
+    deprecated_method 'terminate_pools!', 'Concurrent::AtExit.run'
+    AtExit.run
+  end
+
+  # Global thread pool optimized for short, fast *operations*.
+  #
+  # @return [ThreadPoolExecutor] the thread pool
+  def self.global_fast_executor
+    GLOBAL_FAST_EXECUTOR.value
+  end
+
+  # Global thread pool optimized for long, blocking (IO) *tasks*.
+  #
+  # @return [ThreadPoolExecutor] the thread pool
+  def self.global_io_executor
+    GLOBAL_IO_EXECUTOR.value
+  end
+
+  def self.global_immediate_executor
+    GLOBAL_IMMEDIATE_EXECUTOR
+  end
+
+  # Global thread pool user for global *timers*.
+  #
+  # @return [Concurrent::TimerSet] the thread pool
+  #
+  # @see Concurrent::timer
+  def self.global_timer_set
+    GLOBAL_TIMER_SET.value
+  end
+
+  # General access point to global executors.
+  # @param [Symbol, Executor] executor_identifier symbols:
+  #   - :fast - {Concurrent.global_fast_executor}
+  #   - :io - {Concurrent.global_io_executor}
+  #   - :immediate - {Concurrent.global_immediate_executor}
+  # @return [Executor]
+  def self.executor(executor_identifier)
+    Executor.executor(executor_identifier)
+  end
+
+  def self.new_fast_executor(opts = {})
+    FixedThreadPool.new(
+        [2, Concurrent.processor_count].max,
+        auto_terminate:  opts.fetch(:auto_terminate, true),
+        idletime:        60, # 1 minute
+        max_queue:       0, # unlimited
+        fallback_policy: :abort # shouldn't matter -- 0 max queue
+    )
+  end
+
+  def self.new_io_executor(opts = {})
+    ThreadPoolExecutor.new(
+        min_threads:     [2, Concurrent.processor_count].max,
+        max_threads:     ThreadPoolExecutor::DEFAULT_MAX_POOL_SIZE,
+        # max_threads:     1000,
+        auto_terminate:  opts.fetch(:auto_terminate, true),
+        idletime:        60, # 1 minute
+        max_queue:       0, # unlimited
+        fallback_policy: :abort # shouldn't matter -- 0 max queue
+    )
+  end
+
+  # A gem-level configuration object.
+  class Configuration
+    include Concern::Deprecation
 
     # Create a new configuration object.
     def initialize
-      immediate_executor     = ImmediateExecutor.new
-      @global_task_pool      = Delay.new(executor: immediate_executor) { new_task_pool }
-      @global_operation_pool = Delay.new(executor: immediate_executor) { new_operation_pool }
-      @global_timer_set      = Delay.new(executor: immediate_executor) { Concurrent::TimerSet.new }
-      @logger                = no_logger
-      @auto_terminate        = true
     end
 
     # if assigned to {#logger}, it will log nothing.
+    # @deprecated Use Concurrent::NULL_LOGGER instead
     def no_logger
-      lambda { |level, progname, message = nil, &block| }
+      deprecated_method 'Concurrent.configuration.no_logger', 'Concurrent::NULL_LOGGER'
+      NULL_LOGGER
     end
 
-    # Global thread pool optimized for short *tasks*.
+    # a proc defining how to log messages, its interface has to be:
+    #   lambda { |level, progname, message = nil, &block| _ }
     #
-    # @return [ThreadPoolExecutor] the thread pool
-    def global_task_pool
-      @global_task_pool.value
+    # @deprecated Use Concurrent.global_logger instead
+    def logger
+      deprecated_method 'Concurrent.configuration.logger', 'Concurrent.global_logger'
+      Concurrent.global_logger.value
     end
 
-    # Global thread pool optimized for long *operations*.
+    # a proc defining how to log messages, its interface has to be:
+    #   lambda { |level, progname, message = nil, &block| _ }
     #
-    # @return [ThreadPoolExecutor] the thread pool
+    # @deprecated Use Concurrent.global_logger instead
+    def logger=(value)
+      deprecated_method 'Concurrent.configuration.logger=', 'Concurrent.global_logger='
+      Concurrent.global_logger = value
+    end
+
+    # @deprecated Use Concurrent.global_io_executor instead
+    def global_task_pool
+      deprecated_method 'Concurrent.configuration.global_task_pool', 'Concurrent.global_io_executor'
+      Concurrent.global_io_executor
+    end
+
+    # @deprecated Use Concurrent.global_fast_executor instead
     def global_operation_pool
-      @global_operation_pool.value
+      deprecated_method 'Concurrent.configuration.global_operation_pool', 'Concurrent.global_fast_executor'
+      Concurrent.global_fast_executor
     end
 
-    # Global thread pool optimized for *timers*
-    #
-    # @return [ThreadPoolExecutor] the thread pool
-    #
-    # @see Concurrent::timer
+    # @deprecated Use Concurrent.global_timer_set instead
     def global_timer_set
-      @global_timer_set.value
+      deprecated_method 'Concurrent.configuration.global_timer_set', 'Concurrent.global_timer_set'
+      Concurrent.global_timer_set
     end
 
-    # Global thread pool optimized for short *tasks*.
-    #
-    # A global thread pool must be set as soon as the gem is loaded. Setting a new
-    # thread pool once tasks and operations have been post can lead to unpredictable
-    # results. The first time a task/operation is post a new thread pool will be
-    # created using the default configuration. Once set the thread pool cannot be
-    # changed. Thus, explicitly setting the thread pool must occur *before* any
-    # tasks/operations are post else an exception will be raised.
-    #
-    # @param [Executor] executor the executor to be used for this thread pool
-    #
-    # @return [ThreadPoolExecutor] the new thread pool
-    #
-    # @raise [Concurrent::ConfigurationError] if this thread pool has already been set
+    # @deprecated Replacing global thread pools is deprecated.
+    #   Use the :executor constructor option instead.
     def global_task_pool=(executor)
-      @global_task_pool.reconfigure { executor } or
+      deprecated 'Replacing global thread pools is deprecated. Use the :executor constructor option instead.'
+      GLOBAL_IO_EXECUTOR.reconfigure { executor } or
           raise ConfigurationError.new('global task pool was already set')
     end
 
-    # Global thread pool optimized for long *operations*.
-    #
-    # A global thread pool must be set as soon as the gem is loaded. Setting a new
-    # thread pool once tasks and operations have been post can lead to unpredictable
-    # results. The first time a task/operation is post a new thread pool will be
-    # created using the default configuration. Once set the thread pool cannot be
-    # changed. Thus, explicitly setting the thread pool must occur *before* any
-    # tasks/operations are post else an exception will be raised.
-    #
-    # @param [Executor] executor the executor to be used for this thread pool
-    #
-    # @return [ThreadPoolExecutor] the new thread pool
-    #
-    # @raise [Concurrent::ConfigurationError] if this thread pool has already been set
+    # @deprecated Replacing global thread pools is deprecated.
+    #   Use the :executor constructor option instead.
     def global_operation_pool=(executor)
-      @global_operation_pool.reconfigure { executor } or
+      deprecated 'Replacing global thread pools is deprecated. Use the :executor constructor option instead.'
+      GLOBAL_FAST_EXECUTOR.reconfigure { executor } or
           raise ConfigurationError.new('global operation pool was already set')
     end
 
+    # @deprecated Use Concurrent.new_io_executor instead
     def new_task_pool
-      Concurrent::ThreadPoolExecutor.new(
-          min_threads:     [2, Concurrent.processor_count].max,
-          max_threads:     [20, Concurrent.processor_count * 15].max,
-          idletime:        2 * 60, # 2 minutes
-          max_queue:       0, # unlimited
-          fallback_policy: :abort # raise an exception
-      )
+      deprecated_method 'Concurrent.configuration.new_task_pool', 'Concurrent.new_io_executor'
+      Concurrent.new_io_executor
     end
 
+    # @deprecated Use Concurrent.new_fast_executor instead
     def new_operation_pool
-      Concurrent::ThreadPoolExecutor.new(
-          min_threads:     [2, Concurrent.processor_count].max,
-          max_threads:     [2, Concurrent.processor_count].max,
-          idletime:        10 * 60, # 10 minutes
-          max_queue:       [20, Concurrent.processor_count * 15].max,
-          fallback_policy: :abort # raise an exception
-      )
+      deprecated_method 'Concurrent.configuration.new_operation_pool', 'Concurrent.new_fast_executor'
+      Concurrent.new_fast_executor
+    end
+
+    # @deprecated Use Concurrent.disable_auto_termination_of_global_executors! instead
+    def auto_terminate=(value)
+      deprecated_method 'Concurrent.configuration.auto_terminate=', 'Concurrent.disable_auto_termination_of_global_executors!'
+      Concurrent.disable_auto_termination_of_global_executors! if !value
+    end
+
+    # @deprecated Use Concurrent.auto_terminate_global_executors? instead
+    def auto_terminate
+      deprecated_method 'Concurrent.configuration.auto_terminate', 'Concurrent.auto_terminate_global_executors?'
+      Concurrent.auto_terminate_global_executors?
     end
   end
 
   # create the default configuration on load
-  @configuration = Atomic.new Configuration.new
+  CONFIGURATION = AtomicReference.new(Configuration.new)
+  private_constant :CONFIGURATION
 
   # @return [Configuration]
   def self.configuration
-    @configuration.value
+    CONFIGURATION.value
   end
 
   # Perform gem-level configuration.
@@ -132,36 +278,4 @@ module Concurrent
   def self.configure
     yield(configuration)
   end
-
-  def self.finalize_global_executors
-    self.finalize_executor(self.configuration.global_timer_set)
-    self.finalize_executor(self.configuration.global_task_pool)
-    self.finalize_executor(self.configuration.global_operation_pool)
-  end
-
-  private
-
-  # Attempt to properly shutdown the given executor using the `shutdown` or
-  # `kill` method when available.
-  #
-  # @param [Executor] executor the executor to shutdown
-  #
-  # @return [Boolean] `true` if the executor is successfully shut down or `nil`, else `false`
-  def self.finalize_executor(executor)
-    return true if executor.nil?
-    if executor.respond_to?(:shutdown)
-      executor.shutdown
-    elsif executor.respond_to?(:kill)
-      executor.kill
-    end
-    true
-  rescue => ex
-    log DEBUG, ex
-    false
-  end
-
-  # set exit hook to shutdown global thread pools
-  at_exit do
-    finalize_global_executors if configuration.auto_terminate
-  end
 end

data/lib/concurrent/dataflow.rb

@@ -1,6 +1,5 @@
 require 'concurrent/future'
 require 'concurrent/atomic/atomic_fixnum'
-require 'concurrent/executor/per_thread_executor'
 
 module Concurrent
 
@@ -32,7 +31,7 @@ module Concurrent
   # @raise [ArgumentError] if no block is given
   # @raise [ArgumentError] if any of the inputs are not `IVar`s
   def dataflow(*inputs, &block)
-    dataflow_with(Concurrent.configuration.global_operation_pool, *inputs, &block)
+    dataflow_with(Concurrent.global_io_executor, *inputs, &block)
   end
   module_function :dataflow
 
@@ -42,7 +41,7 @@ module Concurrent
   module_function :dataflow_with
   
   def dataflow!(*inputs, &block)
-    dataflow_with!(Concurrent.configuration.global_task_pool, *inputs, &block)
+    dataflow_with!(Concurrent.global_io_executor, *inputs, &block)
   end
   module_function :dataflow!
 

data/lib/concurrent/delay.rb

@@ -1,17 +1,21 @@
 require 'thread'
-require 'concurrent/obligation'
-require 'concurrent/options_parser'
+require 'concurrent/configuration'
+require 'concurrent/concern/obligation'
+require 'concurrent/executor/executor'
+require 'concurrent/executor/immediate_executor'
+require 'concurrent/synchronization'
 
 module Concurrent
 
-  # Lazy evaluation of a block yielding an immutable result. Useful for expensive
-  # operations that may never be needed.
+  # Lazy evaluation of a block yielding an immutable result. Useful for
+  # expensive operations that may never be needed. It may be non-blocking,
+  # supports the `Concern::Obligation` interface, and accepts the injection of
+  # custom executor upon which to execute the block. Processing of
+  # block will be deferred until the first time `#value` is called.
+  # At that time the caller can choose to return immediately and let
+  # the block execute asynchronously, block indefinitely, or block
+  # with a timeout.
   #
-  # A `Delay` is similar to `Future` but solves a different problem.
-  # Where a `Future` schedules an operation for immediate execution and
-  # performs the operation asynchronously, a `Delay` (as the name implies)
-  # delays execution of the operation until the result is actually needed.
-  # 
   # When a `Delay` is created its state is set to `pending`. The value and
   # reason are both `nil`. The first time the `#value` method is called the
   # enclosed opration will be run and the calling thread will block. Other
@@ -22,68 +26,155 @@ module Concurrent
   # return the cached value. The operation will only be run once. This means that
   # any side effects created by the operation will only happen once as well.
   #
-  # `Delay` includes the `Concurrent::Dereferenceable` mixin to support thread
+  # `Delay` includes the `Concurrent::Concern::Dereferenceable` mixin to support thread
   # safety of the reference returned by `#value`.
   #
-  # @since 0.6.0
+  # @!macro copy_options
   #
-  # @see Concurrent::Dereferenceable
+  # @!macro [attach] delay_note_regarding_blocking
+  #   @note The default behavior of `Delay` is to block indefinitely when
+  #     calling either `value` or `wait`, executing the delayed operation on
+  #     the current thread. This makes the `timeout` value completely
+  #     irrelevant. To enable non-blocking behavior, use the `executor`
+  #     constructor option. This will cause the delayed operation to be
+  #     execute on the given executor, allowing the call to timeout.
   #
-  # @see http://clojuredocs.org/clojure_core/clojure.core/delay
-  # @see http://aphyr.com/posts/306-clojure-from-the-ground-up-state
-  class Delay
-    include Obligation
+  # @see Concurrent::Concern::Dereferenceable
+  class Delay < Synchronization::Object
+    include Concern::Obligation
+
+    # NOTE: Because the global thread pools are lazy-loaded with these objects
+    # there is a performance hit every time we post a new task to one of these
+    # thread pools. Subsequently it is critical that `Delay` perform as fast
+    # as possible post-completion. This class has been highly optimized using
+    # the benchmark script `examples/lazy_and_delay.rb`. Do NOT attempt to
+    # DRY-up this class or perform other refactoring with running the
+    # benchmarks and ensuring that performance is not negatively impacted.
 
     # Create a new `Delay` in the `:pending` state.
     #
-    # @yield the delayed operation to perform
+    # @!macro executor_and_deref_options
     #
-    # @param [Hash] opts the options to create a message with
-    # @option opts [String] :dup_on_deref (false) call `#dup` before returning the data
-    # @option opts [String] :freeze_on_deref (false) call `#freeze` before returning the data
-    # @option opts [String] :copy_on_deref (nil) call the given `Proc` passing the internal value and
-    #   returning the value returned from the proc
+    # @yield the delayed operation to perform
     #
     # @raise [ArgumentError] if no block is given
     def initialize(opts = {}, &block)
       raise ArgumentError.new('no block given') unless block_given?
+      super(&nil)
+      synchronize { ns_initialize(opts, &block) }
+    end
 
-      init_obligation
-      @state = :pending
-      @task  = block
-      set_deref_options(opts)
-      @task_executor = OptionsParser.get_task_executor_from(opts)
-      @computing     = false
+    # Return the value this object represents after applying the options
+    # specified by the `#set_deref_options` method. If the delayed operation
+    # raised an exception this method will return nil. The execption object
+    # can be accessed via the `#reason` method.
+    #
+    # @param [Numeric] timeout the maximum number of seconds to wait
+    # @return [Object] the current value of the object
+    #
+    # @!macro delay_note_regarding_blocking
+    def value(timeout = nil)
+      if @task_executor
+        super
+      else
+        # this function has been optimized for performance and
+        # should not be modified without running new benchmarks
+        mutex.synchronize do
+          execute = @computing = true unless @computing
+          if execute
+            begin
+              set_state(true, @task.call, nil)
+            rescue => ex
+              set_state(false, nil, ex)
+            end
+          end
+        end
+        if @do_nothing_on_deref
+          @value
+        else
+          apply_deref_options(@value)
+        end
+      end
+    end
+
+    # Return the value this object represents after applying the options
+    # specified by the `#set_deref_options` method. If the delayed operation
+    # raised an exception, this method will raise that exception (even when)
+    # the operation has already been executed).
+    #
+    # @param [Numeric] timeout the maximum number of seconds to wait
+    # @return [Object] the current value of the object
+    # @raise [Exception] when `#rejected?` raises `#reason`
+    #
+    # @!macro delay_note_regarding_blocking
+    def value!(timeout = nil)
+      if @task_executor
+        super
+      else
+        result = value
+        raise @reason if @reason
+        result
+      end
     end
 
-    def wait(timeout)
-      execute_task_once
-      super timeout
+    # Return the value this object represents after applying the options
+    # specified by the `#set_deref_options` method.
+    #
+    # @param [Integer] timeout (nil) the maximum number of seconds to wait for
+    #   the value to be computed. When `nil` the caller will block indefinitely.
+    #
+    # @return [Object] self
+    #
+    # @!macro delay_note_regarding_blocking
+    def wait(timeout = nil)
+      if @task_executor
+        execute_task_once
+        super(timeout)
+      else
+        value
+      end
+      self
     end
 
-    # reconfigures the block returning the value if still #incomplete?
+    # Reconfigures the block returning the value if still `#incomplete?`
+    #
     # @yield the delayed operation to perform
     # @return [true, false] if success
     def reconfigure(&block)
-      mutex.lock
-      raise ArgumentError.new('no block given') unless block_given?
-      unless @computing
-        @task = block
-        true
-      else
-        false
+      mutex.synchronize do
+        raise ArgumentError.new('no block given') unless block_given?
+        unless @computing
+          @task = block
+          true
+        else
+          false
+        end
       end
-    ensure
-      mutex.unlock
+    end
+
+    protected
+
+    def ns_initialize(opts, &block)
+      init_obligation(self)
+      set_deref_options(opts)
+      @task_executor = Executor.executor_from_options(opts)
+
+      @task      = block
+      @state     = :pending
+      @computing = false
     end
 
     private
 
-    def execute_task_once
-      mutex.lock
-      execute = @computing = true unless @computing
-      task    = @task
-      mutex.unlock
+    # @!visibility private
+    def execute_task_once # :nodoc:
+      # this function has been optimized for performance and
+      # should not be modified without running new benchmarks
+      execute = task = nil
+      mutex.synchronize do
+        execute = @computing = true unless @computing
+        task    = @task
+      end
 
       if execute
         @task_executor.post do
@@ -93,10 +184,10 @@ module Concurrent
           rescue => ex
             reason = ex
           end
-          mutex.lock
-          set_state success, result, reason
-          event.set
-          mutex.unlock
+          mutex.synchronize do
+            set_state(success, result, reason)
+            event.set
+          end
         end
       end
     end