concurrent-ruby 1.0.5 → 1.1.10

data/lib/concurrent-ruby/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-ruby/concurrent/atomic/atomic_reference.rb

@@ -0,0 +1,205 @@
+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
+                                    TruffleRubyAtomicReference
+                                  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 → concurrent-ruby/concurrent}/atomic/count_down_latch.rb

@@ -1,12 +1,12 @@
+require 'concurrent/utility/engine'
 require 'concurrent/atomic/mutex_count_down_latch'
 require 'concurrent/atomic/java_count_down_latch'
-require 'concurrent/utility/engine'
 
 module Concurrent
 
   ###################################################################
 
-  # @!macro [new] count_down_latch_method_initialize
+  # @!macro count_down_latch_method_initialize
   #
   #   Create a new `CountDownLatch` with the initial `count`.
   #
@@ -14,7 +14,7 @@ module Concurrent
   #
   #   @raise [ArgumentError] if `count` is not an integer or is less than zero
 
-  # @!macro [new] count_down_latch_method_wait
+  # @!macro count_down_latch_method_wait
   #
   #   Block on the latch until the counter reaches zero or until `timeout` is reached.
   #
@@ -22,12 +22,12 @@ module Concurrent
   #     to block indefinitely
   #   @return [Boolean] `true` if the `count` reaches zero else false on `timeout`
 
-  # @!macro [new] count_down_latch_method_count_down
+  # @!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 [attach] count_down_latch_method_count
+  # @!macro count_down_latch_method_count
   #
   #   The current value of the counter.
   #
@@ -35,7 +35,7 @@ module Concurrent
 
   ###################################################################
 
-  # @!macro [new] count_down_latch_public_api
+  # @!macro count_down_latch_public_api
   #
   #   @!method initialize(count = 1)
   #     @!macro count_down_latch_method_initialize
@@ -61,7 +61,7 @@ module Concurrent
                                  end
   private_constant :CountDownLatchImplementation
 
-  # @!macro [attach] count_down_latch
+  # @!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

data/lib/{concurrent → concurrent-ruby/concurrent}/atomic/cyclic_barrier.rb

@@ -23,7 +23,7 @@ module Concurrent
   #   # use main as well
   #   process.call 2
   #
-  #   # here we can be sure that all jobs are processed  
+  #   # here we can be sure that all jobs are processed
   class CyclicBarrier < Synchronization::LockableObject
 
     # @!visibility private

data/lib/{concurrent → concurrent-ruby/concurrent}/atomic/event.rb

@@ -19,7 +19,7 @@ module Concurrent
   #   t1 = Thread.new do
   #     puts "t1 is waiting"
   #     event.wait(1)
-  #     puts "event ocurred"
+  #     puts "event occurred"
   #   end
   #
   #   t2 = Thread.new do
@@ -30,9 +30,9 @@ module Concurrent
   #   [t1, t2].each(&:join)
   #
   #   # prints:
-  #   # t2 calling set
   #   # t1 is waiting
-  #   # event ocurred
+  #   # t2 calling set
+  #   # event occurred
   class Event < Synchronization::LockableObject
 
     # Creates a new `Event` in the unset state. Threads calling `#wait` on the

data/lib/{concurrent → concurrent-ruby/concurrent}/atomic/java_count_down_latch.rb

@@ -9,20 +9,23 @@ if Concurrent.on_jruby?
 
       # @!macro count_down_latch_method_initialize
       def initialize(count = 1)
-        unless count.is_a?(Fixnum) && count >= 0
-          raise ArgumentError.new('count must be in integer greater than or equal zero')
-        end
+        Utility::NativeInteger.ensure_integer_and_bounds(count)
+        Utility::NativeInteger.ensure_positive(count)
         @latch = java.util.concurrent.CountDownLatch.new(count)
       end
 
       # @!macro count_down_latch_method_wait
       def wait(timeout = nil)
+        result = nil
         if timeout.nil?
-          @latch.await
-          true
+          Synchronization::JRuby.sleep_interruptibly { @latch.await }
+          result = true
         else
-          @latch.await(1000 * timeout, java.util.concurrent.TimeUnit::MILLISECONDS)
+          Synchronization::JRuby.sleep_interruptibly do
+            result = @latch.await(1000 * timeout, java.util.concurrent.TimeUnit::MILLISECONDS)
+          end
         end
+        result
       end
 
       # @!macro count_down_latch_method_count_down

data/lib/{concurrent → concurrent-ruby/concurrent}/atomic/mutex_atomic_boolean.rb

@@ -50,6 +50,8 @@ module Concurrent
       @value = !!initial
     end
 
+    private
+
     # @!visibility private
     def ns_make_value(value)
       old = @value

data/lib/{concurrent → concurrent-ruby/concurrent}/atomic/mutex_count_down_latch.rb

@@ -1,4 +1,5 @@
 require 'concurrent/synchronization'
+require 'concurrent/utility/native_integer'
 
 module Concurrent
 

data/lib/{concurrent → concurrent-ruby/concurrent}/atomic/mutex_semaphore.rb

@@ -23,7 +23,14 @@ module Concurrent
 
       synchronize do
         try_acquire_timed(permits, nil)
-        nil
+      end
+
+      return unless block_given?
+
+      begin
+        yield
+      ensure
+        release(permits)
       end
     end
 
@@ -48,13 +55,22 @@ module Concurrent
       Utility::NativeInteger.ensure_integer_and_bounds permits
       Utility::NativeInteger.ensure_positive permits
 
-      synchronize do
+      acquired = synchronize do
         if timeout.nil?
           try_acquire_now(permits)
         else
           try_acquire_timed(permits, timeout)
         end
       end
+
+      return acquired unless block_given?
+      return unless acquired
+
+      begin
+        yield
+      ensure
+        release(permits)
+      end
     end
 
     # @!macro semaphore_method_release

data/lib/{concurrent → concurrent-ruby/concurrent}/atomic/read_write_lock.rb

@@ -193,7 +193,8 @@ module Concurrent
     #
     # @return [Boolean] true if the lock is successfully released
     def release_write_lock
-      c = @Counter.update { |counter| counter-RUNNING_WRITER }
+      return true unless running_writer?
+      c = @Counter.update { |counter| counter - RUNNING_WRITER }
       @ReadLock.broadcast
       @WriteLock.signal if waiting_writers(c) > 0
       true

data/lib/{concurrent → concurrent-ruby/concurrent}/atomic/reentrant_read_write_lock.rb

@@ -21,7 +21,9 @@ module Concurrent
   # also acquire a read lock OR a write lock more than once. Only when the read (or
   # write) lock is released as many times as it was acquired, will the thread
   # actually let it go, allowing other threads which might have been waiting
-  # to proceed.
+  # to proceed. Therefore the lock can be upgraded by first acquiring
+  # read lock and then write lock and that the lock can be downgraded by first
+  # having both read and write lock a releasing just the write lock.
   #
   # If both read and write locks are acquired by the same thread, it is not strictly
   # necessary to release them in the same order they were acquired. In other words,
@@ -265,12 +267,10 @@ module Concurrent
         #   running right now, AND no writers who came before us still waiting to
         #   acquire the lock
         # Additionally, if any read locks have been taken, we must hold all of them
-        if c == held
-          # If we successfully swap the RUNNING_WRITER bit on, then we can go ahead
-          if @Counter.compare_and_set(c, c+RUNNING_WRITER)
-            @HeldCount.value = held + WRITE_LOCK_HELD
-            return true
-          end
+        if held > 0 && @Counter.compare_and_set(1, c+RUNNING_WRITER)
+          # If we are the only one reader and successfully swap the RUNNING_WRITER bit on, then we can go ahead
+          @HeldCount.value = held + WRITE_LOCK_HELD
+          return true
         elsif @Counter.compare_and_set(c, c+WAITING_WRITER)
           while true
             # Now we have successfully incremented, so no more readers will be able to increment