concurrent-ruby 0.6.0.pre.1 → 0.6.0.pre.2

data/lib/concurrent/{channel → collection}/ring_buffer.rb

@@ -1,6 +1,6 @@
 module Concurrent
 
-  # not thread safe buffer
+  # non-thread safe buffer
   class RingBuffer
 
     def initialize(capacity)
@@ -9,18 +9,23 @@ module Concurrent
       @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

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

@@ -1,29 +1,43 @@
 require 'thread'
-require 'concurrent/thread_pool_executor'
-require 'concurrent/processor_count'
+require 'concurrent/executor/thread_pool_executor'
+require 'concurrent/executor/timer_set'
+require 'concurrent/utility/processor_count'
 
 module Concurrent
 
+  # An error class to be raised when errors occur during configuration.
   ConfigurationError = Class.new(StandardError)
 
   class << self
     attr_accessor :configuration
   end
 
+  # Perform gem-level configuration.
+  #
+  # @yield the configuration commands
+  # @yieldparam [Configuration] the current configuration object
   def self.configure
     (@mutex ||= Mutex.new).synchronize do
       yield(configuration)
+
+      # initialize the global thread pools if necessary
+      configuration.global_task_pool
+      configuration.global_operation_pool
+      configuration.global_timer_set
     end
   end
 
+  # A gem-level configuration object.
   class Configuration
-    attr_accessor :global_task_pool
-    attr_accessor :global_operation_pool
 
+    # Create a new configuration object.
     def initialize
       @cores ||= Concurrent::processor_count
     end
 
+    # Global thread pool optimized for short *tasks*.
+    #
+    # @return [ThreadPoolExecutor] the thread pool
     def global_task_pool
       @global_task_pool ||= Concurrent::ThreadPoolExecutor.new(
         min_threads: [2, @cores].max,
@@ -34,6 +48,9 @@ module Concurrent
       )
     end
 
+    # Global thread pool optimized for long *operations*.
+    #
+    # @return [ThreadPoolExecutor] the thread pool
     def global_operation_pool
       @global_operation_pool ||= Concurrent::ThreadPoolExecutor.new(
         min_threads: [2, @cores].max,
@@ -44,41 +61,72 @@ module Concurrent
       )
     end
 
+    # Global thread pool optimized for *timers*
+    #
+    # @return [ThreadPoolExecutor] the thread pool
+    #
+    # @see Concurrent::timer
+    def global_timer_set
+      @global_timer_set ||= Concurrent::TimerSet.new
+    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 [ConfigurationError] if this thread pool has already been set
     def global_task_pool=(executor)
       raise ConfigurationError.new('global task pool was already set') unless @global_task_pool.nil?
       @global_task_pool = executor
     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 [ConfigurationError] if this thread pool has already been set
     def global_operation_pool=(executor)
       raise ConfigurationError.new('global operation pool was already set') unless @global_operation_pool.nil?
       @global_operation_pool = executor
     end
   end
 
-  module OptionsParser
-
-    def get_executor_from(opts = {})
-      if opts[:executor]
-        opts[:executor]
-      elsif opts[:operation] == true || opts[:task] == false
-        Concurrent.configuration.global_operation_pool
-      else
-        Concurrent.configuration.global_task_pool
-      end
-    end
-  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 if executor.nil?
+    return true if executor.nil?
     if executor.respond_to?(:shutdown)
       executor.shutdown
     elsif executor.respond_to?(:kill)
       executor.kill
     end
+    true
   rescue
-    # suppress
+    false
   end
 
   # create the default configuration on load
@@ -86,6 +134,7 @@ module Concurrent
 
   # 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)
   end

data/lib/concurrent/dataflow.rb

@@ -1,6 +1,6 @@
-require 'concurrent/atomic'
 require 'concurrent/future'
-require 'concurrent/per_thread_executor'
+require 'concurrent/atomic/atomic_fixnum'
+require 'concurrent/executor/per_thread_executor'
 
 module Concurrent
 
@@ -20,13 +20,13 @@ module Concurrent
   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
+  # 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
+  # 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.
   #
@@ -50,16 +50,16 @@ module Concurrent
   #   # 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
+  # @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
+  # @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
+  # @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

data/lib/concurrent/delay.rb

@@ -32,14 +32,14 @@ module Concurrent
   class Delay
     include Obligation
 
-    # Create a new +Delay+ in the +:pending+ state.
+    # 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
+    # @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
@@ -54,24 +54,34 @@ module Concurrent
 
     # 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
+    # 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)
+    # 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
+    # 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.synchronize do
+      mutex.lock
+      execute_task_once
+      result = apply_deref_options(@value)
+      mutex.unlock
+
+      result
+    end
+
+    private
+
+      def execute_task_once
         if @state == :pending
           begin
             @value = @task.call
@@ -81,8 +91,6 @@ module Concurrent
             @state = :rejected
           end
         end
-        return apply_deref_options(@value)
       end
-    end
   end
 end

data/lib/concurrent/dereferenceable.rb

@@ -1,58 +1,66 @@
 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
+  # 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.
+    # 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+
+    # * `: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
+    # 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+.
+    # This method is thread-safe and synchronized with the internal `#mutex`.
     #
     # @return [Object] the current value of the object
     def value
-      mutex.synchronize do
-        apply_deref_options(@value)
-      end
+      mutex.lock
+      result = apply_deref_options(@value)
+      mutex.unlock
+      result
     end
+
     alias_method :deref, :value
 
     protected
 
+    # Set the internal value of this object
+    #
+    # @param [Object] val the new value
+    def value=(val)
+      mutex.lock
+      result = @value = val
+      mutex.unlock
+      result
+    end
+
     # A mutex lock used for synchronizing thread-safe operations. Methods defined
-    # by +Dereferenceable+ are synchronized using the +Mutex+ returned from this
+    # 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+.
+    # `@value` instance variable should be locked with this `Mutex`.
     #
     # @return [Mutex] the synchronization object
-    #
-    # @!visibility public
     def mutex
       @mutex
     end
 
-    # Initializes the internal +Mutex+. 
+    # Initializes the internal `Mutex`. 
     #
     # @note This method *must* be called from within the constructor of the including class.
     #
     # @see #mutex
-    #
-    # @!visibility public
     def init_mutex
       @mutex = Mutex.new
     end
@@ -60,24 +68,23 @@ module Concurrent
     # 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+
+    # @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
+    # @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
-    #
-    # @!visibility public
     def set_deref_options(opts = {})
-      mutex.synchronize do
-        @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)
-      end
+      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)
+      mutex.unlock
+      nil
     end
 
     # @!visibility private

data/lib/concurrent/exchanger.rb

@@ -8,6 +8,9 @@ module Concurrent
       @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

data/lib/concurrent/{cached_thread_pool.rb → executor/cached_thread_pool.rb}

@@ -1,9 +1,9 @@
-require 'concurrent/ruby_cached_thread_pool'
+require 'concurrent/executor/ruby_cached_thread_pool'
 
 module Concurrent
 
   if RUBY_PLATFORM == 'java'
-    require 'concurrent/java_cached_thread_pool'
+    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
@@ -11,9 +11,9 @@ module Concurrent
     #   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
+    #   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.
@@ -23,10 +23,10 @@ module Concurrent
     #   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+
+    #   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+.
+    #   @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
@@ -34,7 +34,6 @@ module Concurrent
     #   @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
-    #   @see http://stackoverflow.com/questions/17957382/fixedthreadpool-vs-cachedthreadpool-the-lesser-of-two-evils
     class CachedThreadPool < JavaCachedThreadPool
     end
   else