concurrent-ruby 0.7.0-java

data/lib/concurrent/collection/ring_buffer.rb

@@ -0,0 +1,59 @@
+module Concurrent
+
+  # non-thread safe buffer
+  class RingBuffer
+
+    def initialize(capacity)
+      @buffer = Array.new(capacity)
+      @first = @last = 0
+      @count = 0
+    end
+
+
+    # @return [Integer] the capacity of the buffer
+    def capacity
+      @buffer.size
+    end
+
+    # @return [Integer] the number of elements currently in the buffer
+    def count
+      @count
+    end
+
+    # @return [Boolean] true if buffer is empty, false otherwise
+    def empty?
+      @count == 0
+    end
+
+    # @return [Boolean] true if buffer is full, false otherwise
+    def full?
+      @count == capacity
+    end
+
+    # @param [Object] value
+    # @return [Boolean] true if value has been inserted, false otherwise
+    def offer(value)
+      return false if full?
+
+      @buffer[@last] = value
+      @last = (@last + 1) % @buffer.size
+      @count += 1
+      true
+    end
+
+    # @return [Object] the first available value and removes it from the buffer. If buffer is empty returns nil
+    def poll
+      result = @buffer[@first]
+      @buffer[@first] = nil
+      @first = (@first + 1) % @buffer.size
+      @count -= 1
+      result
+    end
+
+    # @return [Object] the first available value and without removing it from the buffer. If buffer is empty returns nil
+    def peek
+      @buffer[@first]
+    end
+
+  end
+end

data/lib/concurrent/collections.rb

@@ -0,0 +1,3 @@
+require 'concurrent/collection/priority_queue'
+require 'concurrent/collection/ring_buffer'
+require 'concurrent/collection/blocking_ring_buffer'

data/lib/concurrent/configuration.rb

@@ -0,0 +1,161 @@
+require 'thread'
+require 'concurrent/delay'
+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'
+
+module Concurrent
+  extend Logging
+
+  # A gem-level configuration object.
+  class Configuration
+
+    # a proc defining how to log messages, its interface has to be:
+    #   lambda { |level, progname, message = nil, &block| _ }
+    attr_accessor :logger
+
+    # 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
+    end
+
+    # if assigned to {#logger}, it will log nothing.
+    def no_logger
+      lambda { |level, progname, message = nil, &block| }
+    end
+
+    # Global thread pool optimized for short *tasks*.
+    #
+    # @return [ThreadPoolExecutor] the thread pool
+    def global_task_pool
+      @global_task_pool.value
+    end
+
+    # Global thread pool optimized for long *operations*.
+    #
+    # @return [ThreadPoolExecutor] the thread pool
+    def global_operation_pool
+      @global_operation_pool.value
+    end
+
+    # Global thread pool optimized for *timers*
+    #
+    # @return [ThreadPoolExecutor] the thread pool
+    #
+    # @see Concurrent::timer
+    def global_timer_set
+      @global_timer_set.value
+    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
+    def global_task_pool=(executor)
+      @global_task_pool.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
+    def global_operation_pool=(executor)
+      @global_operation_pool.reconfigure { executor } or
+          raise ConfigurationError.new('global operation pool was already set')
+    end
+
+    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
+          overflow_policy: :abort # raise an exception
+      )
+    end
+
+    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,
+          overflow_policy: :abort # raise an exception
+      )
+    end
+  end
+
+  # create the default configuration on load
+  @configuration = Atomic.new Configuration.new
+
+  # @return [Configuration]
+  def self.configuration
+    @configuration.value
+  end
+
+  # Perform gem-level configuration.
+  #
+  # @yield the configuration commands
+  # @yieldparam [Configuration] the current configuration object
+  def self.configure
+    yield(configuration)
+  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
+    self.finalize_executor(self.configuration.global_timer_set)
+    self.finalize_executor(self.configuration.global_task_pool)
+    self.finalize_executor(self.configuration.global_operation_pool)
+    # TODO may break other test suites using concurrent-ruby, terminates before test is run
+  end
+end

data/lib/concurrent/dataflow.rb

@@ -0,0 +1,108 @@
+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_operation_pool, *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.configuration.global_task_pool, *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?
+    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.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/delay.rb

@@ -0,0 +1,104 @@
+require 'thread'
+require 'concurrent/obligation'
+require 'concurrent/options_parser'
+
+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)
+      @task_executor = OptionsParser.get_task_executor_from(opts)
+      @computing     = false
+    end
+
+    def wait(timeout)
+      execute_task_once
+      super timeout
+    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?
+      unless @computing
+        @task = block
+        true
+      else
+        false
+      end
+    ensure
+      mutex.unlock
+    end
+
+    private
+
+    def execute_task_once
+      mutex.lock
+      execute = @computing = true unless @computing
+      task    = @task
+      mutex.unlock
+
+      if execute
+        @task_executor.post do
+          begin
+            result  = task.call
+            success = true
+          rescue => ex
+            reason = ex
+          end
+          mutex.lock
+          set_state success, result, reason
+          event.set
+          mutex.unlock
+        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