concurrent-ruby 1.0.5 → 1.1.0.pre1

data/lib/concurrent/atomic/atomic_reference.rb

@@ -1,51 +1,194 @@
 require 'concurrent/synchronization'
 require 'concurrent/utility/engine'
-require 'concurrent/atomic_reference/concurrent_update_error'
-require 'concurrent/atomic_reference/mutex_atomic'
-
-begin
-  # force fallback impl with FORCE_ATOMIC_FALLBACK=1
-  if /[^0fF]/ =~ ENV['FORCE_ATOMIC_FALLBACK']
-    ruby_engine = 'mutex_atomic'
-  else
-    ruby_engine = Concurrent.ruby_engine
-  end
+require 'concurrent/atomic_reference/numeric_cas_wrapper'
 
-  require "concurrent/atomic_reference/#{ruby_engine}"
-rescue LoadError
-  #warn 'Compiled extensions not installed, pure Ruby Atomic will be used.'
-end
+module Concurrent
 
-if defined? Concurrent::JavaAtomicReference
+  # Define update methods that use direct paths
+  #
+  # @!visibility private
+  # @!macro internal_implementation_note
+  module AtomicDirectUpdate
 
-  # @!macro atomic_reference
-  class Concurrent::AtomicReference < Concurrent::JavaAtomicReference
-  end
+    # @!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
 
-elsif defined? Concurrent::RbxAtomicReference
+    # @!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
 
-  # @!macro atomic_reference
-  class Concurrent::AtomicReference < Concurrent::RbxAtomicReference
+      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
 
-elsif defined? Concurrent::CAtomicReference
+  require 'concurrent/atomic_reference/mutex_atomic'
 
   # @!macro atomic_reference
-  class Concurrent::AtomicReference < Concurrent::CAtomicReference
+  #
+  #   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
 
-else
+  # @!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 < Truffle::AtomicReference
+                                      include AtomicDirectUpdate
+                                      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 Concurrent::AtomicReference < Concurrent::MutexAtomicReference
-  end
-end
+  class AtomicReference < AtomicReferenceImplementation
 
-class Concurrent::AtomicReference
-  # @return [String] Short string representation.
-  def to_s
-    format '<#%s:0x%x value:%s>', self.class, object_id << 1, get
-  end
+    # @return [String] Short string representation.
+    def to_s
+      format '%s value:%s>', super[0..-2], get
+    end
 
-  alias_method :inspect, :to_s
+    alias_method :inspect, :to_s
+  end
 end

data/lib/concurrent/atomic/count_down_latch.rb

@@ -6,7 +6,7 @@ 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/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/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/atomic/java_count_down_latch.rb

@@ -9,19 +9,20 @@ 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)
         if timeout.nil?
-          @latch.await
+          Synchronization::JRuby.sleep_interruptibly { @latch.await }
           true
         else
-          @latch.await(1000 * timeout, java.util.concurrent.TimeUnit::MILLISECONDS)
+          Synchronization::JRuby.sleep_interruptibly do
+            @latch.await(1000 * timeout, java.util.concurrent.TimeUnit::MILLISECONDS)
+          end
         end
       end
 

data/lib/concurrent/atomic/mutex_count_down_latch.rb

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

data/lib/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/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/atomic/semaphore.rb

@@ -5,7 +5,7 @@ module Concurrent
 
   ###################################################################
 
-  # @!macro [new] semaphore_method_initialize
+  # @!macro semaphore_method_initialize
   #
   #   Create a new `Semaphore` with the initial `count`.
   #
@@ -13,7 +13,7 @@ module Concurrent
   #
   #   @raise [ArgumentError] if `count` is not an integer or is less than zero
 
-  # @!macro [new] semaphore_method_acquire
+  # @!macro semaphore_method_acquire
   #
   #   Acquires the given number of permits from this semaphore,
   #     blocking until all are available.
@@ -25,19 +25,19 @@ module Concurrent
   #
   #   @return [nil]
 
-  # @!macro [new] semaphore_method_available_permits
+  # @!macro semaphore_method_available_permits
   #
   #   Returns the current number of permits available in this semaphore.
   #
   #   @return [Integer]
 
-  # @!macro [new] semaphore_method_drain_permits
+  # @!macro semaphore_method_drain_permits
   #
   #   Acquires and returns all permits that are immediately available.
   #
   #   @return [Integer]
 
-  # @!macro [new] semaphore_method_try_acquire
+  # @!macro semaphore_method_try_acquire
   #
   #   Acquires the given number of permits from this semaphore,
   #     only if all are available at the time of invocation or within
@@ -54,7 +54,7 @@ module Concurrent
   #   @return [Boolean] `false` if no permits are available, `true` when
   #     acquired a permit
 
-  # @!macro [new] semaphore_method_release
+  # @!macro semaphore_method_release
   #
   #   Releases the given number of permits, returning them to the semaphore.
   #
@@ -66,7 +66,7 @@ module Concurrent
 
   ###################################################################
 
-  # @!macro [new] semaphore_public_api
+  # @!macro semaphore_public_api
   #
   #   @!method initialize(count)
   #     @!macro semaphore_method_initialize
@@ -98,7 +98,7 @@ module Concurrent
                             end
   private_constant :SemaphoreImplementation
 
-  # @!macro [attach] semaphore
+  # @!macro semaphore
   #
   #   A counting semaphore. Conceptually, a semaphore maintains a set of
   #   permits. Each {#acquire} blocks if necessary until a permit is

data/lib/concurrent/atomic/thread_local_var.rb

@@ -6,7 +6,7 @@ module Concurrent
 
   ###################################################################
 
-  # @!macro [new] thread_local_var_method_initialize
+  # @!macro thread_local_var_method_initialize
   #
   #   Creates a thread local variable.
   #
@@ -14,20 +14,20 @@ module Concurrent
   #   @param [Proc] default_block Optional block that gets called to obtain the
   #     default value for each thread
 
-  # @!macro [new] thread_local_var_method_get
+  # @!macro thread_local_var_method_get
   #
   #   Returns the value in the current thread's copy of this thread-local variable.
   #
   #   @return [Object] the current value
 
-  # @!macro [new] thread_local_var_method_set
+  # @!macro thread_local_var_method_set
   #
   #   Sets the current thread's copy of this thread-local variable to the specified value.
   #
   #   @param [Object] value the value to set
   #   @return [Object] the new value
 
-  # @!macro [new] thread_local_var_method_bind
+  # @!macro thread_local_var_method_bind
   #
   #   Bind the given value to thread local storage during
   #   execution of the given block.
@@ -39,9 +39,9 @@ module Concurrent
 
   ###################################################################
 
-  # @!macro [new] thread_local_var_public_api
+  # @!macro thread_local_var_public_api
   #
-  #   @!method initialize(default = nil)
+  #   @!method initialize(default = nil, &default_block)
   #     @!macro thread_local_var_method_initialize
   #
   #   @!method value
@@ -65,7 +65,7 @@ module Concurrent
                                  end
   private_constant :ThreadLocalVarImplementation
 
-  # @!macro [attach] thread_local_var
+  # @!macro thread_local_var
   #
   #   A `ThreadLocalVar` is a variable where the value is different for each thread.
   #   Each variable may have a default value, but when you modify the variable only