concurrent-ruby 0.8.0 → 0.9.0.pre2

data/lib/concurrent/executors.rb

@@ -2,8 +2,8 @@ require 'concurrent/executor/cached_thread_pool'
 require 'concurrent/executor/fixed_thread_pool'
 require 'concurrent/executor/immediate_executor'
 require 'concurrent/executor/indirect_immediate_executor'
-require 'concurrent/executor/per_thread_executor'
 require 'concurrent/executor/safe_task_executor'
+require 'concurrent/executor/simple_executor_service'
 require 'concurrent/executor/single_thread_executor'
 require 'concurrent/executor/thread_pool_executor'
 require 'concurrent/executor/timer_set'

data/lib/concurrent/future.rb

@@ -1,13 +1,15 @@
 require 'thread'
-
-require 'concurrent/options_parser'
+require 'concurrent/errors'
 require 'concurrent/ivar'
+require 'concurrent/executor/executor'
 require 'concurrent/executor/safe_task_executor'
 
 module Concurrent
 
   # {include:file:doc/future.md}
   #
+  # @!macro copy_options
+  #
   # @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
@@ -17,27 +19,15 @@ module Concurrent
     #
     # @yield the asynchronous operation to perform
     #
-    # @param [Hash] opts the options controlling how the future will be processed
-    # @option opts [Boolean] :operation (false) when `true` will execute the future on the global
-    #   operation pool (for long-running operations), when `false` will execute the future on the
-    #   global task pool (for short-running tasks)
-    # @option opts [object] :executor when provided will run all operations on
-    #   this executor rather than the global thread pool (overrides :operation)
-    # @option opts [object, Array] :args zero or more arguments to be passed the task block on execution
+    # @!macro executor_and_deref_options
     #
-    # @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
+    # @option opts [object, Array] :args zero or more arguments to be passed the task
+    #   block on execution
     #
     # @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
-      @executor = OptionsParser::get_executor_from(opts) || Concurrent.configuration.global_operation_pool
-      @args = OptionsParser::get_arguments_from(opts)
+      super(IVar::NO_VALUE, opts.merge(__task_from_block__: block), &nil)
     end
 
     # Execute an `:unscheduled` `Future`. Immediately sets the state to `:pending` and
@@ -57,7 +47,7 @@ module Concurrent
     #   future.state #=> :pending
     def execute
       if compare_and_set_state(:pending, :unscheduled)
-        @executor.post(@args){ work }
+        @executor.post{ safe_execute(@task, @args) }
         self
       end
     end
@@ -67,23 +57,15 @@ module Concurrent
     #
     # @yield the asynchronous operation to perform
     #
-    # @param [Hash] opts the options controlling how the future will be processed
-    # @option opts [Boolean] :operation (false) when `true` will execute the future on the global
-    #   operation pool (for long-running operations), when `false` will execute the future on the
-    #   global task pool (for short-running tasks)
-    # @option opts [object] :executor when provided will run all operations on
-    #   this executor rather than the global thread pool (overrides :operation)
-    # @option opts [object, Array] :args zero or more arguments to be passed the task block on execution
+    # @!macro executor_and_deref_options
     #
-    # @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
+    # @option opts [object, Array] :args zero or more arguments to be passed the task
+    #   block on execution
     #
     # @raise [ArgumentError] if no block is given
     #
+    # @return [Future] the newly created `Future` in the `:pending` state
+    #
     # @example
     #   future = Concurrent::Future.execute{ sleep(1); 42 }
     #   future.state #=> :pending
@@ -91,14 +73,64 @@ module Concurrent
       Future.new(opts, &block).execute
     end
 
-    protected :set, :fail, :complete
+    # @!macro ivar_set_method
+    def set(value = IVar::NO_VALUE, &block)
+      check_for_block_or_value!(block_given?, value)
+      synchronize do
+        if @state != :unscheduled
+          raise MultipleAssignmentError
+        else
+          @task = block || Proc.new { value }
+        end
+      end
+      execute
+    end
 
-    private
+    # Attempt to cancel the operation if it has not already processed.
+    # The operation can only be cancelled while still `pending`. It cannot
+    # be cancelled once it has begun processing or has completed.
+    #
+    # @return [Boolean] was the operation successfully cancelled.
+    def cancel
+      if compare_and_set_state(:cancelled, :pending)
+        complete(false, nil, CancelledOperationError.new)
+        true
+      else
+        false
+      end
+    end
+
+    # Has the operation been successfully cancelled?
+    #
+    # @return [Boolean]
+    def cancelled?
+      state == :cancelled
+    end
+
+    # Wait the given number of seconds for the operation to complete.
+    # On timeout attempt to cancel the operation.
+    #
+    # @param [Numeric] timeout the maximum time in seconds to wait.
+    # @return [Boolean] true if the operation completed before the timeout
+    #   else false
+    def wait_or_cancel(timeout)
+      wait(timeout)
+      if complete?
+        true
+      else
+        cancel
+        false
+      end
+    end
 
-    # @!visibility private
-    def work # :nodoc:
-      success, val, reason = SafeTaskExecutor.new(@task).execute(*@args)
-      complete(success, val, reason)
+    protected
+
+    def ns_initialize(value, opts)
+      super
+      @state = :unscheduled
+      @task = opts[:__task_from_block__]
+      @executor = Executor.executor_from_options(opts) || Concurrent.global_io_executor
+      @args = get_arguments_from(opts)
     end
   end
 end

data/lib/concurrent/immutable_struct.rb

@@ -0,0 +1,89 @@
+require 'concurrent/synchronization/abstract_struct'
+require 'concurrent/synchronization'
+
+module Concurrent
+
+  # A thread-safe, immutable variation of Ruby's standard `Struct`.
+  #
+  # @see http://ruby-doc.org/core-2.2.0/Struct.html Ruby standard library `Struct`
+  module ImmutableStruct
+    include Synchronization::AbstractStruct
+
+    # @!macro struct_values
+    def values
+      ns_values
+    end
+
+    alias_method :to_a, :values
+
+    # @!macro struct_values_at
+    def values_at(*indexes)
+      ns_values_at(indexes)
+    end
+
+    # @!macro struct_inspect
+    def inspect
+      ns_inspect
+    end
+
+    alias_method :to_s, :inspect
+
+    # @!macro struct_merge
+    def merge(other, &block)
+      ns_merge(other, &block)
+    end
+
+    # @!macro struct_to_h
+    def to_h
+      ns_to_h
+    end
+
+    # @!macro struct_get
+    def [](member)
+      ns_get(member)
+    end
+
+    # @!macro struct_equality
+    def ==(other)
+      ns_equality(other)
+    end
+
+    # @!macro struct_each
+    def each(&block)
+      return enum_for(:each) unless block_given?
+      ns_each(&block)
+    end
+
+    # @!macro struct_each_pair
+    def each_pair(&block)
+      return enum_for(:each_pair) unless block_given?
+      ns_each_pair(&block)
+    end
+
+    # @!macro struct_select
+    def select(&block)
+      return enum_for(:select) unless block_given?
+      ns_select(&block)
+    end
+
+    # @!macro struct_new
+    def self.new(*args, &block)
+      clazz_name = nil
+      if args.length == 0
+        raise ArgumentError.new('wrong number of arguments (0 for 1+)')
+      elsif args.length > 0 && args.first.is_a?(String)
+        clazz_name = args.shift
+      end
+      FACTORY.define_struct(clazz_name, args, &block)
+    end
+
+    FACTORY = Class.new(Synchronization::Object) do
+      def define_struct(name, members, &block)
+        synchronize do
+          Synchronization::AbstractStruct.define_struct_class(ImmutableStruct, Synchronization::Object, name, members, &block)
+        end
+      end
+    end.new
+    private_constant :FACTORY
+  end
+end

data/lib/concurrent/ivar.rb

@@ -1,39 +1,53 @@
 require 'thread'
 
 require 'concurrent/errors'
-require 'concurrent/obligation'
-require 'concurrent/observable'
+require 'concurrent/collection/copy_on_write_observer_set'
+require 'concurrent/concern/obligation'
+require 'concurrent/concern/observable'
+require 'concurrent/synchronization'
 
 module Concurrent
 
-  # An `IVar` is like a future that you can assign. As a future is a value that is being computed that you can wait on, an `IVar` is a value that is waiting to be assigned, that you can wait on. `IVars` are single assignment and deterministic.
-  # 
-  # Then, express futures as an asynchronous computation that assigns an `IVar`. The `IVar` becomes the primitive on which [futures](Future) and [dataflow](Dataflow) are built.
+  # An `IVar` is like a future that you can assign. As a future is a value that
+  # is being computed that you can wait on, an `IVar` is a value that is waiting
+  # to be assigned, that you can wait on. `IVars` are single assignment and
+  # deterministic.
+  #
+  # Then, express futures as an asynchronous computation that assigns an `IVar`.
+  # The `IVar` becomes the primitive on which [futures](Future) and
+  # [dataflow](Dataflow) are built.
   #
   # An `IVar` is a single-element container that is normally created empty, and
-  # can only be set once. The I in `IVar` stands for immutable. Reading an `IVar`
-  # normally blocks until it is set. It is safe to set and read an `IVar` from
-  # different threads.
+  # can only be set once. The I in `IVar` stands for immutable. Reading an
+  # `IVar` normally blocks until it is set. It is safe to set and read an `IVar`
+  # from different threads.
   #
   # If you want to have some parallel task set the value in an `IVar`, you want
-  # a `Future`. If you want to create a graph of parallel tasks all executed when
-  # the values they depend on are ready you want `dataflow`. `IVar` is generally
-  # a low-level primitive.
-  # 
-  # **See Also:**
+  # a `Future`. If you want to create a graph of parallel tasks all executed
+  # when the values they depend on are ready you want `dataflow`. `IVar` is
+  # generally a low-level primitive.
   #
-  # * For the theory: Arvind, R. Nikhil, and K. Pingali. [I-Structures: Data structures for parallel computing](http://dl.acm.org/citation.cfm?id=69562). In Proceedings of Workshop on Graph Reduction, 1986.
-  # * For recent application: [DataDrivenFuture in Habanero Java from Rice](http://www.cs.rice.edu/~vs3/hjlib/doc/edu/rice/hj/api/HjDataDrivenFuture.html).
+  # ## Examples
   #
-  # @example Create, set and get an `IVar`
-  #   ivar = Concurrent::IVar.new
-  #   ivar.set 14
-  #   ivar.get #=> 14
-  #   ivar.set 2 # would now be an error
-  class IVar
-
-    include Obligation
-    include Observable
+  # Create, set and get an `IVar`
+  #
+  # ```ruby
+  # ivar = Concurrent::IVar.new
+  # ivar.set 14
+  # ivar.get #=> 14
+  # ivar.set 2 # would now be an error
+  # ```
+  #
+  # ## See Also
+  #
+  # 1. For the theory: Arvind, R. Nikhil, and K. Pingali.
+  #    [I-Structures: Data structures for parallel computing](http://dl.acm.org/citation.cfm?id=69562).
+  #    In Proceedings of Workshop on Graph Reduction, 1986.
+  # 2. For recent application:
+  #    [DataDrivenFuture in Habanero Java from Rice](http://www.cs.rice.edu/~vs3/hjlib/doc/edu/rice/hj/api/HjDataDrivenFuture.html).
+  class IVar < Synchronization::Object
+    include Concern::Obligation
+    include Concern::Observable
 
     # @!visibility private
     NO_VALUE = Object.new # :nodoc:
@@ -42,31 +56,31 @@ module Concurrent
     #
     # @param [Object] value the initial value
     # @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
-    def initialize(value = NO_VALUE, opts = {})
-      init_obligation
-      self.observers = CopyOnWriteObserverSet.new
-      set_deref_options(opts)
-
-      if value == NO_VALUE
-        @state = :pending
-      else
-        set(value)
+    # @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 initialize(value = NO_VALUE, opts = {}, &block)
+      if value != NO_VALUE && block_given?
+        raise ArgumentError.new('provide only a value or a block')
       end
+      super(&nil)
+      synchronize { ns_initialize(value, opts, &block) }
     end
 
     # Add an observer on this object that will receive notification on update.
     #
-    # Upon completion the `IVar` will notify all observers in a thread-say way. The `func`
-    # method of the observer will be called with three arguments: the `Time` at which the
-    # `Future` completed the asynchronous operation, the final `value` (or `nil` on rejection),
-    # and the final `reason` (or `nil` on fulfillment).
+    # Upon completion the `IVar` will notify all observers in a thread-safe way.
+    # The `func` method of the observer will be called with three arguments: the
+    # `Time` at which the `Future` completed the asynchronous operation, the
+    # final `value` (or `nil` on rejection), and the final `reason` (or `nil` on
+    # fulfillment).
     #
     # @param [Object] observer the object that will be notified of changes
-    # @param [Symbol] func symbol naming the method to call when this `Observable` has changes`
+    # @param [Symbol] func symbol naming the method to call when this
+    #   `Observable` has changes`
     def add_observer(observer = nil, func = :update, &block)
       raise ArgumentError.new('cannot provide both an observer and a block') if observer && block
       direct_notification = false
@@ -76,7 +90,7 @@ module Concurrent
         func = :call
       end
 
-      mutex.synchronize do
+      synchronize do
         if event.set?
           direct_notification = true
         else
@@ -88,33 +102,111 @@ module Concurrent
       observer
     end
 
-    # Set the `IVar` to a value and wake or notify all threads waiting on it.
-    #
-    # @param [Object] value the value to store in the `IVar`
-    # @raise [Concurrent::MultipleAssignmentError] if the `IVar` has already been set or otherwise completed
-    def set(value)
-      complete(true, value, nil)
+    # @!macro [attach] ivar_set_method
+    #   Set the `IVar` to a value and wake or notify all threads waiting on it.
+    #  
+    #   @!macro [attach] ivar_set_parameters_and_exceptions
+    #     @param [Object] value the value to store in the `IVar`
+    #     @yield A block operation to use for setting the value
+    #     @raise [ArgumentError] if both a value and a block are given
+    #     @raise [Concurrent::MultipleAssignmentError] if the `IVar` has already
+    #       been set or otherwise completed
+    #  
+    #   @return [IVar] self
+    def set(value = NO_VALUE)
+      check_for_block_or_value!(block_given?, value)
+      raise MultipleAssignmentError unless compare_and_set_state(:processing, :pending)
+
+      begin
+        value = yield if block_given?
+        complete_without_notification(true, value, nil)
+      rescue => ex
+        complete_without_notification(false, nil, ex)
+      end
+
+      notify_observers(self.value, reason)
+      self
     end
 
-    # Set the `IVar` to failed due to some error and wake or notify all threads waiting on it.
-    #
-    # @param [Object] reason for the failure
-    # @raise [Concurrent::MultipleAssignmentError] if the `IVar` has already been set or otherwise completed
+    # @!macro [attach] ivar_fail_method
+    #   Set the `IVar` to failed due to some error and wake or notify all threads waiting on it.
+    #  
+    #   @param [Object] reason for the failure
+    #   @raise [Concurrent::MultipleAssignmentError] if the `IVar` has already
+    #     been set or otherwise completed
+    #   @return [IVar] self
     def fail(reason = StandardError.new)
       complete(false, nil, reason)
     end
 
+    # Attempt to set the `IVar` with the given value or block. Return a
+    # boolean indicating the success or failure of the set operation.
+    #
+    # @!macro ivar_set_parameters_and_exceptions
+    #
+    # @return [Boolean] true if the value was set else false
+    def try_set(value = NO_VALUE, &block)
+      set(value, &block)
+      true
+    rescue MultipleAssignmentError
+      false
+    end
+
+    protected
+
+    # @!visibility private
+    def ns_initialize(value, opts)
+      value = yield if block_given?
+      init_obligation(self)
+      self.observers = Collection::CopyOnWriteObserverSet.new
+      set_deref_options(opts)
+
+      if value == NO_VALUE
+        @state = :pending
+      else
+        ns_complete_without_notification(true, value, nil)
+      end
+    end
+
     # @!visibility private
-    def complete(success, value, reason) # :nodoc:
-      mutex.synchronize do
-        raise MultipleAssignmentError.new('multiple assignment') if [:fulfilled, :rejected].include? @state
-        set_state(success, value, reason)
-        event.set
+    def safe_execute(task, args = [])
+      if compare_and_set_state(:processing, :pending)
+        success, val, reason = SafeTaskExecutor.new(task, rescue_exception: true).execute(*@args)
+        complete(success, val, reason)
+        yield(success, val, reason) if block_given?
       end
+    end
 
-      time = Time.now
-      observers.notify_and_delete_observers{ [time, self.value, reason] }
+    # @!visibility private
+    def complete(success, value, reason)
+      complete_without_notification(success, value, reason)
+      notify_observers(self.value, reason)
       self
     end
+
+    # @!visibility private
+    def complete_without_notification(success, value, reason)
+      synchronize { ns_complete_without_notification(success, value, reason) }
+      self
+    end
+
+    # @!visibility private
+    def notify_observers(value, reason)
+      observers.notify_and_delete_observers{ [Time.now, value, reason] }
+    end
+
+    # @!visibility private
+    def ns_complete_without_notification(success, value, reason)
+      raise MultipleAssignmentError if [:fulfilled, :rejected].include? @state
+      set_state(success, value, reason)
+      event.set
+    end
+
+    # @!visibility private
+    def check_for_block_or_value!(block_given, value) # :nodoc:
+      if (block_given && value != NO_VALUE) || (! block_given && value == NO_VALUE)
+        raise ArgumentError.new('must set with either a value or a block')
+      end
+    end
   end
 end