concurrent-ruby 1.0.5 → 1.1.6

data/lib/concurrent-ruby/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 → 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

@@ -32,7 +32,7 @@ module Concurrent
   #   # prints:
   #   # t2 calling set
   #   # t1 is waiting
-  #   # event ocurred
+  #   # 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/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,

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

@@ -32,12 +32,38 @@ module Concurrent
     FREE   = []
     LOCK   = Mutex.new
     ARRAYS = {} # used as a hash set
+    # noinspection RubyClassVariableUsageInspection
     @@next = 0
-    private_constant :FREE, :LOCK, :ARRAYS
+    QUEUE  = Queue.new
+    THREAD = Thread.new do
+      while true
+        method, i = QUEUE.pop
+        case method
+        when :thread_local_finalizer
+          LOCK.synchronize do
+            FREE.push(i)
+            # The cost of GC'ing a TLV is linear in the number of threads using TLVs
+            # But that is natural! More threads means more storage is used per TLV
+            # So naturally more CPU time is required to free more storage
+            ARRAYS.each_value do |array|
+              array[i] = nil
+            end
+          end
+        when :thread_finalizer
+          LOCK.synchronize do
+            # The thread which used this thread-local array is now gone
+            # So don't hold onto a reference to the array (thus blocking GC)
+            ARRAYS.delete(i)
+          end
+        end
+      end
+    end
+
+    private_constant :FREE, :LOCK, :ARRAYS, :QUEUE, :THREAD
 
     # @!macro thread_local_var_method_get
     def value
-      if array = get_threadlocal_array
+      if (array = get_threadlocal_array)
         value = array[@index]
         if value.nil?
           default
@@ -57,10 +83,10 @@ module Concurrent
       # We could keep the thread-local arrays in a hash, keyed by Thread
       # But why? That would require locking
       # Using Ruby's built-in thread-local storage is faster
-      unless array = get_threadlocal_array(me)
+      unless (array = get_threadlocal_array(me))
         array = set_threadlocal_array([], me)
         LOCK.synchronize { ARRAYS[array.object_id] = array }
-        ObjectSpace.define_finalizer(me, self.class.thread_finalizer(array))
+        ObjectSpace.define_finalizer(me, self.class.thread_finalizer(array.object_id))
       end
       array[@index] = (value.nil? ? NULL : value)
       value
@@ -69,6 +95,7 @@ module Concurrent
     protected
 
     # @!visibility private
+    # noinspection RubyClassVariableUsageInspection
     def allocate_storage
       @index = LOCK.synchronize do
         FREE.pop || begin
@@ -77,37 +104,19 @@ module Concurrent
           result
         end
       end
-      ObjectSpace.define_finalizer(self, self.class.threadlocal_finalizer(@index))
+      ObjectSpace.define_finalizer(self, self.class.thread_local_finalizer(@index))
     end
 
     # @!visibility private
-    def self.threadlocal_finalizer(index)
-      proc do
-        Thread.new do # avoid error: can't be called from trap context
-          LOCK.synchronize do
-            FREE.push(index)
-            # The cost of GC'ing a TLV is linear in the number of threads using TLVs
-            # But that is natural! More threads means more storage is used per TLV
-            # So naturally more CPU time is required to free more storage
-            ARRAYS.each_value do |array|
-              array[index] = nil
-            end
-          end
-        end
-      end
+    def self.thread_local_finalizer(index)
+      # avoid error: can't be called from trap context
+      proc { QUEUE.push [:thread_local_finalizer, index] }
     end
 
     # @!visibility private
-    def self.thread_finalizer(array)
-      proc do
-        Thread.new do # avoid error: can't be called from trap context
-          LOCK.synchronize do
-            # The thread which used this thread-local array is now gone
-            # So don't hold onto a reference to the array (thus blocking GC)
-            ARRAYS.delete(array.object_id)
-          end
-        end
-      end
+    def self.thread_finalizer(id)
+      # avoid error: can't be called from trap context
+      proc { QUEUE.push [:thread_finalizer, id] }
     end
 
     private
@@ -136,21 +145,22 @@ module Concurrent
     # This exists only for use in testing
     # @!visibility private
     def value_for(thread)
-      if array = get_threadlocal_array(thread)
+      if (array = get_threadlocal_array(thread))
         value = array[@index]
         if value.nil?
-          default_for(thread)
+          get_default
         elsif value.equal?(NULL)
           nil
         else
           value
         end
       else
-        default_for(thread)
+        get_default
       end
     end
 
-    def default_for(thread)
+    # @!visibility private
+    def get_default
       if @default_block
         raise "Cannot use default_for with default block"
       else