o-concurrent-ruby 1.1.11

data/lib/concurrent-ruby/concurrent/concern/dereferenceable.rb

@@ -0,0 +1,73 @@
+module Concurrent
+  module Concern
+
+    # Object references in Ruby are mutable. This can lead to serious problems when
+    # the `#value` of a concurrent object is a mutable reference. Which is always the
+    # case unless the value is a `Fixnum`, `Symbol`, or similar "primitive" data type.
+    # Most classes in this library that expose a `#value` getter method do so using the
+    # `Dereferenceable` mixin module.
+    #
+    # @!macro copy_options
+    module Dereferenceable
+      # NOTE: This module is going away in 2.0. In the mean time we need it to
+      # play nicely with the synchronization layer. This means that the
+      # including class SHOULD be synchronized and it MUST implement a
+      # `#synchronize` method. Not doing so will lead to runtime errors.
+
+      # Return the value this object represents after applying the options specified
+      # by the `#set_deref_options` method.
+      #
+      # @return [Object] the current value of the object
+      def value
+        synchronize { apply_deref_options(@value) }
+      end
+      alias_method :deref, :value
+
+      protected
+
+      # Set the internal value of this object
+      #
+      # @param [Object] value the new value
+      def value=(value)
+        synchronize{ @value = value }
+      end
+
+      # @!macro dereferenceable_set_deref_options
+      #   Set the options which define the operations #value performs before
+      #   returning data to the caller (dereferencing).
+      #
+      #   @note Most classes that include this module will call `#set_deref_options`
+      #     from within the constructor, thus allowing these options to be set at
+      #     object creation.
+      #
+      #   @param [Hash] opts the options defining dereference behavior.
+      #   @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
+      def set_deref_options(opts = {})
+        synchronize{ ns_set_deref_options(opts) }
+      end
+
+      # @!macro dereferenceable_set_deref_options
+      # @!visibility private
+      def ns_set_deref_options(opts)
+        @dup_on_deref = opts[:dup_on_deref] || opts[:dup]
+        @freeze_on_deref = opts[:freeze_on_deref] || opts[:freeze]
+        @copy_on_deref = opts[:copy_on_deref] || opts[:copy]
+        @do_nothing_on_deref = !(@dup_on_deref || @freeze_on_deref || @copy_on_deref)
+        nil
+      end
+
+      # @!visibility private
+      def apply_deref_options(value)
+        return nil if value.nil?
+        return value if @do_nothing_on_deref
+        value = @copy_on_deref.call(value) if @copy_on_deref
+        value = value.dup if @dup_on_deref
+        value = value.freeze if @freeze_on_deref
+        value
+      end
+    end
+  end
+end

data/lib/concurrent-ruby/concurrent/concern/logging.rb

@@ -0,0 +1,32 @@
+require 'logger'
+
+module Concurrent
+  module Concern
+
+    # Include where logging is needed
+    #
+    # @!visibility private
+    module Logging
+      include Logger::Severity
+
+      # Logs through {Concurrent.global_logger}, it can be overridden by setting @logger
+      # @param [Integer] level one of Logger::Severity constants
+      # @param [String] progname e.g. a path of an Actor
+      # @param [String, nil] message when nil block is used to generate the message
+      # @yieldreturn [String] a message
+      def log(level, progname, message = nil, &block)
+        #NOTE: Cannot require 'concurrent/configuration' above due to circular references.
+        #      Assume that the gem has been initialized if we've gotten this far.
+        logger = if defined?(@logger) && @logger
+                   @logger
+                 else
+                   Concurrent.global_logger
+                 end
+        logger.call level, progname, message, &block
+      rescue => error
+        $stderr.puts "`Concurrent.configuration.logger` failed to log #{[level, progname, message, block]}\n" +
+          "#{error.message} (#{error.class})\n#{error.backtrace.join "\n"}"
+      end
+    end
+  end
+end

data/lib/concurrent-ruby/concurrent/concern/obligation.rb

@@ -0,0 +1,220 @@
+require 'thread'
+require 'timeout'
+
+require 'concurrent/atomic/event'
+require 'concurrent/concern/dereferenceable'
+
+module Concurrent
+  module Concern
+
+    module Obligation
+      include Concern::Dereferenceable
+      # NOTE: The Dereferenceable module is going away in 2.0. In the mean time
+      # we need it to place nicely with the synchronization layer. This means
+      # that the including class SHOULD be synchronized and it MUST implement a
+      # `#synchronize` method. Not doing so will lead to runtime errors.
+
+      # Has the obligation been fulfilled?
+      #
+      # @return [Boolean]
+      def fulfilled?
+        state == :fulfilled
+      end
+      alias_method :realized?, :fulfilled?
+
+      # Has the obligation been rejected?
+      #
+      # @return [Boolean]
+      def rejected?
+        state == :rejected
+      end
+
+      # Is obligation completion still pending?
+      #
+      # @return [Boolean]
+      def pending?
+        state == :pending
+      end
+
+      # Is the obligation still unscheduled?
+      #
+      # @return [Boolean]
+      def unscheduled?
+        state == :unscheduled
+      end
+
+      # Has the obligation completed processing?
+      #
+      # @return [Boolean]
+      def complete?
+        [:fulfilled, :rejected].include? state
+      end
+
+      # Is the obligation still awaiting completion of processing?
+      #
+      # @return [Boolean]
+      def incomplete?
+        ! complete?
+      end
+
+      # The current value of the obligation. Will be `nil` while the state is
+      # pending or the operation has been rejected.
+      #
+      # @param [Numeric] timeout the maximum time in seconds to wait.
+      # @return [Object] see Dereferenceable#deref
+      def value(timeout = nil)
+        wait timeout
+        deref
+      end
+
+      # Wait until obligation is complete or the timeout has been reached.
+      #
+      # @param [Numeric] timeout the maximum time in seconds to wait.
+      # @return [Obligation] self
+      def wait(timeout = nil)
+        event.wait(timeout) if timeout != 0 && incomplete?
+        self
+      end
+
+      # Wait until obligation is complete or the timeout is reached. Will re-raise
+      # any exceptions raised during processing (but will not raise an exception
+      # on timeout).
+      #
+      # @param [Numeric] timeout the maximum time in seconds to wait.
+      # @return [Obligation] self
+      # @raise [Exception] raises the reason when rejected
+      def wait!(timeout = nil)
+        wait(timeout).tap { raise self if rejected? }
+      end
+      alias_method :no_error!, :wait!
+
+      # The current value of the obligation. Will be `nil` while the state is
+      # pending or the operation has been rejected. Will re-raise any exceptions
+      # raised during processing (but will not raise an exception on timeout).
+      #
+      # @param [Numeric] timeout the maximum time in seconds to wait.
+      # @return [Object] see Dereferenceable#deref
+      # @raise [Exception] raises the reason when rejected
+      def value!(timeout = nil)
+        wait(timeout)
+        if rejected?
+          raise self
+        else
+          deref
+        end
+      end
+
+      # The current state of the obligation.
+      #
+      # @return [Symbol] the current state
+      def state
+        synchronize { @state }
+      end
+
+      # If an exception was raised during processing this will return the
+      # exception object. Will return `nil` when the state is pending or if
+      # the obligation has been successfully fulfilled.
+      #
+      # @return [Exception] the exception raised during processing or `nil`
+      def reason
+        synchronize { @reason }
+      end
+
+      # @example allows Obligation to be risen
+      #   rejected_ivar = Ivar.new.fail
+      #   raise rejected_ivar
+      def exception(*args)
+        raise 'obligation is not rejected' unless rejected?
+        reason.exception(*args)
+      end
+
+      protected
+
+      # @!visibility private
+      def get_arguments_from(opts = {})
+        [*opts.fetch(:args, [])]
+      end
+
+      # @!visibility private
+      def init_obligation
+        @event = Event.new
+        @value = @reason = nil
+      end
+
+      # @!visibility private
+      def event
+        @event
+      end
+
+      # @!visibility private
+      def set_state(success, value, reason)
+        if success
+          @value = value
+          @state = :fulfilled
+        else
+          @reason = reason
+          @state  = :rejected
+        end
+      end
+
+      # @!visibility private
+      def state=(value)
+        synchronize { ns_set_state(value) }
+      end
+
+      # Atomic compare and set operation
+      # State is set to `next_state` only if `current state == expected_current`.
+      #
+      # @param [Symbol] next_state
+      # @param [Symbol] expected_current
+      #
+      # @return [Boolean] true is state is changed, false otherwise
+      #
+      # @!visibility private
+      def compare_and_set_state(next_state, *expected_current)
+        synchronize do
+          if expected_current.include? @state
+            @state = next_state
+            true
+          else
+            false
+          end
+        end
+      end
+
+      # Executes the block within mutex if current state is included in expected_states
+      #
+      # @return block value if executed, false otherwise
+      #
+      # @!visibility private
+      def if_state(*expected_states)
+        synchronize do
+          raise ArgumentError.new('no block given') unless block_given?
+
+          if expected_states.include? @state
+            yield
+          else
+            false
+          end
+        end
+      end
+
+      protected
+
+      # Am I in the current state?
+      #
+      # @param [Symbol] expected The state to check against
+      # @return [Boolean] true if in the expected state else false
+      #
+      # @!visibility private
+      def ns_check_state?(expected)
+        @state == expected
+      end
+
+      # @!visibility private
+      def ns_set_state(value)
+        @state = value
+      end
+    end
+  end
+end

data/lib/concurrent-ruby/concurrent/concern/observable.rb

@@ -0,0 +1,110 @@
+require 'concurrent/collection/copy_on_notify_observer_set'
+require 'concurrent/collection/copy_on_write_observer_set'
+
+module Concurrent
+  module Concern
+
+    # The [observer pattern](http://en.wikipedia.org/wiki/Observer_pattern) is one
+    # of the most useful design patterns.
+    #
+    # The workflow is very simple:
+    # - an `observer` can register itself to a `subject` via a callback
+    # - many `observers` can be registered to the same `subject`
+    # - the `subject` notifies all registered observers when its status changes
+    # - an `observer` can deregister itself when is no more interested to receive
+    #     event notifications
+    #
+    # In a single threaded environment the whole pattern is very easy: the
+    # `subject` can use a simple data structure to manage all its subscribed
+    # `observer`s and every `observer` can react directly to every event without
+    # caring about synchronization.
+    #
+    # In a multi threaded environment things are more complex. The `subject` must
+    # synchronize the access to its data structure and to do so currently we're
+    # using two specialized ObserverSet: {Concurrent::Concern::CopyOnWriteObserverSet}
+    # and {Concurrent::Concern::CopyOnNotifyObserverSet}.
+    #
+    # When implementing and `observer` there's a very important rule to remember:
+    # **there are no guarantees about the thread that will execute the callback**
+    #
+    # Let's take this example
+    # ```
+    # class Observer
+    #   def initialize
+    #     @count = 0
+    #   end
+    #
+    #   def update
+    #     @count += 1
+    #   end
+    # end
+    #
+    # obs = Observer.new
+    # [obj1, obj2, obj3, obj4].each { |o| o.add_observer(obs) }
+    # # execute [obj1, obj2, obj3, obj4]
+    # ```
+    #
+    # `obs` is wrong because the variable `@count` can be accessed by different
+    # threads at the same time, so it should be synchronized (using either a Mutex
+    # or an AtomicFixum)
+    module Observable
+
+      # @!macro observable_add_observer
+      #
+      #   Adds an observer to this set. If a block is passed, the observer will be
+      #   created by this method and no other params should be passed.
+      #
+      #   @param [Object] observer the observer to add
+      #   @param [Symbol] func the function to call on the observer during notification.
+      #     Default is :update
+      #   @return [Object] the added observer
+      def add_observer(observer = nil, func = :update, &block)
+        observers.add_observer(observer, func, &block)
+      end
+
+      # As `#add_observer` but can be used for chaining.
+      #
+      # @param [Object] observer the observer to add
+      # @param [Symbol] func the function to call on the observer during notification.
+      # @return [Observable] self
+      def with_observer(observer = nil, func = :update, &block)
+        add_observer(observer, func, &block)
+        self
+      end
+
+      # @!macro observable_delete_observer
+      #
+      #   Remove `observer` as an observer on this object so that it will no
+      #   longer receive notifications.
+      #
+      #   @param [Object] observer the observer to remove
+      #   @return [Object] the deleted observer
+      def delete_observer(observer)
+        observers.delete_observer(observer)
+      end
+
+      # @!macro observable_delete_observers
+      #
+      #   Remove all observers associated with this object.
+      #
+      #   @return [Observable] self
+      def delete_observers
+        observers.delete_observers
+        self
+      end
+
+      # @!macro observable_count_observers
+      #
+      #   Return the number of observers associated with this object.
+      #
+      #   @return [Integer] the observers count
+      def count_observers
+        observers.count_observers
+      end
+
+      protected
+
+      attr_accessor :observers
+    end
+  end
+end

data/lib/concurrent-ruby/concurrent/configuration.rb

@@ -0,0 +1,188 @@
+require 'thread'
+require 'concurrent/delay'
+require 'concurrent/errors'
+require 'concurrent/atomic/atomic_reference'
+require 'concurrent/concern/logging'
+require 'concurrent/concern/deprecation'
+require 'concurrent/executor/immediate_executor'
+require 'concurrent/executor/cached_thread_pool'
+require 'concurrent/utility/processor_counter'
+
+module Concurrent
+  extend Concern::Logging
+  extend Concern::Deprecation
+
+  autoload :Options, 'concurrent/options'
+  autoload :TimerSet, 'concurrent/executor/timer_set'
+  autoload :ThreadPoolExecutor, 'concurrent/executor/thread_pool_executor'
+
+  # @return [Logger] Logger with provided level and output.
+  def self.create_simple_logger(level = Logger::FATAL, output = $stderr)
+    # TODO (pitr-ch 24-Dec-2016): figure out why it had to be replaced, stdlogger was deadlocking
+    lambda do |severity, progname, message = nil, &block|
+      return false if severity < level
+
+      message           = block ? block.call : message
+      formatted_message = case message
+                          when String
+                            message
+                          when Exception
+                            format "%s (%s)\n%s",
+                                   message.message, message.class, (message.backtrace || []).join("\n")
+                          else
+                            message.inspect
+                          end
+
+      output.print format "[%s] %5s -- %s: %s\n",
+                          Time.now.strftime('%Y-%m-%d %H:%M:%S.%L'),
+                          Logger::SEV_LABEL[severity],
+                          progname,
+                          formatted_message
+      true
+    end
+  end
+
+  # Use logger created by #create_simple_logger to log concurrent-ruby messages.
+  def self.use_simple_logger(level = Logger::FATAL, output = $stderr)
+    Concurrent.global_logger = create_simple_logger level, output
+  end
+
+  # @return [Logger] Logger with provided level and output.
+  # @deprecated
+  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
+
+    lambda do |loglevel, progname, message = nil, &block|
+      logger.add loglevel, message, progname, &block
+    end
+  end
+
+  # Use logger created by #create_stdlib_logger to log concurrent-ruby messages.
+  # @deprecated
+  def self.use_stdlib_logger(level = Logger::FATAL, output = $stderr)
+    Concurrent.global_logger = create_stdlib_logger level, output
+  end
+
+  # TODO (pitr-ch 27-Dec-2016): remove deadlocking stdlib_logger methods
+
+  # Suppresses all output when used for logging.
+  NULL_LOGGER   = lambda { |level, progname, message = nil, &block| }
+
+  # @!visibility private
+  GLOBAL_LOGGER = AtomicReference.new(create_simple_logger(Logger::WARN))
+  private_constant :GLOBAL_LOGGER
+
+  def self.global_logger
+    GLOBAL_LOGGER.value
+  end
+
+  def self.global_logger=(value)
+    GLOBAL_LOGGER.value = value
+  end
+
+  # @!visibility private
+  GLOBAL_FAST_EXECUTOR = Delay.new { Concurrent.new_fast_executor }
+  private_constant :GLOBAL_FAST_EXECUTOR
+
+  # @!visibility private
+  GLOBAL_IO_EXECUTOR = Delay.new { Concurrent.new_io_executor }
+  private_constant :GLOBAL_IO_EXECUTOR
+
+  # @!visibility private
+  GLOBAL_TIMER_SET = Delay.new { TimerSet.new }
+  private_constant :GLOBAL_TIMER_SET
+
+  # @!visibility private
+  GLOBAL_IMMEDIATE_EXECUTOR = ImmediateExecutor.new
+  private_constant :GLOBAL_IMMEDIATE_EXECUTOR
+
+  # Disables AtExit handlers including pool auto-termination handlers.
+  # When disabled it will be the application programmer's responsibility
+  # to ensure that the handlers 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.
+  # @deprecated Has no effect since it is no longer needed, see https://github.com/ruby-concurrency/concurrent-ruby/pull/841.
+  #
+  def self.disable_at_exit_handlers!
+    deprecated "Method #disable_at_exit_handlers! has no effect since it is no longer needed, see https://github.com/ruby-concurrency/concurrent-ruby/pull/841."
+  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
+  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)
+    Options.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
+        name:            "fast"
+    )
+  end
+
+  def self.new_io_executor(opts = {})
+    CachedThreadPool.new(
+        auto_terminate:  opts.fetch(:auto_terminate, true),
+        fallback_policy: :abort, # shouldn't matter -- 0 max queue
+        name:            "io"
+    )
+  end
+end

data/lib/concurrent-ruby/concurrent/constants.rb

@@ -0,0 +1,8 @@
+module Concurrent
+
+  # Various classes within allows for +nil+ values to be stored,
+  # so a special +NULL+ token is required to indicate the "nil-ness".
+  # @!visibility private
+  NULL = ::Object.new
+
+end