o-concurrent-ruby 1.1.11

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

@@ -0,0 +1,81 @@
+require 'concurrent/future'
+require 'concurrent/atomic/atomic_fixnum'
+
+module Concurrent
+
+  # @!visibility private
+  class DependencyCounter # :nodoc:
+
+    def initialize(count, &block)
+      @counter = AtomicFixnum.new(count)
+      @block = block
+    end
+
+    def update(time, value, reason)
+      if @counter.decrement == 0
+        @block.call
+      end
+    end
+  end
+
+  # Dataflow allows you to create a task that will be scheduled when all of its data dependencies are available.
+  # {include:file:docs-source/dataflow.md}
+  #
+  # @param [Future] inputs zero or more `Future` operations that this dataflow depends upon
+  #
+  # @yield The operation to perform once all the dependencies are met
+  # @yieldparam [Future] inputs each of the `Future` inputs to the dataflow
+  # @yieldreturn [Object] the result of the block operation
+  #
+  # @return [Object] the result of all the operations
+  #
+  # @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.global_io_executor, *inputs, &block)
+  end
+  module_function :dataflow
+
+  def dataflow_with(executor, *inputs, &block)
+    call_dataflow(:value, executor, *inputs, &block)
+  end
+  module_function :dataflow_with
+
+  def dataflow!(*inputs, &block)
+    dataflow_with!(Concurrent.global_io_executor, *inputs, &block)
+  end
+  module_function :dataflow!
+
+  def dataflow_with!(executor, *inputs, &block)
+    call_dataflow(:value!, executor, *inputs, &block)
+  end
+  module_function :dataflow_with!
+
+  private
+
+  def call_dataflow(method, executor, *inputs, &block)
+    raise ArgumentError.new('an executor must be provided') if executor.nil?
+    raise ArgumentError.new('no block given') unless block_given?
+    unless inputs.all? { |input| input.is_a? IVar }
+      raise ArgumentError.new("Not all dependencies are IVars.\nDependencies: #{ inputs.inspect }")
+    end
+
+    result = Future.new(executor: executor) do
+      values = inputs.map { |input| input.send(method) }
+      block.call(*values)
+    end
+
+    if inputs.empty?
+      result.execute
+    else
+      counter = DependencyCounter.new(inputs.size) { result.execute }
+
+      inputs.each do |input|
+        input.add_observer counter
+      end
+    end
+
+    result
+  end
+  module_function :call_dataflow
+end

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

@@ -0,0 +1,199 @@
+require 'thread'
+require 'concurrent/concern/obligation'
+require 'concurrent/executor/immediate_executor'
+require 'concurrent/synchronization'
+
+module Concurrent
+
+  # This file has circular require issues. It must be autoloaded here.
+  autoload :Options, 'concurrent/options'
+
+  # 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.
+  #
+  # 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
+  # threads attempting to call `#value` will block as well. Once the operation
+  # is complete the *value* will be set to the result of the operation or the
+  # *reason* will be set to the raised exception, as appropriate. All threads
+  # blocked on `#value` will return. Subsequent calls to `#value` will immediately
+  # 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::Concern::Dereferenceable` mixin to support thread
+  # safety of the reference returned by `#value`.
+  #
+  # @!macro copy_options
+  #
+  # @!macro 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 Concurrent::Concern::Dereferenceable
+  class Delay < Synchronization::LockableObject
+    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.
+    #
+    # @!macro executor_and_deref_options
+    #
+    # @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
+
+    # 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 @executor # TODO (pitr 12-Sep-2015): broken unsafe read?
+        super
+      else
+        # this function has been optimized for performance and
+        # should not be modified without running new benchmarks
+        synchronize do
+          execute = @evaluation_started = true unless @evaluation_started
+          if execute
+            begin
+              set_state(true, @task.call, nil)
+            rescue => ex
+              set_state(false, nil, ex)
+            end
+          elsif incomplete?
+            raise IllegalOperationError, 'Recursive call to #value during evaluation of the Delay'
+          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 @executor
+        super
+      else
+        result = value
+        raise @reason if @reason
+        result
+      end
+    end
+
+    # 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 @executor
+        execute_task_once
+        super(timeout)
+      else
+        value
+      end
+      self
+    end
+
+    # Reconfigures the block returning the value if still `#incomplete?`
+    #
+    # @yield the delayed operation to perform
+    # @return [true, false] if success
+    def reconfigure(&block)
+      synchronize do
+        raise ArgumentError.new('no block given') unless block_given?
+        unless @evaluation_started
+          @task = block
+          true
+        else
+          false
+        end
+      end
+    end
+
+    protected
+
+    def ns_initialize(opts, &block)
+      init_obligation
+      set_deref_options(opts)
+      @executor = opts[:executor]
+
+      @task               = block
+      @state              = :pending
+      @evaluation_started = false
+    end
+
+    private
+
+    # @!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
+      synchronize do
+        execute = @evaluation_started = true unless @evaluation_started
+        task    = @task
+      end
+
+      if execute
+        executor = Options.executor_from_options(executor: @executor)
+        executor.post do
+          begin
+            result  = task.call
+            success = true
+          rescue => ex
+            reason = ex
+          end
+          synchronize do
+            set_state(success, result, reason)
+            event.set
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,69 @@
+module Concurrent
+
+  Error = Class.new(StandardError)
+
+  # Raised when errors occur during configuration.
+  ConfigurationError = Class.new(Error)
+
+  # Raised when an asynchronous operation is cancelled before execution.
+  CancelledOperationError = Class.new(Error)
+
+  # 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(Error)
+
+  # Raised when an attempt is made to violate an immutability guarantee.
+  ImmutabilityError = Class.new(Error)
+
+  # Raised when an operation is attempted which is not legal given the
+  # receiver's current state
+  IllegalOperationError = Class.new(Error)
+
+  # Raised when an object's methods are called when it has not been
+  # properly initialized.
+  InitializationError = Class.new(Error)
+
+  # 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(Error)
+
+  # Raised when an attempt is made to modify an immutable object
+  # (such as an `IVar`) after its final state has been set.
+  class MultipleAssignmentError < Error
+    attr_reader :inspection_data
+
+    def initialize(message = nil, inspection_data = nil)
+      @inspection_data = inspection_data
+      super message
+    end
+
+    def inspect
+      format '%s %s>', super[0..-2], @inspection_data.inspect
+    end
+  end
+
+  # 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(Error)
+
+  # Raised when any finite resource, such as a lock counter, exceeds its
+  # maximum limit/threshold.
+  ResourceLimitError = Class.new(Error)
+
+  # Raised when an operation times out.
+  TimeoutError = Class.new(Error)
+
+  # Aggregates multiple exceptions.
+  class MultipleErrors < Error
+    attr_reader :errors
+
+    def initialize(errors, message = "#{errors.size} errors")
+      @errors = errors
+      super [*message,
+             *errors.map { |e| [format('%s (%s)', e.message, e.class), *e.backtrace] }.flatten(1)
+            ].join("\n")
+    end
+  end
+
+end

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

@@ -0,0 +1,352 @@
+require 'concurrent/constants'
+require 'concurrent/errors'
+require 'concurrent/maybe'
+require 'concurrent/atomic/atomic_reference'
+require 'concurrent/atomic/count_down_latch'
+require 'concurrent/utility/engine'
+require 'concurrent/utility/monotonic_time'
+
+module Concurrent
+
+  # @!macro exchanger
+  #
+  #   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.
+  #
+  #   @!macro thread_safe_variable_comparison
+  #
+  #   This implementation is very simple, using only a single slot for each
+  #   exchanger (unlike more advanced implementations which use an "arena").
+  #   This approach will work perfectly fine when there are only a few threads
+  #   accessing a single `Exchanger`. Beyond a handful of threads the performance
+  #   will degrade rapidly due to contention on the single slot, but the algorithm
+  #   will remain correct.
+  #
+  #   @see http://docs.oracle.com/javase/7/docs/api/java/util/concurrent/Exchanger.html java.util.concurrent.Exchanger
+  #   @example
+  #
+  #     exchanger = Concurrent::Exchanger.new
+  #
+  #     threads = [
+  #       Thread.new { puts "first: " << exchanger.exchange('foo', 1) }, #=> "first: bar"
+  #       Thread.new { puts "second: " << exchanger.exchange('bar', 1) } #=> "second: foo"
+  #     ]
+  #     threads.each {|t| t.join(2) }
+
+  # @!visibility private
+  class AbstractExchanger < Synchronization::Object
+
+    # @!visibility private
+    CANCEL = ::Object.new
+    private_constant :CANCEL
+
+    def initialize
+      super
+    end
+
+    # @!macro exchanger_method_do_exchange
+    #
+    #   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. The timeout value indicates the
+    #   approximate number of seconds the method should block while waiting
+    #   for the exchange. When the timeout value is `nil` the method will
+    #   block indefinitely.
+    #
+    #   @param [Object] value the value to exchange with another thread
+    #   @param [Numeric, nil] timeout in seconds, `nil` blocks indefinitely
+    #
+    # @!macro exchanger_method_exchange
+    #
+    #   In some edge cases when a `timeout` is given a return value of `nil` may be
+    #   ambiguous. Specifically, if `nil` is a valid value in the exchange it will
+    #   be impossible to tell whether `nil` is the actual return value or if it
+    #   signifies timeout. When `nil` is a valid value in the exchange consider
+    #   using {#exchange!} or {#try_exchange} instead.
+    #
+    #   @return [Object] the value exchanged by the other thread or `nil` on timeout
+    def exchange(value, timeout = nil)
+      (value = do_exchange(value, timeout)) == CANCEL ? nil : value
+    end
+
+    # @!macro exchanger_method_do_exchange
+    # @!macro exchanger_method_exchange_bang
+    #
+    #   On timeout a {Concurrent::TimeoutError} exception will be raised.
+    #
+    #   @return [Object] the value exchanged by the other thread
+    #   @raise [Concurrent::TimeoutError] on timeout
+    def exchange!(value, timeout = nil)
+      if (value = do_exchange(value, timeout)) == CANCEL
+        raise Concurrent::TimeoutError
+      else
+        value
+      end
+    end
+
+    # @!macro exchanger_method_do_exchange
+    # @!macro exchanger_method_try_exchange
+    #
+    #   The return value will be a {Concurrent::Maybe} set to `Just` on success or
+    #   `Nothing` on timeout.
+    #
+    #   @return [Concurrent::Maybe] on success a `Just` maybe will be returned with
+    #     the item exchanged by the other thread as `#value`; on timeout a
+    #     `Nothing` maybe will be returned with {Concurrent::TimeoutError} as `#reason`
+    #
+    #   @example
+    #
+    #     exchanger = Concurrent::Exchanger.new
+    #
+    #     result = exchanger.exchange(:foo, 0.5)
+    #
+    #     if result.just?
+    #       puts result.value #=> :bar
+    #     else
+    #       puts 'timeout'
+    #     end
+    def try_exchange(value, timeout = nil)
+      if (value = do_exchange(value, timeout)) == CANCEL
+        Concurrent::Maybe.nothing(Concurrent::TimeoutError)
+      else
+        Concurrent::Maybe.just(value)
+      end
+    end
+
+    private
+
+    # @!macro exchanger_method_do_exchange
+    #
+    # @return [Object, CANCEL] the value exchanged by the other thread; {CANCEL} on timeout
+    def do_exchange(value, timeout)
+      raise NotImplementedError
+    end
+  end
+
+  # @!macro internal_implementation_note
+  # @!visibility private
+  class RubyExchanger < AbstractExchanger
+    # A simplified version of java.util.concurrent.Exchanger written by
+    # Doug Lea, Bill Scherer, and Michael Scott with assistance from members
+    # of JCP JSR-166 Expert Group and released to the public domain. It does
+    # not include the arena or the multi-processor spin loops.
+    # http://grepcode.com/file/repository.grepcode.com/java/root/jdk/openjdk/6-b14/java/util/concurrent/Exchanger.java
+
+    safe_initialization!
+
+    class Node < Concurrent::Synchronization::Object
+      attr_atomic :value
+      safe_initialization!
+
+      def initialize(item)
+        super()
+        @Item      = item
+        @Latch     = Concurrent::CountDownLatch.new
+        self.value = nil
+      end
+
+      def latch
+        @Latch
+      end
+
+      def item
+        @Item
+      end
+    end
+    private_constant :Node
+
+    def initialize
+      super
+    end
+
+    private
+
+    attr_atomic(:slot)
+
+    # @!macro exchanger_method_do_exchange
+    #
+    # @return [Object, CANCEL] the value exchanged by the other thread; {CANCEL} on timeout
+    def do_exchange(value, timeout)
+
+      # ALGORITHM
+      #
+      # From the original Java version:
+      #
+      # > The basic idea is to maintain a "slot", which is a reference to
+      # > a Node containing both an Item to offer and a "hole" waiting to
+      # > get filled in.  If an incoming "occupying" thread sees that the
+      # > slot is null, it CAS'es (compareAndSets) a Node there and waits
+      # > for another to invoke exchange.  That second "fulfilling" thread
+      # > sees that the slot is non-null, and so CASes it back to null,
+      # > also exchanging items by CASing the hole, plus waking up the
+      # > occupying thread if it is blocked.  In each case CAS'es may
+      # > fail because a slot at first appears non-null but is null upon
+      # > CAS, or vice-versa.  So threads may need to retry these
+      # > actions.
+      #
+      # This version:
+      #
+      # An exchange occurs between an "occupier" thread and a "fulfiller" thread.
+      # The "slot" is used to setup this interaction. The first thread in the
+      # exchange puts itself into the slot (occupies) and waits for a fulfiller.
+      # The second thread removes the occupier from the slot and attempts to
+      # perform the exchange. Removing the occupier also frees the slot for
+      # another occupier/fulfiller pair.
+      #
+      # Because the occupier and the fulfiller are operating independently and
+      # because there may be contention with other threads, any failed operation
+      # indicates contention. Both the occupier and the fulfiller operate within
+      # spin loops. Any failed actions along the happy path will cause the thread
+      # to repeat the loop and try again.
+      #
+      # When a timeout value is given the thread must be cognizant of time spent
+      # in the spin loop. The remaining time is checked every loop. When the time
+      # runs out the thread will exit.
+      #
+      # A "node" is the data structure used to perform the exchange. Only the
+      # occupier's node is necessary. It's the node used for the exchange.
+      # Each node has an "item," a "hole" (self), and a "latch." The item is the
+      # node's initial value. It never changes. It's what the fulfiller returns on
+      # success. The occupier's hole is where the fulfiller put its item. It's the
+      # item that the occupier returns on success. The latch is used for synchronization.
+      # Because a thread may act as either an occupier or fulfiller (or possibly
+      # both in periods of high contention) every thread creates a node when
+      # the exchange method is first called.
+      #
+      # The following steps occur within the spin loop. If any actions fail
+      # the thread will loop and try again, so long as there is time remaining.
+      # If time runs out the thread will return CANCEL.
+      #
+      # Check the slot for an occupier:
+      #
+      #   * If the slot is empty try to occupy
+      #   * If the slot is full try to fulfill
+      #
+      # Attempt to occupy:
+      #
+      #   * Attempt to CAS myself into the slot
+      #   * Go to sleep and wait to be woken by a fulfiller
+      #   * If the sleep is successful then the fulfiller completed its happy path
+      #     - Return the value from my hole (the value given by the fulfiller)
+      #   * When the sleep fails (time ran out) attempt to cancel the operation
+      #     - Attempt to CAS myself out of the hole
+      #     - If successful there is no contention
+      #       - Return CANCEL
+      #     - On failure, I am competing with a fulfiller
+      #       - Attempt to CAS my hole to CANCEL
+      #       - On success
+      #         - Let the fulfiller deal with my cancel
+      #         - Return CANCEL
+      #       - On failure the fulfiller has completed its happy path
+      #         - Return th value from my hole (the fulfiller's value)
+      #
+      # Attempt to fulfill:
+      #
+      # * Attempt to CAS the occupier out of the slot
+      #   - On failure loop again
+      # * Attempt to CAS my item into the occupier's hole
+      #   - On failure the occupier is trying to cancel
+      #     - Loop again
+      #   - On success we are on the happy path
+      #     - Wake the sleeping occupier
+      #     - Return the occupier's item
+
+      value  = NULL if value.nil? # The sentinel allows nil to be a valid value
+      me     = Node.new(value) # create my node in case I need to occupy
+      end_at = Concurrent.monotonic_time + timeout.to_f # The time to give up
+
+      result = loop do
+        other = slot
+        if other && compare_and_set_slot(other, nil)
+          # try to fulfill
+          if other.compare_and_set_value(nil, value)
+            # happy path
+            other.latch.count_down
+            break other.item
+          end
+        elsif other.nil? && compare_and_set_slot(nil, me)
+          # try to occupy
+          timeout = end_at - Concurrent.monotonic_time if timeout
+          if me.latch.wait(timeout)
+            # happy path
+            break me.value
+          else
+            # attempt to remove myself from the slot
+            if compare_and_set_slot(me, nil)
+              break CANCEL
+            elsif !me.compare_and_set_value(nil, CANCEL)
+              # I've failed to block the fulfiller
+              break me.value
+            end
+          end
+        end
+        break CANCEL if timeout && Concurrent.monotonic_time >= end_at
+      end
+
+      result == NULL ? nil : result
+    end
+  end
+
+  if Concurrent.on_jruby?
+
+    # @!macro internal_implementation_note
+    # @!visibility private
+    class JavaExchanger < AbstractExchanger
+
+      def initialize
+        @exchanger = java.util.concurrent.Exchanger.new
+      end
+
+      private
+
+      # @!macro exchanger_method_do_exchange
+      #
+      # @return [Object, CANCEL] the value exchanged by the other thread; {CANCEL} on timeout
+      def do_exchange(value, timeout)
+        result = nil
+        if timeout.nil?
+          Synchronization::JRuby.sleep_interruptibly do
+            result = @exchanger.exchange(value)
+          end
+        else
+          Synchronization::JRuby.sleep_interruptibly do
+            result = @exchanger.exchange(value, 1000 * timeout, java.util.concurrent.TimeUnit::MILLISECONDS)
+          end
+        end
+        result
+      rescue java.util.concurrent.TimeoutException
+        CANCEL
+      end
+    end
+  end
+
+  # @!visibility private
+  # @!macro internal_implementation_note
+  ExchangerImplementation = case
+                            when Concurrent.on_jruby?
+                              JavaExchanger
+                            else
+                              RubyExchanger
+                            end
+  private_constant :ExchangerImplementation
+
+  # @!macro exchanger
+  class Exchanger < ExchangerImplementation
+
+    # @!method initialize
+    #   Creates exchanger instance
+
+    # @!method exchange(value, timeout = nil)
+    #   @!macro exchanger_method_do_exchange
+    #   @!macro exchanger_method_exchange
+
+    # @!method exchange!(value, timeout = nil)
+    #   @!macro exchanger_method_do_exchange
+    #   @!macro exchanger_method_exchange_bang
+
+    # @!method try_exchange(value, timeout = nil)
+    #   @!macro exchanger_method_do_exchange
+    #   @!macro exchanger_method_try_exchange
+  end
+end