concurrent-ruby 0.4.1 → 0.5.0.pre.1

data/lib/concurrent/dataflow.rb

@@ -0,0 +1,85 @@
+require 'concurrent/atomic'
+require 'concurrent/future'
+
+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)
+    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 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
+end

data/lib/concurrent/dereferenceable.rb

@@ -1,24 +1,76 @@
 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.
+    #
+    # 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.synchronize do
+        apply_deref_options(@value)
+      end
+    end
+    alias_method :deref, :value
+
+    protected
+
+    # 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
+    #
+    # @!visibility public
+    def mutex
+      @mutex
+    end
+
+    # 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
+
     # Set the options which define the operations #value performs before
     # returning data to the caller (dereferencing).
     #
-    # @note Many 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 Call #dup before returning the data (default: false)
-    # @option opts [String] :freeze_on_deref Call #freeze before returning the data (default: false)
-    # @option opts [String] :copy_on_deref Call the given `Proc` passing the internal value and
-    #   returning the value returned from the proc (default: `nil`)
+    # @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]
@@ -28,29 +80,15 @@ module Concurrent
       end
     end
 
-    # Return the value this object represents after applying the options specified
-    # by the #set_deref_options method.
-    def value
-      return nil if @value.nil?
-      return @value if @do_nothing_on_deref
-      mutex.synchronize do
-        value = @value
-        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
-    alias_method :deref, :value
-
-    protected
-
-    def mutex # :nodoc:
-      @mutex
-    end
-
-    def init_mutex
-      @mutex = Mutex.new
+    # @!visibility private
+    def apply_deref_options(value) # :nodoc:
+      return nil if value.nil?
+      return value if @do_nothing_on_deref
+      value = value
+      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/event.rb

@@ -1,41 +1,42 @@
 require 'thread'
 require 'concurrent/utilities'
+require 'concurrent/condition'
 
 module Concurrent
 
   # Old school kernel-style event reminiscent of Win32 programming in C++.
   #
-  # When an `Event` is created it is in the `unset` state. Threads can choose to
-  # `#wait` on the event, blocking until released by another thread. When one
-  # thread wants to alert all blocking threads it calls the `#set` method which
-  # will then wake up all listeners. Once an `Event` has been set it remains set.
-  # New threads calling `#wait` will return immediately. An `Event` may be
-  # `#reset` at any time once it has been set.
+  # When an +Event+ is created it is in the +unset+ state. Threads can choose to
+  # +#wait+ on the event, blocking until released by another thread. When one
+  # thread wants to alert all blocking threads it calls the +#set+ method which
+  # will then wake up all listeners. Once an +Event+ has been set it remains set.
+  # New threads calling +#wait+ will return immediately. An +Event+ may be
+  # +#reset+ at any time once it has been set.
   #
   # @see http://msdn.microsoft.com/en-us/library/windows/desktop/ms682655.aspx
   class Event
 
-    # Creates a new `Event` in the unset state. Threads calling `#wait` on the
-    # `Event` will block.
+    # Creates a new +Event+ in the unset state. Threads calling +#wait+ on the
+    # +Event+ will block.
     def initialize
       @set = false
       @mutex = Mutex.new
-      @condition = ConditionVariable.new
+      @condition = Condition.new
     end
 
     # Is the object in the set state?
     #
-    # @return [Boolean] indicating whether or not the `Event` has been set
+    # @return [Boolean] indicating whether or not the +Event+ has been set
     def set?
       @mutex.synchronize do
         @set
       end
     end
 
-    # Trigger the event, setting the state to `set` and releasing all threads
-    # waiting on the event. Has no effect if the `Event` has already been set.
+    # Trigger the event, setting the state to +set+ and releasing all threads
+    # waiting on the event. Has no effect if the +Event+ has already been set.
     #
-    # @return [Boolean] should always return `true`
+    # @return [Boolean] should always return +true+
     def set
       @mutex.synchronize do
         return true if @set
@@ -46,10 +47,10 @@ module Concurrent
       true
     end
 
-    # Reset a previously set event back to the `unset` state.
-    # Has no effect if the `Event` has not yet been set.
+    # Reset a previously set event back to the +unset+ state.
+    # Has no effect if the +Event+ has not yet been set.
     #
-    # @return [Boolean] should always return `true`
+    # @return [Boolean] should always return +true+
     def reset
       @mutex.synchronize do
         @set = false
@@ -58,15 +59,20 @@ module Concurrent
       true
     end
 
-    # Wait a given number of seconds for the `Event` to be set by another
-    # thread. Will wait forever when no `timeout` value is given. Returns
-    # immediately if the `Event` has already been set.
+    # Wait a given number of seconds for the +Event+ to be set by another
+    # thread. Will wait forever when no +timeout+ value is given. Returns
+    # immediately if the +Event+ has already been set.
     #
-    # @return [Boolean] true if the `Event` was set before timeout else false
+    # @return [Boolean] true if the +Event+ was set before timeout else false
     def wait(timeout = nil)
       @mutex.synchronize do
         return true if @set
-        @condition.wait(@mutex, timeout)
+
+        remaining = Condition::Result.new(timeout)
+        while !@set && remaining.can_wait?
+          remaining = @condition.wait(@mutex, remaining.remaining_time)
+        end
+
         @set
       end
     end

data/lib/concurrent/future.rb

@@ -1,62 +1,122 @@
 require 'thread'
-require 'observer'
 
-require 'concurrent/global_thread_pool'
 require 'concurrent/obligation'
+require 'concurrent/global_thread_pool'
+require 'concurrent/safe_task_executor'
 
 module Concurrent
 
-  class Future
+  # A +Future+ represents a promise to complete an action at some time in the future.
+  # The action is atomic and permanent. The idea behind a future is to send an operation
+  # for asynchronous completion, do other stuff, then return and retrieve the result
+  # of the async operation at a later time.
+  #
+  # A +Future+ has four possible states: *:unscheduled*, *:pending*, *:rejected*, or *:fulfilled*.
+  # When a +Future+ is created its state is set to *:unscheduled*. Once the +#execute+ method is
+  # called the state becomes *:pending* and will remain in that state until processing is
+  # complete. A completed +Future+ is either *:rejected*, indicating that an exception was
+  # thrown during processing, or *:fulfilled*, indicating success. If a +Future+ is *:fulfilled*
+  # its +value+ will be updated to reflect the result of the operation. If *:rejected* the
+  # +reason+ will be updated with a reference to the thrown exception. The predicate methods
+  # +#unscheduled?+, +#pending?+, +#rejected?+, and +fulfilled?+ can be called at any time to
+  # obtain the state of the +Future+, as can the +#state+ method, which returns a symbol. 
+  #
+  # Retrieving the value of a +Future+ is done through the +#value+ (alias: +#deref+) method.
+  # Obtaining the value of a +Future+ is a potentially blocking operation. When a +Future+ is
+  # *:rejected* a call to +#value+ will return +nil+ immediately. When a +Future+ is
+  # *:fulfilled* a call to +#value+ will immediately return the current value. When a
+  # +Future+ is *:pending* a call to +#value+ will block until the +Future+ is either
+  # *:rejected* or *:fulfilled*. A *timeout* value can be passed to +#value+ to limit how
+  # long the call will block. If +nil+ the call will block indefinitely. If +0+ the call will
+  # not block. Any other integer or float value will indicate the maximum number of seconds to block.
+  #
+  # The +Future+ class also includes the behavior of the Ruby standard library +Observable+ module,
+  # but does so in a thread-safe way. On fulfillment or rejection all observers will be notified
+  # according to the normal +Observable+ behavior. The observer callback function will be called
+  # with three parameters: the +Time+ of fulfillment/rejection, the final +value+, and the final
+  # +reason+. Observers added after fulfillment/rejection will still be notified as normal.
+  #
+  # @see http://ruby-doc.org/stdlib-2.1.1/libdoc/observer/rdoc/Observable.html Ruby Observable module
+  # @see http://clojuredocs.org/clojure_core/clojure.core/future Clojure's future function
+  # @see http://docs.oracle.com/javase/7/docs/api/java/util/concurrent/Future.html java.util.concurrent.Future
+  class Future < IVar
     include Obligation
-    include Observable
     include UsesGlobalThreadPool
 
-    def initialize(*args, &block)
-      init_mutex
-      unless block_given?
-        @state = :fulfilled
-      else
-        @value = nil
-        @state = :pending
-        Future.thread_pool.post(*args) do
-          work(*args, &block)
-        end
-      end
+    # Create a new +Future+ in the +:unscheduled+ state.
+    #
+    # @yield the asynchronous 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?
+      super(IVar::NO_VALUE, opts)
+      @state = :unscheduled
+      @task = block
     end
 
-    def add_observer(observer, func = :update)
-      val = self.value
-      mutex.synchronize do
-        if event.set?
-          Future.thread_pool.post(func, Time.now, val, @reason) do |f, *args|
-            observer.send(f, *args)
-          end
-        else
-          super
-        end
+    # Execute an +:unscheduled+ +Future+. Immediately sets the state to +:pending+ and
+    # passes the block to a new thread/thread pool for eventual execution.
+    # Does nothing if the +Future+ is in any state other than +:unscheduled+.
+    #
+    # @return [Future] a reference to +self+
+    #
+    # @example Instance and execute in separate steps
+    #   future = Concurrent::Future.new{ sleep(1); 42 }
+    #   future.state #=> :unscheduled
+    #   future.execute
+    #   future.state #=> :pending
+    #
+    # @example Instance and execute in one line
+    #   future = Concurrent::Future.new{ sleep(1); 42 }.execute
+    #   future.state #=> :pending
+    #
+    # @since 0.5.0
+    def execute
+      if compare_and_set_state(:pending, :unscheduled)
+        Future.thread_pool.post { work }
+        self
       end
-      return func
     end
 
+    # Create a new +Future+ object with the given block, execute it, and return the
+    # +:pending+ object.
+    #
+    # @yield the asynchronous operation to perform
+    #
+    # @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
+    #
+    # @return [Future] the newly created +Future+ in the +:pending+ state
+    #
+    # @raise [ArgumentError] if no block is given
+    #
+    # @example
+    #   future = Concurrent::Future.execute{ sleep(1); 42 }
+    #   future.state #=> :pending
+    #
+    # @since 0.5.0
+    def self.execute(opts = {}, &block)
+      return Future.new(opts, &block).execute
+    end
+
+    protected :set, :fail, :complete
+
     private
 
-    # @private
-    def work(*args) # :nodoc:
-      begin
-        @value = yield(*args)
-        @state = :fulfilled
-      rescue Exception => ex
-        @reason = ex
-        @state = :rejected
-      ensure
-        val = self.value
-        mutex.synchronize do
-          event.set
-          changed
-          notify_observers(Time.now, val, @reason)
-          delete_observers
-        end
-      end
+    # @!visibility private
+    def work # :nodoc:
+      success, val, reason = SafeTaskExecutor.new(@task).execute
+      complete(success, val, reason)
     end
+    
   end
 end