concurrent-ruby 1.1.5

data/lib/concurrent/atomic/atomic_markable_reference.rb

@@ -0,0 +1,164 @@
+module Concurrent
+  # An atomic reference which maintains an object reference along with a mark bit
+  # that can be updated atomically.
+  #
+  # @see http://docs.oracle.com/javase/7/docs/api/java/util/concurrent/atomic/AtomicMarkableReference.html
+  #   java.util.concurrent.atomic.AtomicMarkableReference
+  class AtomicMarkableReference < ::Concurrent::Synchronization::Object
+
+    attr_atomic(:reference)
+    private :reference, :reference=, :swap_reference, :compare_and_set_reference, :update_reference
+
+    def initialize(value = nil, mark = false)
+      super()
+      self.reference = immutable_array(value, mark)
+    end
+
+    # Atomically sets the value and mark to the given updated value and
+    # mark given both:
+    #   - the current value == the expected value &&
+    #   - the current mark == the expected mark
+    #
+    # @param [Object] expected_val the expected value
+    # @param [Object] new_val the new value
+    # @param [Boolean] expected_mark the expected mark
+    # @param [Boolean] new_mark the new mark
+    #
+    # @return [Boolean] `true` if successful. A `false` return indicates
+    # that the actual value was not equal to the expected value or the
+    # actual mark was not equal to the expected mark
+    def compare_and_set(expected_val, new_val, expected_mark, new_mark)
+      # Memoize a valid reference to the current AtomicReference for
+      # later comparison.
+      current             = reference
+      curr_val, curr_mark = current
+
+      # Ensure that that the expected marks match.
+      return false unless expected_mark == curr_mark
+
+      if expected_val.is_a? Numeric
+        # If the object is a numeric, we need to ensure we are comparing
+        # the numerical values
+        return false unless expected_val == curr_val
+      else
+        # Otherwise, we need to ensure we are comparing the object identity.
+        # Theoretically, this could be incorrect if a user monkey-patched
+        # `Object#equal?`, but they should know that they are playing with
+        # fire at that point.
+        return false unless expected_val.equal? curr_val
+      end
+
+      prospect = immutable_array(new_val, new_mark)
+
+      compare_and_set_reference current, prospect
+    end
+
+    alias_method :compare_and_swap, :compare_and_set
+
+    # Gets the current reference and marked values.
+    #
+    # @return [Array] the current reference and marked values
+    def get
+      reference
+    end
+
+    # Gets the current value of the reference
+    #
+    # @return [Object] the current value of the reference
+    def value
+      reference[0]
+    end
+
+    # Gets the current marked value
+    #
+    # @return [Boolean] the current marked value
+    def mark
+      reference[1]
+    end
+
+    alias_method :marked?, :mark
+
+    # _Unconditionally_ sets to the given value of both the reference and
+    # the mark.
+    #
+    # @param [Object] new_val the new value
+    # @param [Boolean] new_mark the new mark
+    #
+    # @return [Array] both the new value and the new mark
+    def set(new_val, new_mark)
+      self.reference = immutable_array(new_val, new_mark)
+    end
+
+    # Pass the current value and marked state to the given block, replacing it
+    # with the block's results. May retry if the value changes during the
+    # block's execution.
+    #
+    # @yield [Object] Calculate a new value and marked state for the atomic
+    #   reference using given (old) value and (old) marked
+    # @yieldparam [Object] old_val the starting value of the atomic reference
+    # @yieldparam [Boolean] old_mark the starting state of marked
+    #
+    # @return [Array] the new value and new mark
+    def update
+      loop do
+        old_val, old_mark = reference
+        new_val, new_mark = yield old_val, old_mark
+
+        if compare_and_set old_val, new_val, old_mark, new_mark
+          return immutable_array(new_val, new_mark)
+        end
+      end
+    end
+
+    # Pass the current value to the given block, replacing it
+    # with the block's result. Raise an exception if the update
+    # fails.
+    #
+    # @yield [Object] Calculate a new value and marked state for the atomic
+    #   reference using given (old) value and (old) marked
+    # @yieldparam [Object] old_val the starting value of the atomic reference
+    # @yieldparam [Boolean] old_mark the starting state of marked
+    #
+    # @return [Array] the new value and marked state
+    #
+    # @raise [Concurrent::ConcurrentUpdateError] if the update fails
+    def try_update!
+      old_val, old_mark = reference
+      new_val, new_mark = yield old_val, old_mark
+
+      unless compare_and_set old_val, new_val, old_mark, new_mark
+        fail ::Concurrent::ConcurrentUpdateError,
+             'AtomicMarkableReference: Update failed due to race condition.',
+             'Note: If you would like to guarantee an update, please use ' +
+                 'the `AtomicMarkableReference#update` method.'
+      end
+
+      immutable_array(new_val, new_mark)
+    end
+
+    # Pass the current value to the given block, replacing it with the
+    # block's result. Simply return nil if update fails.
+    #
+    # @yield [Object] Calculate a new value and marked state for the atomic
+    #   reference using given (old) value and (old) marked
+    # @yieldparam [Object] old_val the starting value of the atomic reference
+    # @yieldparam [Boolean] old_mark the starting state of marked
+    #
+    # @return [Array] the new value and marked state, or nil if
+    # the update failed
+    def try_update
+      old_val, old_mark = reference
+      new_val, new_mark = yield old_val, old_mark
+
+      return unless compare_and_set old_val, new_val, old_mark, new_mark
+
+      immutable_array(new_val, new_mark)
+    end
+
+    private
+
+    def immutable_array(*args)
+      args.freeze
+    end
+  end
+end

data/lib/concurrent/atomic/atomic_reference.rb

@@ -0,0 +1,204 @@
+require 'concurrent/synchronization'
+require 'concurrent/utility/engine'
+require 'concurrent/atomic_reference/numeric_cas_wrapper'
+
+# Shim for TruffleRuby::AtomicReference
+if Concurrent.on_truffleruby? && !defined?(TruffleRuby::AtomicReference)
+  # @!visibility private
+  module TruffleRuby
+    AtomicReference = Truffle::AtomicReference
+  end
+end
+
+module Concurrent
+
+  # Define update methods that use direct paths
+  #
+  # @!visibility private
+  # @!macro internal_implementation_note
+  module AtomicDirectUpdate
+
+    # @!macro atomic_reference_method_update
+    #
+    #   Pass the current value to the given block, replacing it
+    #   with the block's result. May retry if the value changes
+    #   during the block's execution.
+    #
+    #   @yield [Object] Calculate a new value for the atomic reference using
+    #     given (old) value
+    #   @yieldparam [Object] old_value the starting value of the atomic reference
+    #   @return [Object] the new value
+    def update
+      true until compare_and_set(old_value = get, new_value = yield(old_value))
+      new_value
+    end
+
+    # @!macro atomic_reference_method_try_update
+    #
+    #   Pass the current value to the given block, replacing it
+    #   with the block's result. Return nil if the update fails.
+    #
+    #   @yield [Object] Calculate a new value for the atomic reference using
+    #     given (old) value
+    #   @yieldparam [Object] old_value the starting value of the atomic reference
+    #   @note This method was altered to avoid raising an exception by default.
+    #     Instead, this method now returns `nil` in case of failure. For more info,
+    #     please see: https://github.com/ruby-concurrency/concurrent-ruby/pull/336
+    #   @return [Object] the new value, or nil if update failed
+    def try_update
+      old_value = get
+      new_value = yield old_value
+
+      return unless compare_and_set old_value, new_value
+
+      new_value
+    end
+
+    # @!macro atomic_reference_method_try_update!
+    #
+    #   Pass the current value to the given block, replacing it
+    #   with the block's result. Raise an exception if the update
+    #   fails.
+    #
+    #   @yield [Object] Calculate a new value for the atomic reference using
+    #     given (old) value
+    #   @yieldparam [Object] old_value the starting value of the atomic reference
+    #   @note This behavior mimics the behavior of the original
+    #     `AtomicReference#try_update` API. The reason this was changed was to
+    #     avoid raising exceptions (which are inherently slow) by default. For more
+    #     info: https://github.com/ruby-concurrency/concurrent-ruby/pull/336
+    #   @return [Object] the new value
+    #   @raise [Concurrent::ConcurrentUpdateError] if the update fails
+    def try_update!
+      old_value = get
+      new_value = yield old_value
+      unless compare_and_set(old_value, new_value)
+        if $VERBOSE
+          raise ConcurrentUpdateError, "Update failed"
+        else
+          raise ConcurrentUpdateError, "Update failed", ConcurrentUpdateError::CONC_UP_ERR_BACKTRACE
+        end
+      end
+      new_value
+    end
+  end
+
+  require 'concurrent/atomic_reference/mutex_atomic'
+
+  # @!macro atomic_reference
+  #
+  #   An object reference that may be updated atomically. All read and write
+  #   operations have java volatile semantic.
+  #
+  #   @!macro thread_safe_variable_comparison
+  #
+  #   @see http://docs.oracle.com/javase/8/docs/api/java/util/concurrent/atomic/AtomicReference.html
+  #   @see http://docs.oracle.com/javase/8/docs/api/java/util/concurrent/atomic/package-summary.html
+  #
+  #   @!method initialize(value = nil)
+  #     @!macro atomic_reference_method_initialize
+  #       @param [Object] value The initial value.
+  #
+  #   @!method get
+  #     @!macro atomic_reference_method_get
+  #       Gets the current value.
+  #       @return [Object] the current value
+  #
+  #   @!method set(new_value)
+  #     @!macro atomic_reference_method_set
+  #       Sets to the given value.
+  #       @param [Object] new_value the new value
+  #       @return [Object] the new value
+  #
+  #   @!method get_and_set(new_value)
+  #     @!macro atomic_reference_method_get_and_set
+  #       Atomically sets to the given value and returns the old value.
+  #       @param [Object] new_value the new value
+  #       @return [Object] the old value
+  #
+  #   @!method compare_and_set(old_value, new_value)
+  #     @!macro atomic_reference_method_compare_and_set
+  #
+  #       Atomically sets the value to the given updated value if
+  #       the current value == the expected value.
+  #
+  #       @param [Object] old_value the expected value
+  #       @param [Object] new_value the new value
+  #
+  #       @return [Boolean] `true` if successful. A `false` return indicates
+  #       that the actual value was not equal to the expected value.
+  #
+  #   @!method update
+  #     @!macro atomic_reference_method_update
+  #
+  #   @!method try_update
+  #     @!macro atomic_reference_method_try_update
+  #
+  #   @!method try_update!
+  #     @!macro atomic_reference_method_try_update!
+
+
+  # @!macro internal_implementation_note
+  class ConcurrentUpdateError < ThreadError
+    # frozen pre-allocated backtrace to speed ConcurrentUpdateError
+    CONC_UP_ERR_BACKTRACE = ['backtrace elided; set verbose to enable'].freeze
+  end
+
+  # @!macro internal_implementation_note
+  AtomicReferenceImplementation = case
+                                  when Concurrent.on_cruby? && Concurrent.c_extensions_loaded?
+                                    # @!visibility private
+                                    # @!macro internal_implementation_note
+                                    class CAtomicReference
+                                      include AtomicDirectUpdate
+                                      include AtomicNumericCompareAndSetWrapper
+                                      alias_method :compare_and_swap, :compare_and_set
+                                    end
+                                    CAtomicReference
+                                  when Concurrent.on_jruby?
+                                    # @!visibility private
+                                    # @!macro internal_implementation_note
+                                    class JavaAtomicReference
+                                      include AtomicDirectUpdate
+                                    end
+                                    JavaAtomicReference
+                                  when Concurrent.on_truffleruby?
+                                    class TruffleRubyAtomicReference < TruffleRuby::AtomicReference
+                                      include AtomicDirectUpdate
+                                      alias_method :value, :get
+                                      alias_method :value=, :set
+                                      alias_method :compare_and_swap, :compare_and_set
+                                      alias_method :swap, :get_and_set
+                                    end
+                                  when Concurrent.on_rbx?
+                                    # @note Extends `Rubinius::AtomicReference` version adding aliases
+                                    #   and numeric logic.
+                                    #
+                                    # @!visibility private
+                                    # @!macro internal_implementation_note
+                                    class RbxAtomicReference < Rubinius::AtomicReference
+                                      alias_method :_compare_and_set, :compare_and_set
+                                      include AtomicDirectUpdate
+                                      include AtomicNumericCompareAndSetWrapper
+                                      alias_method :value, :get
+                                      alias_method :value=, :set
+                                      alias_method :swap, :get_and_set
+                                      alias_method :compare_and_swap, :compare_and_set
+                                    end
+                                    RbxAtomicReference
+                                  else
+                                    MutexAtomicReference
+                                  end
+  private_constant :AtomicReferenceImplementation
+
+  # @!macro atomic_reference
+  class AtomicReference < AtomicReferenceImplementation
+
+    # @return [String] Short string representation.
+    def to_s
+      format '%s value:%s>', super[0..-2], get
+    end
+
+    alias_method :inspect, :to_s
+  end
+end

data/lib/concurrent/atomic/count_down_latch.rb

@@ -0,0 +1,100 @@
+require 'concurrent/atomic/mutex_count_down_latch'
+require 'concurrent/atomic/java_count_down_latch'
+require 'concurrent/utility/engine'
+
+module Concurrent
+
+  ###################################################################
+
+  # @!macro count_down_latch_method_initialize
+  #
+  #   Create a new `CountDownLatch` with the initial `count`.
+  #
+  #   @param [new] count the initial count
+  #
+  #   @raise [ArgumentError] if `count` is not an integer or is less than zero
+
+  # @!macro count_down_latch_method_wait
+  #
+  #   Block on the latch until the counter reaches zero or until `timeout` is reached.
+  #
+  #   @param [Fixnum] timeout the number of seconds to wait for the counter or `nil`
+  #     to block indefinitely
+  #   @return [Boolean] `true` if the `count` reaches zero else false on `timeout`
+
+  # @!macro count_down_latch_method_count_down
+  #
+  #   Signal the latch to decrement the counter. Will signal all blocked threads when
+  #   the `count` reaches zero.
+
+  # @!macro count_down_latch_method_count
+  #
+  #   The current value of the counter.
+  #
+  #   @return [Fixnum] the current value of the counter
+
+  ###################################################################
+
+  # @!macro count_down_latch_public_api
+  #
+  #   @!method initialize(count = 1)
+  #     @!macro count_down_latch_method_initialize
+  #
+  #   @!method wait(timeout = nil)
+  #     @!macro count_down_latch_method_wait
+  #
+  #   @!method count_down
+  #     @!macro count_down_latch_method_count_down
+  #
+  #   @!method count
+  #     @!macro count_down_latch_method_count
+
+  ###################################################################
+
+  # @!visibility private
+  # @!macro internal_implementation_note
+  CountDownLatchImplementation = case
+                                 when Concurrent.on_jruby?
+                                   JavaCountDownLatch
+                                 else
+                                   MutexCountDownLatch
+                                 end
+  private_constant :CountDownLatchImplementation
+
+  # @!macro count_down_latch
+  #
+  #   A synchronization object that allows one thread to wait on multiple other threads.
+  #   The thread that will wait creates a `CountDownLatch` and sets the initial value
+  #   (normally equal to the number of other threads). The initiating thread passes the
+  #   latch to the other threads then waits for the other threads by calling the `#wait`
+  #   method. Each of the other threads calls `#count_down` when done with its work.
+  #   When the latch counter reaches zero the waiting thread is unblocked and continues
+  #   with its work. A `CountDownLatch` can be used only once. Its value cannot be reset.
+  #
+  # @!macro count_down_latch_public_api
+  # @example Waiter and Decrementer
+  #   latch = Concurrent::CountDownLatch.new(3)
+  #
+  #   waiter = Thread.new do
+  #     latch.wait()
+  #     puts ("Waiter released")
+  #   end
+  #
+  #   decrementer = Thread.new do
+  #     sleep(1)
+  #     latch.count_down
+  #     puts latch.count
+  #
+  #     sleep(1)
+  #     latch.count_down
+  #     puts latch.count
+  #
+  #     sleep(1)
+  #     latch.count_down
+  #     puts latch.count
+  #   end
+  #
+  #   [waiter, decrementer].each(&:join)
+  class CountDownLatch < CountDownLatchImplementation
+  end
+end