concurrent-ruby 0.7.0.rc0-x86-linux

data/lib/concurrent/dataflow.rb

@@ -0,0 +1,91 @@
+require 'concurrent/future'
+require 'concurrent/atomic/atomic_fixnum'
+require 'concurrent/executor/per_thread_executor'
+
+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 then all of its
+  # data dependencies are available. Data dependencies are `Future` values. The
+  # dataflow task itself is also a `Future` value, so you can build up a graph of
+  # these tasks, each of which is run when all the data and other tasks it depends
+  # on are available or completed.
+  #
+  # Our syntax is somewhat related to that of Akka's `flow` and Habanero Java's
+  # `DataDrivenFuture`. However unlike Akka we don't schedule a task at all until
+  # it is ready to run, and unlike Habanero Java we pass the data values into the
+  # task instead of dereferencing them again in the task.
+  #
+  # The theory of dataflow goes back to the 80s. In the terminology of the literature,
+  # our implementation is coarse-grained, in that each task can be many instructions,
+  # and dynamic in that you can create more tasks within other tasks.
+  #
+  # @example Parallel Fibonacci calculator
+  #   def fib(n)
+  #     if n < 2
+  #       Concurrent::dataflow { n }
+  #     else
+  #       n1 = fib(n - 1)
+  #       n2 = fib(n - 2)
+  #       Concurrent::dataflow(n1, n2) { |v1, v2| v1 + v2 }
+  #     end
+  #   end
+  #   
+  #   f = fib(14) #=> #<Concurrent::Future:0x000001019a26d8 ...
+  #   
+  #   # wait up to 1 second for the answer...
+  #   f.value(1) #=> 377
+  #
+  # @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.configuration.global_task_pool, *inputs, &block)
+  end
+  module_function :dataflow
+
+  def dataflow_with(executor, *inputs, &block)
+    raise ArgumentError.new('an executor must be provided') if executor.nil?
+    raise ArgumentError.new('no block given') unless block_given?
+    raise ArgumentError.new('not all dependencies are IVars') unless inputs.all? { |input| input.is_a? IVar }
+
+    result = Future.new(executor: executor) do
+      values = inputs.map { |input| input.value }
+      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 :dataflow_with
+end

data/lib/concurrent/delay.rb

@@ -0,0 +1,112 @@
+require 'thread'
+require 'concurrent/obligation'
+
+module Concurrent
+
+  # Lazy evaluation of a block yielding an immutable result. Useful for expensive
+  # operations that may never be needed.
+  #
+  # 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
+  # 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::Dereferenceable` mixin to support thread
+  # safety of the reference returned by `#value`.
+  #
+  # @since 0.6.0
+  #
+  # @see Concurrent::Dereferenceable
+  #
+  # @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
+
+    # Create a new `Delay` in the `:pending` state.
+    #
+    # @yield the delayed operation to perform
+    #
+    # @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
+    #
+    # @raise [ArgumentError] if no block is given
+    def initialize(opts = {}, &block)
+      raise ArgumentError.new('no block given') unless block_given?
+
+      init_obligation
+      @state = :pending
+      @task  = block
+      set_deref_options(opts)
+    end
+
+    # Return the (possibly memoized) value of the delayed operation.
+    # 
+    # If the state is `:pending` then the calling thread will block while the
+    # operation is performed. All other threads simultaneously calling `#value`
+    # will block as well. Once the operation is complete (either `:fulfilled` or
+    # `:rejected`) all waiting threads will unblock and the new value will be
+    # returned.
+    #
+    # If the state is not `:pending` when `#value` is called the (possibly memoized)
+    # value will be returned without blocking and without performing the operation
+    # again.
+    #
+    # Regardless of the final disposition all `Dereferenceable` options set during
+    # object construction will be honored.
+    #
+    # @return [Object] the (possibly memoized) result of the block operation
+    #
+    # @see Concurrent::Dereferenceable
+    def value
+      mutex.lock
+      execute_task_once
+      apply_deref_options(@value)
+    ensure
+      mutex.unlock
+    end
+
+    # 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?
+      if @state == :pending
+        @task = block
+        true
+      else
+        false
+      end
+    ensure
+      mutex.unlock
+    end
+
+    private
+
+    def execute_task_once
+      if @state == :pending
+        begin
+          @value = @task.call
+          @state = :fulfilled
+        rescue => ex
+          @reason = ex
+          @state  = :rejected
+        end
+      end
+    end
+  end
+end

data/lib/concurrent/dereferenceable.rb

@@ -0,0 +1,101 @@
+module Concurrent
+
+  # 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
+  # this mixin module.
+  module Dereferenceable
+
+    # Return the value this object represents after applying the options specified
+    # by the `#set_deref_options` method.
+    #
+    # When multiple deref options are set the order of operations is strictly defined.
+    # The order of deref operations is:
+    # * `:copy_on_deref`
+    # * `:dup_on_deref`
+    # * `:freeze_on_deref`
+    #
+    # Because of this ordering there is no need to `#freeze` an object created by a
+    # provided `:copy_on_deref` block. Simply set `:freeze_on_deref` to `true`.
+    # Setting both `:dup_on_deref` to `true` and `:freeze_on_deref` to `true` is
+    # as close to the behavior of a "pure" functional language (like Erlang, Clojure,
+    # or Haskell) as we are likely to get in Ruby.
+    # 
+    # This method is thread-safe and synchronized with the internal `#mutex`.
+    #
+    # @return [Object] the current value of the object
+    def value
+      mutex.lock
+      apply_deref_options(@value)
+    ensure
+      mutex.unlock
+    end
+
+    alias_method :deref, :value
+
+    protected
+
+    # Set the internal value of this object
+    #
+    # @param [Object] val the new value
+    def value=(val)
+      mutex.lock
+      @value = val
+    ensure
+      mutex.unlock
+    end
+
+    # A mutex lock used for synchronizing thread-safe operations. Methods defined
+    # by `Dereferenceable` are synchronized using the `Mutex` returned from this
+    # method. Operations performed by the including class that operate on the
+    # `@value` instance variable should be locked with this `Mutex`.
+    #
+    # @return [Mutex] the synchronization object
+    def mutex
+      @mutex
+    end
+
+    # Initializes the internal `Mutex`. 
+    #
+    # @note This method *must* be called from within the constructor of the including class.
+    #
+    # @see #mutex
+    def init_mutex
+      @mutex = Mutex.new
+    end
+
+    # 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 = {})
+      mutex.lock
+      @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
+    ensure
+      mutex.unlock
+    end
+
+    # @!visibility private
+    def apply_deref_options(value) # :nodoc:
+      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

data/lib/concurrent/errors.rb

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

data/lib/concurrent/exchanger.rb

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

data/lib/concurrent/executor/cached_thread_pool.rb

@@ -0,0 +1,44 @@
+require 'concurrent/executor/ruby_cached_thread_pool'
+
+module Concurrent
+
+  if RUBY_PLATFORM == 'java'
+    require 'concurrent/executor/java_cached_thread_pool'
+    # @!macro [attach] cached_thread_pool
+    #   A thread pool that dynamically grows and shrinks to fit the current workload.
+    #   New threads are created as needed, existing threads are reused, and threads
+    #   that remain idle for too long are killed and removed from the pool. These
+    #   pools are particularly suited to applications that perform a high volume of
+    #   short-lived tasks.
+    #
+    #   On creation a `CachedThreadPool` has zero running threads. New threads are
+    #   created on the pool as new operations are `#post`. The size of the pool
+    #   will grow until `#max_length` threads are in the pool or until the number
+    #   of threads exceeds the number of running and pending operations. When a new
+    #   operation is post to the pool the first available idle thread will be tasked
+    #   with the new operation.
+    #
+    #   Should a thread crash for any reason the thread will immediately be removed
+    #   from the pool. Similarly, threads which remain idle for an extended period
+    #   of time will be killed and reclaimed. Thus these thread pools are very
+    #   efficient at reclaiming unused resources.
+    #
+    #   The API and behavior of this class are based on Java's `CachedThreadPool`
+    #
+    #   @note When running on the JVM (JRuby) this class will inherit from `JavaCachedThreadPool`.
+    #     On all other platforms it will inherit from `RubyCachedThreadPool`.
+    #
+    #   @see Concurrent::RubyCachedThreadPool
+    #   @see Concurrent::JavaCachedThreadPool
+    #
+    #   @see http://docs.oracle.com/javase/tutorial/essential/concurrency/pools.html
+    #   @see http://docs.oracle.com/javase/7/docs/api/java/util/concurrent/Executors.html
+    #   @see http://docs.oracle.com/javase/8/docs/api/java/util/concurrent/ExecutorService.html
+    class CachedThreadPool < JavaCachedThreadPool
+    end
+  else
+    # @!macro cached_thread_pool
+    class CachedThreadPool < RubyCachedThreadPool
+    end
+  end
+end

data/lib/concurrent/executor/executor.rb

@@ -0,0 +1,229 @@
+require 'concurrent/errors'
+require 'concurrent/logging'
+require 'concurrent/atomic/event'
+
+module Concurrent
+
+  module Executor
+    def can_overflow?
+      false
+    end
+  end
+
+  module RubyExecutor
+    include Executor
+    include Logging
+
+    # Submit a task to the executor for asynchronous processing.
+    #
+    # @param [Array] args zero or more arguments to be passed to the task
+    #
+    # @yield the asynchronous task to perform
+    #
+    # @return [Boolean] `true` if the task is queued, `false` if the executor
+    #   is not running
+    #
+    # @raise [ArgumentError] if no task is given
+    def post(*args, &task)
+      raise ArgumentError.new('no block given') unless block_given?
+      mutex.synchronize do
+        return false unless running?
+        execute(*args, &task)
+        true
+      end
+    end
+
+    # 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
+
+    # Is the executor running?
+    #
+    # @return [Boolean] `true` when running, `false` when shutting down or shutdown
+    def running?
+      ! stop_event.set?
+    end
+
+    # Is the executor shuttingdown?
+    #
+    # @return [Boolean] `true` when not running and not shutdown, else `false`
+    def shuttingdown?
+      ! (running? || shutdown?)
+    end
+
+    # Is the executor shutdown?
+    #
+    # @return [Boolean] `true` when shutdown, `false` when shutting down or running
+    def shutdown?
+      stopped_event.set?
+    end
+
+    # 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
+
+    # 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
+
+    # 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
+
+    def init_executor
+      @mutex = Mutex.new
+      @stop_event = Event.new
+      @stopped_event = Event.new
+    end
+
+    def execute(*args, &task)
+      raise NotImplementedError
+    end
+
+    def shutdown_execution
+      stopped_event.set
+    end
+
+    def kill_execution
+      # do nothing
+    end
+  end
+
+  if RUBY_PLATFORM == 'java'
+
+    module JavaExecutor
+      include Executor
+
+      # 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)
+        raise ArgumentError.new('no block given') unless block_given?
+        if running?
+          @executor.submit{ yield(*args) }
+          true
+        else
+          false
+        end
+      rescue Java::JavaUtilConcurrent::RejectedExecutionException => ex
+        raise RejectedExecutionError
+      end
+
+      # 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
+
+      # Is the executor running?
+      #
+      # @return [Boolean] `true` when running, `false` when shutting down or shutdown
+      def running?
+        ! (shuttingdown? || shutdown?)
+      end
+
+      # Is the executor shuttingdown?
+      #
+      # @return [Boolean] `true` when not running and not shutdown, else `false`
+      def shuttingdown?
+        if @executor.respond_to? :isTerminating
+          @executor.isTerminating
+        else
+          false
+        end
+      end
+
+      # Is the executor shutdown?
+      #
+      # @return [Boolean] `true` when shutdown, `false` when shutting down or running
+      def shutdown?
+        @executor.isShutdown || @executor.isTerminated
+      end
+
+      # 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)
+        @executor.awaitTermination(1000 * timeout, java.util.concurrent.TimeUnit::MILLISECONDS)
+      end
+
+      # 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
+      # executor is not running.
+      def shutdown
+        @executor.shutdown
+        nil
+      end
+
+      # 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 executor is
+      # not running.
+      def kill
+        @executor.shutdownNow
+        nil
+      end
+
+      protected
+
+      def set_shutdown_hook
+        # without this the process may fail to exit
+        at_exit { self.kill }
+      end
+    end
+  end
+end