concurrent-ruby 1.1.5

data/lib/concurrent/future.rb

@@ -0,0 +1,141 @@
+require 'thread'
+require 'concurrent/constants'
+require 'concurrent/errors'
+require 'concurrent/ivar'
+require 'concurrent/executor/safe_task_executor'
+
+require 'concurrent/options'
+
+# TODO (pitr-ch 14-Mar-2017): deprecate, Future, Promise, etc.
+
+
+module Concurrent
+
+  # {include:file:docs-source/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
+  class Future < IVar
+
+    # Create a new `Future` in the `:unscheduled` state.
+    #
+    # @yield the asynchronous operation to perform
+    #
+    # @!macro executor_and_deref_options
+    #
+    # @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(NULL, opts.merge(__task_from_block__: block), &nil)
+    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
+    def execute
+      if compare_and_set_state(:pending, :unscheduled)
+        @executor.post{ safe_execute(@task, @args) }
+        self
+      end
+    end
+
+    # Create a new `Future` object with the given block, execute it, and return the
+    # `:pending` object.
+    #
+    # @yield the asynchronous operation to perform
+    #
+    # @!macro executor_and_deref_options
+    #
+    # @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
+    def self.execute(opts = {}, &block)
+      Future.new(opts, &block).execute
+    end
+
+    # @!macro ivar_set_method
+    def set(value = NULL, &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
+
+    # 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
+
+    protected
+
+    def ns_initialize(value, opts)
+      super
+      @state = :unscheduled
+      @task = opts[:__task_from_block__]
+      @executor = Options.executor_from_options(opts) || Concurrent.global_io_executor
+      @args = get_arguments_from(opts)
+    end
+  end
+end

data/lib/concurrent/hash.rb

@@ -0,0 +1,59 @@
+require 'concurrent/utility/engine'
+require 'concurrent/thread_safe/util'
+
+module Concurrent
+
+  # @!macro concurrent_hash
+  #
+  #   A thread-safe subclass of Hash. This version locks against the object
+  #   itself for every method call, ensuring only one thread can be reading
+  #   or writing at a time. This includes iteration methods like `#each`,
+  #   which takes the lock repeatedly when reading an item.
+  #
+  #   @see http://ruby-doc.org/core-2.2.0/Hash.html Ruby standard library `Hash`
+
+  # @!macro internal_implementation_note
+  HashImplementation = case
+                       when Concurrent.on_cruby?
+                         # Hash is thread-safe in practice because CRuby runs
+                         # threads one at a time and does not do context
+                         # switching during the execution of C functions.
+                         ::Hash
+
+                       when Concurrent.on_jruby?
+                         require 'jruby/synchronized'
+
+                         class JRubyHash < ::Hash
+                           include JRuby::Synchronized
+                         end
+                         JRubyHash
+
+                       when Concurrent.on_rbx?
+                         require 'monitor'
+                         require 'concurrent/thread_safe/util/data_structures'
+
+                         class RbxHash < ::Hash
+                         end
+                         ThreadSafe::Util.make_synchronized_on_rbx RbxHash
+                         RbxHash
+
+                       when Concurrent.on_truffleruby?
+                         require 'concurrent/thread_safe/util/data_structures'
+
+                         class TruffleRubyHash < ::Hash
+                         end
+
+                         ThreadSafe::Util.make_synchronized_on_truffleruby TruffleRubyHash
+                         TruffleRubyHash
+
+                       else
+                         warn 'Possibly unsupported Ruby implementation'
+                         ::Hash
+                       end
+  private_constant :HashImplementation
+
+  # @!macro concurrent_hash
+  class Hash < HashImplementation
+  end
+
+end

data/lib/concurrent/immutable_struct.rb

@@ -0,0 +1,93 @@
+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
+
+    def self.included(base)
+      base.safe_initialization!
+    end
+
+    # @!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::LockableObject) 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

@@ -0,0 +1,207 @@
+require 'concurrent/constants'
+require 'concurrent/errors'
+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 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.
+  #
+  # 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.
+  #
+  # ## Examples
+  #
+  # Create, set and get an `IVar`
+  #
+  # ```ruby
+  # ivar = Concurrent::IVar.new
+  # ivar.set 14
+  # ivar.value #=> 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::LockableObject
+    include Concern::Obligation
+    include Concern::Observable
+
+    # Create a new `IVar` in the `:pending` state with the (optional) initial value.
+    #
+    # @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 = NULL, opts = {}, &block)
+      if value != NULL && 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-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`
+    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
+
+      if block
+        observer = block
+        func = :call
+      end
+
+      synchronize do
+        if event.set?
+          direct_notification = true
+        else
+          observers.add_observer(observer, func)
+        end
+      end
+
+      observer.send(func, Time.now, self.value, reason) if direct_notification
+      observer
+    end
+
+    # @!macro ivar_set_method
+    #   Set the `IVar` to a value and wake or notify all threads waiting on it.
+    #
+    #   @!macro 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 = NULL)
+      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
+
+    # @!macro 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 = NULL, &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.observers = Collection::CopyOnWriteObserverSet.new
+      set_deref_options(opts)
+
+      @state = :pending
+      if value != NULL
+        ns_complete_without_notification(true, value, nil)
+      end
+    end
+
+    # @!visibility private
+    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
+
+    # @!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 != NULL) || (! block_given && value == NULL)
+        raise ArgumentError.new('must set with either a value or a block')
+      end
+    end
+  end
+end