o-concurrent-ruby 1.1.11

data/lib/concurrent-ruby/concurrent/re_include.rb

@@ -0,0 +1,58 @@
+module Concurrent
+
+  # Methods form module A included to a module B, which is already included into class C,
+  # will not be visible in the C class. If this module is extended to B then A's methods
+  # are correctly made visible to C.
+  #
+  # @example
+  #   module A
+  #     def a
+  #       :a
+  #     end
+  #   end
+  #
+  #   module B1
+  #   end
+  #
+  #   class C1
+  #     include B1
+  #   end
+  #
+  #   module B2
+  #     extend Concurrent::ReInclude
+  #   end
+  #
+  #   class C2
+  #     include B2
+  #   end
+  #
+  #   B1.send :include, A
+  #   B2.send :include, A
+  #
+  #   C1.new.respond_to? :a # => false
+  #   C2.new.respond_to? :a # => true
+  module ReInclude
+    # @!visibility private
+    def included(base)
+      (@re_include_to_bases ||= []) << [:include, base]
+      super(base)
+    end
+
+    # @!visibility private
+    def extended(base)
+      (@re_include_to_bases ||= []) << [:extend, base]
+      super(base)
+    end
+
+    # @!visibility private
+    def include(*modules)
+      result = super(*modules)
+      modules.reverse.each do |module_being_included|
+        (@re_include_to_bases ||= []).each do |method, mod|
+          mod.send method, module_being_included
+        end
+      end
+      result
+    end
+  end
+end

data/lib/concurrent-ruby/concurrent/scheduled_task.rb

@@ -0,0 +1,331 @@
+require 'concurrent/constants'
+require 'concurrent/errors'
+require 'concurrent/configuration'
+require 'concurrent/ivar'
+require 'concurrent/collection/copy_on_notify_observer_set'
+require 'concurrent/utility/monotonic_time'
+
+require 'concurrent/options'
+
+module Concurrent
+
+  # `ScheduledTask` is a close relative of `Concurrent::Future` but with one
+  # important difference: A `Future` is set to execute as soon as possible
+  # whereas a `ScheduledTask` is set to execute after a specified delay. This
+  # implementation is loosely based on Java's
+  # [ScheduledExecutorService](http://docs.oracle.com/javase/7/docs/api/java/util/concurrent/ScheduledExecutorService.html).
+  # It is a more feature-rich variant of {Concurrent.timer}.
+  #
+  # The *intended* schedule time of task execution is set on object construction
+  # with the `delay` argument. The delay is a numeric (floating point or integer)
+  # representing a number of seconds in the future. Any other value or a numeric
+  # equal to or less than zero will result in an exception. The *actual* schedule
+  # time of task execution is set when the `execute` method is called.
+  #
+  # The constructor can also be given zero or more processing options. Currently
+  # the only supported options are those recognized by the
+  # [Dereferenceable](Dereferenceable) module.
+  #
+  # The final constructor argument is a block representing the task to be performed.
+  # If no block is given an `ArgumentError` will be raised.
+  #
+  # **States**
+  #
+  # `ScheduledTask` mixes in the  [Obligation](Obligation) module thus giving it
+  # "future" behavior. This includes the expected lifecycle states. `ScheduledTask`
+  # has one additional state, however. While the task (block) is being executed the
+  # state of the object will be `:processing`. This additional state is necessary
+  # because it has implications for task cancellation.
+  #
+  # **Cancellation**
+  #
+  # A `:pending` task can be cancelled using the `#cancel` method. A task in any
+  # other state, including `:processing`, cannot be cancelled. The `#cancel`
+  # method returns a boolean indicating the success of the cancellation attempt.
+  # A cancelled `ScheduledTask` cannot be restarted. It is immutable.
+  #
+  # **Obligation and Observation**
+  #
+  # The result of a `ScheduledTask` can be obtained either synchronously or
+  # asynchronously. `ScheduledTask` mixes in both the [Obligation](Obligation)
+  # module and the
+  # [Observable](http://ruby-doc.org/stdlib-2.0/libdoc/observer/rdoc/Observable.html)
+  # module from the Ruby standard library. With one exception `ScheduledTask`
+  # behaves identically to [Future](Observable) with regard to these modules.
+  #
+  # @!macro copy_options
+  #
+  # @example Basic usage
+  #
+  #   require 'concurrent'
+  #   require 'csv'
+  #   require 'open-uri'
+  #
+  #   class Ticker
+  #     def get_year_end_closing(symbol, year, api_key)
+  #      uri = "https://www.alphavantage.co/query?function=TIME_SERIES_MONTHLY&symbol=#{symbol}&apikey=#{api_key}&datatype=csv"
+  #      data = []
+  #      csv = URI.parse(uri).read
+  #      if csv.include?('call frequency')
+  #        return :rate_limit_exceeded
+  #      end
+  #      CSV.parse(csv, headers: true) do |row|
+  #        data << row['close'].to_f if row['timestamp'].include?(year.to_s)
+  #      end
+  #      year_end = data.first
+  #      year_end
+  #    rescue => e
+  #      p e
+  #    end
+  #   end
+  #
+  #   api_key = ENV['ALPHAVANTAGE_KEY']
+  #   abort(error_message) unless api_key
+  #
+  #   # Future
+  #   price = Concurrent::Future.execute{ Ticker.new.get_year_end_closing('TWTR', 2013, api_key) }
+  #   price.state #=> :pending
+  #   price.pending? #=> true
+  #   price.value(0) #=> nil (does not block)
+  #
+  #    sleep(1)    # do other stuff
+  #
+  #   price.value #=> 63.65 (after blocking if necessary)
+  #   price.state #=> :fulfilled
+  #   price.fulfilled? #=> true
+  #   price.value #=> 63.65
+  #
+  # @example Successful task execution
+  #
+  #   task = Concurrent::ScheduledTask.new(2){ 'What does the fox say?' }
+  #   task.state         #=> :unscheduled
+  #   task.execute
+  #   task.state         #=> pending
+  #
+  #   # wait for it...
+  #   sleep(3)
+  #
+  #   task.unscheduled? #=> false
+  #   task.pending?     #=> false
+  #   task.fulfilled?   #=> true
+  #   task.rejected?    #=> false
+  #   task.value        #=> 'What does the fox say?'
+  #
+  # @example One line creation and execution
+  #
+  #   task = Concurrent::ScheduledTask.new(2){ 'What does the fox say?' }.execute
+  #   task.state         #=> pending
+  #
+  #   task = Concurrent::ScheduledTask.execute(2){ 'What do you get when you multiply 6 by 9?' }
+  #   task.state         #=> pending
+  #
+  # @example Failed task execution
+  #
+  #   task = Concurrent::ScheduledTask.execute(2){ raise StandardError.new('Call me maybe?') }
+  #   task.pending?      #=> true
+  #
+  #   # wait for it...
+  #   sleep(3)
+  #
+  #   task.unscheduled? #=> false
+  #   task.pending?     #=> false
+  #   task.fulfilled?   #=> false
+  #   task.rejected?    #=> true
+  #   task.value        #=> nil
+  #   task.reason       #=> #<StandardError: Call me maybe?>
+  #
+  # @example Task execution with observation
+  #
+  #   observer = Class.new{
+  #     def update(time, value, reason)
+  #       puts "The task completed at #{time} with value '#{value}'"
+  #     end
+  #   }.new
+  #
+  #   task = Concurrent::ScheduledTask.new(2){ 'What does the fox say?' }
+  #   task.add_observer(observer)
+  #   task.execute
+  #   task.pending?      #=> true
+  #
+  #   # wait for it...
+  #   sleep(3)
+  #
+  #   #>> The task completed at 2013-11-07 12:26:09 -0500 with value 'What does the fox say?'
+  #
+  # @!macro monotonic_clock_warning
+  #
+  # @see Concurrent.timer
+  class ScheduledTask < IVar
+    include Comparable
+
+    # The executor on which to execute the task.
+    # @!visibility private
+    attr_reader :executor
+
+    # Schedule a task for execution at a specified future time.
+    #
+    # @param [Float] delay the number of seconds to wait for before executing the task
+    #
+    # @yield the task to be performed
+    #
+    # @!macro executor_and_deref_options
+    #
+    # @option opts [object, Array] :args zero or more arguments to be passed the task
+    #   block on execution
+    #
+    # @raise [ArgumentError] When no block is given
+    # @raise [ArgumentError] When given a time that is in the past
+    def initialize(delay, opts = {}, &task)
+      raise ArgumentError.new('no block given') unless block_given?
+      raise ArgumentError.new('seconds must be greater than zero') if delay.to_f < 0.0
+
+      super(NULL, opts, &nil)
+
+      synchronize do
+        ns_set_state(:unscheduled)
+        @parent = opts.fetch(:timer_set, Concurrent.global_timer_set)
+        @args = get_arguments_from(opts)
+        @delay = delay.to_f
+        @task = task
+        @time = nil
+        @executor = Options.executor_from_options(opts) || Concurrent.global_io_executor
+        self.observers = Collection::CopyOnNotifyObserverSet.new
+      end
+    end
+
+    # The `delay` value given at instanciation.
+    #
+    # @return [Float] the initial delay.
+    def initial_delay
+      synchronize { @delay }
+    end
+
+    # The monotonic time at which the the task is scheduled to be executed.
+    #
+    # @return [Float] the schedule time or nil if `unscheduled`
+    def schedule_time
+      synchronize { @time }
+    end
+
+    # Comparator which orders by schedule time.
+    #
+    # @!visibility private
+    def <=>(other)
+      schedule_time <=> other.schedule_time
+    end
+
+    # Has the task been cancelled?
+    #
+    # @return [Boolean] true if the task is in the given state else false
+    def cancelled?
+      synchronize { ns_check_state?(:cancelled) }
+    end
+
+    # In the task execution in progress?
+    #
+    # @return [Boolean] true if the task is in the given state else false
+    def processing?
+      synchronize { ns_check_state?(:processing) }
+    end
+
+    # Cancel this task and prevent it from executing. A task can only be
+    # cancelled if it is pending or unscheduled.
+    #
+    # @return [Boolean] true if successfully cancelled else false
+    def cancel
+      if compare_and_set_state(:cancelled, :pending, :unscheduled)
+        complete(false, nil, CancelledOperationError.new)
+        # To avoid deadlocks this call must occur outside of #synchronize
+        # Changing the state above should prevent redundant calls
+        @parent.send(:remove_task, self)
+      else
+        false
+      end
+    end
+
+    # Reschedule the task using the original delay and the current time.
+    # A task can only be reset while it is `:pending`.
+    #
+    # @return [Boolean] true if successfully rescheduled else false
+    def reset
+      synchronize{ ns_reschedule(@delay) }
+    end
+
+    # Reschedule the task using the given delay and the current time.
+    # A task can only be reset while it is `:pending`.
+    #
+    # @param [Float] delay the number of seconds to wait for before executing the task
+    #
+    # @return [Boolean] true if successfully rescheduled else false
+    #
+    # @raise [ArgumentError] When given a time that is in the past
+    def reschedule(delay)
+      delay = delay.to_f
+      raise ArgumentError.new('seconds must be greater than zero') if delay < 0.0
+      synchronize{ ns_reschedule(delay) }
+    end
+
+    # Execute an `:unscheduled` `ScheduledTask`. Immediately sets the state to `:pending`
+    # and starts counting down toward execution. Does nothing if the `ScheduledTask` is
+    # in any state other than `:unscheduled`.
+    #
+    # @return [ScheduledTask] a reference to `self`
+    def execute
+      if compare_and_set_state(:pending, :unscheduled)
+        synchronize{ ns_schedule(@delay) }
+      end
+      self
+    end
+
+    # Create a new `ScheduledTask` object with the given block, execute it, and return the
+    # `:pending` object.
+    #
+    # @param [Float] delay the number of seconds to wait for before executing the task
+    #
+    # @!macro executor_and_deref_options
+    #
+    # @return [ScheduledTask] the newly created `ScheduledTask` in the `:pending` state
+    #
+    # @raise [ArgumentError] if no block is given
+    def self.execute(delay, opts = {}, &task)
+      new(delay, opts, &task).execute
+    end
+
+    # Execute the task.
+    #
+    # @!visibility private
+    def process_task
+      safe_execute(@task, @args)
+    end
+
+    protected :set, :try_set, :fail, :complete
+
+    protected
+
+    # Schedule the task using the given delay and the current time.
+    #
+    # @param [Float] delay the number of seconds to wait for before executing the task
+    #
+    # @return [Boolean] true if successfully rescheduled else false
+    #
+    # @!visibility private
+    def ns_schedule(delay)
+      @delay = delay
+      @time = Concurrent.monotonic_time + @delay
+      @parent.send(:post_task, self)
+    end
+
+    # Reschedule the task using the given delay and the current time.
+    # A task can only be reset while it is `:pending`.
+    #
+    # @param [Float] delay the number of seconds to wait for before executing the task
+    #
+    # @return [Boolean] true if successfully rescheduled else false
+    #
+    # @!visibility private
+    def ns_reschedule(delay)
+      return false unless ns_check_state?(:pending)
+      @parent.send(:remove_task, self) && ns_schedule(delay)
+    end
+  end
+end

data/lib/concurrent-ruby/concurrent/set.rb

@@ -0,0 +1,74 @@
+require 'concurrent/utility/engine'
+require 'concurrent/thread_safe/util'
+require 'set'
+
+module Concurrent
+
+  # @!macro concurrent_set
+  #
+  #   A thread-safe subclass of Set. 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`.
+  #
+  #   @note `a += b` is **not** a **thread-safe** operation on
+  #     `Concurrent::Set`. It reads Set `a`, then it creates new `Concurrent::Set`
+  #     which is union of `a` and `b`, then it writes the union to `a`.
+  #     The read and write are independent operations they do not form a single atomic
+  #     operation therefore when two `+=` operations are executed concurrently updates
+  #     may be lost. Use `#merge` instead.
+  #
+  #   @see http://ruby-doc.org/stdlib-2.4.0/libdoc/set/rdoc/Set.html Ruby standard library `Set`
+
+  # @!macro internal_implementation_note
+  SetImplementation = case
+                      when Concurrent.on_cruby?
+                        # The CRuby implementation of Set is written in Ruby itself and is
+                        # not thread safe for certain methods.
+                        require 'monitor'
+                        require 'concurrent/thread_safe/util/data_structures'
+
+                        class CRubySet < ::Set
+                        end
+
+                        ThreadSafe::Util.make_synchronized_on_cruby CRubySet
+                        CRubySet
+
+                      when Concurrent.on_jruby?
+                        require 'jruby/synchronized'
+
+                        class JRubySet < ::Set
+                          include JRuby::Synchronized
+                        end
+
+                        JRubySet
+
+                      when Concurrent.on_rbx?
+                        require 'monitor'
+                        require 'concurrent/thread_safe/util/data_structures'
+
+                        class RbxSet < ::Set
+                        end
+
+                        ThreadSafe::Util.make_synchronized_on_rbx RbxSet
+                        RbxSet
+
+                      when Concurrent.on_truffleruby?
+                        require 'concurrent/thread_safe/util/data_structures'
+
+                        class TruffleRubySet < ::Set
+                        end
+
+                        ThreadSafe::Util.make_synchronized_on_truffleruby TruffleRubySet
+                        TruffleRubySet
+
+                      else
+                        warn 'Possibly unsupported Ruby implementation'
+                        ::Set
+                      end
+  private_constant :SetImplementation
+
+  # @!macro concurrent_set
+  class Set < SetImplementation
+  end
+end
+

data/lib/concurrent-ruby/concurrent/settable_struct.rb

@@ -0,0 +1,139 @@
+require 'concurrent/synchronization/abstract_struct'
+require 'concurrent/errors'
+require 'concurrent/synchronization'
+
+module Concurrent
+
+  # An thread-safe, write-once variation of Ruby's standard `Struct`.
+  # Each member can have its value set at most once, either at construction
+  # or any time thereafter. Attempting to assign a value to a member
+  # that has already been set will result in a `Concurrent::ImmutabilityError`.
+  #
+  # @see http://ruby-doc.org/core/Struct.html Ruby standard library `Struct`
+  # @see http://en.wikipedia.org/wiki/Final_(Java) Java `final` keyword
+  module SettableStruct
+    include Synchronization::AbstractStruct
+
+    # @!macro struct_values
+    def values
+      synchronize { ns_values }
+    end
+    alias_method :to_a, :values
+
+    # @!macro struct_values_at
+    def values_at(*indexes)
+      synchronize { ns_values_at(indexes) }
+    end
+
+    # @!macro struct_inspect
+    def inspect
+      synchronize { ns_inspect }
+    end
+    alias_method :to_s, :inspect
+
+    # @!macro struct_merge
+    def merge(other, &block)
+      synchronize { ns_merge(other, &block) }
+    end
+
+    # @!macro struct_to_h
+    def to_h
+      synchronize { ns_to_h }
+    end
+
+    # @!macro struct_get
+    def [](member)
+      synchronize { ns_get(member) }
+    end
+
+    # @!macro struct_equality
+    def ==(other)
+      synchronize { ns_equality(other) }
+    end
+
+    # @!macro struct_each
+    def each(&block)
+      return enum_for(:each) unless block_given?
+      synchronize { ns_each(&block) }
+    end
+
+    # @!macro struct_each_pair
+    def each_pair(&block)
+      return enum_for(:each_pair) unless block_given?
+      synchronize { ns_each_pair(&block) }
+    end
+
+    # @!macro struct_select
+    def select(&block)
+      return enum_for(:select) unless block_given?
+      synchronize { ns_select(&block) }
+    end
+
+    # @!macro struct_set
+    #
+    # @raise [Concurrent::ImmutabilityError] if the given member has already been set
+    def []=(member, value)
+      if member.is_a? Integer
+        length = synchronize { @values.length }
+        if member >= length
+          raise IndexError.new("offset #{member} too large for struct(size:#{length})")
+        end
+        synchronize do
+          unless @values[member].nil?
+            raise Concurrent::ImmutabilityError.new('struct member has already been set')
+          end
+          @values[member] = value
+        end
+      else
+        send("#{member}=", value)
+      end
+    rescue NoMethodError
+      raise NameError.new("no member '#{member}' in struct")
+    end
+
+    private
+
+    # @!visibility private
+    def initialize_copy(original)
+      synchronize do
+        super(original)
+        ns_initialize_copy
+      end
+    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
+          clazz = Synchronization::AbstractStruct.define_struct_class(SettableStruct, Synchronization::LockableObject, name, members, &block)
+          members.each_with_index do |member, index|
+            clazz.send :remove_method, member if clazz.instance_methods.include? member
+            clazz.send(:define_method, member) do
+              synchronize { @values[index] }
+            end
+            clazz.send(:define_method, "#{member}=") do |value|
+              synchronize do
+                unless @values[index].nil?
+                  raise Concurrent::ImmutabilityError.new('struct member has already been set')
+                end
+                @values[index] = value
+              end
+            end
+          end
+          clazz
+        end
+      end
+    end.new
+    private_constant :FACTORY
+  end
+end

data/lib/concurrent-ruby/concurrent/synchronization/abstract_lockable_object.rb

@@ -0,0 +1,98 @@
+module Concurrent
+  module Synchronization
+
+    # @!visibility private
+    class AbstractLockableObject < Synchronization::Object
+
+      protected
+
+      # @!macro synchronization_object_method_synchronize
+      #
+      #   @yield runs the block synchronized against this object,
+      #     equivalent of java's `synchronize(this) {}`
+      #   @note can by made public in descendants if required by `public :synchronize`
+      def synchronize
+        raise NotImplementedError
+      end
+
+      # @!macro synchronization_object_method_ns_wait_until
+      #
+      #   Wait until condition is met or timeout passes,
+      #   protects against spurious wake-ups.
+      #   @param [Numeric, nil] timeout in seconds, `nil` means no timeout
+      #   @yield condition to be met
+      #   @yieldreturn [true, false]
+      #   @return [true, false] if condition met
+      #   @note only to be used inside synchronized block
+      #   @note to provide direct access to this method in a descendant add method
+      #     ```
+      #     def wait_until(timeout = nil, &condition)
+      #       synchronize { ns_wait_until(timeout, &condition) }
+      #     end
+      #     ```
+      def ns_wait_until(timeout = nil, &condition)
+        if timeout
+          wait_until = Concurrent.monotonic_time + timeout
+          loop do
+            now              = Concurrent.monotonic_time
+            condition_result = condition.call
+            return condition_result if now >= wait_until || condition_result
+            ns_wait wait_until - now
+          end
+        else
+          ns_wait timeout until condition.call
+          true
+        end
+      end
+
+      # @!macro synchronization_object_method_ns_wait
+      #
+      #   Wait until another thread calls #signal or #broadcast,
+      #   spurious wake-ups can happen.
+      #
+      #   @param [Numeric, nil] timeout in seconds, `nil` means no timeout
+      #   @return [self]
+      #   @note only to be used inside synchronized block
+      #   @note to provide direct access to this method in a descendant add method
+      #     ```
+      #     def wait(timeout = nil)
+      #       synchronize { ns_wait(timeout) }
+      #     end
+      #     ```
+      def ns_wait(timeout = nil)
+        raise NotImplementedError
+      end
+
+      # @!macro synchronization_object_method_ns_signal
+      #
+      #   Signal one waiting thread.
+      #   @return [self]
+      #   @note only to be used inside synchronized block
+      #   @note to provide direct access to this method in a descendant add method
+      #     ```
+      #     def signal
+      #       synchronize { ns_signal }
+      #     end
+      #     ```
+      def ns_signal
+        raise NotImplementedError
+      end
+
+      # @!macro synchronization_object_method_ns_broadcast
+      #
+      #   Broadcast to all waiting threads.
+      #   @return [self]
+      #   @note only to be used inside synchronized block
+      #   @note to provide direct access to this method in a descendant add method
+      #     ```
+      #     def broadcast
+      #       synchronize { ns_broadcast }
+      #     end
+      #     ```
+      def ns_broadcast
+        raise NotImplementedError
+      end
+
+    end
+  end
+end