concurrent-ruby 1.0.5 → 1.1.1

data/lib/concurrent/agent.rb

@@ -129,7 +129,7 @@ module Concurrent
   # end
   # ```
   #
-  # @!macro [new] agent_await_warning
+  # @!macro agent_await_warning
   #
   #   **NOTE** Never, *under any circumstances*, call any of the "await" methods
   #   ({#await}, {#await_for}, {#await_for!}, and {#wait}) from within an action
@@ -147,7 +147,7 @@ module Concurrent
     ERROR_MODES = [:continue, :fail].freeze
     private_constant :ERROR_MODES
 
-    AWAIT_FLAG = Object.new
+    AWAIT_FLAG = ::Object.new
     private_constant :AWAIT_FLAG
 
     AWAIT_ACTION = ->(value, latch) { latch.count_down; AWAIT_FLAG }
@@ -242,7 +242,7 @@ module Concurrent
 
     alias_method :reason, :error
 
-    # @!macro [attach] agent_send
+    # @!macro agent_send
     #
     #   Dispatches an action to the Agent and returns immediately. Subsequently,
     #   in a thread from a thread pool, the {#value} will be set to the return
@@ -271,7 +271,7 @@ module Concurrent
     #     action
     #   @yieldreturn [Object] the new value of the Agent
     #
-    # @!macro [attach] send_return
+    # @!macro send_return
     #   @return [Boolean] true if the action is successfully enqueued, false if
     #     the Agent is {#failed?}
     def send(*args, &action)
@@ -280,7 +280,7 @@ module Concurrent
 
     # @!macro agent_send
     #
-    # @!macro [attach] send_bang_return_and_raise
+    # @!macro send_bang_return_and_raise
     #   @return [Boolean] true if the action is successfully enqueued
     #   @raise [Concurrent::Agent::Error] if the Agent is {#failed?}
     def send!(*args, &action)
@@ -326,7 +326,7 @@ module Concurrent
     #
     # @param [Proc] action the action dispatch to be enqueued
     # @return [Concurrent::Agent] self
-    # @see {#send_off}
+    # @see #send_off
     def <<(action)
       send_off(&action)
       self
@@ -397,7 +397,7 @@ module Concurrent
 
     # Is the Agent in a failed state?
     #
-    # @see {#restart}
+    # @see #restart
     def failed?
       !@error.value.nil?
     end

data/lib/concurrent/array.rb

@@ -2,38 +2,65 @@ require 'concurrent/utility/engine'
 require 'concurrent/thread_safe/util'
 
 module Concurrent
-  if Concurrent.on_cruby?
-
-    # Because MRI never runs code in parallel, the existing
-    # non-thread-safe structures should usually work fine.
-
-    # @!macro [attach] concurrent_array
-    #
-    #   A thread-safe subclass of Array. 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`.
-    #
-    #   @see http://ruby-doc.org/core-2.2.0/Array.html Ruby standard library `Array`
-    class Array < ::Array;
-    end
-
-  elsif Concurrent.on_jruby?
-    require 'jruby/synchronized'
-
-    # @!macro concurrent_array
-    class Array < ::Array
-      include JRuby::Synchronized
-    end
-
-  elsif Concurrent.on_rbx? || Concurrent.on_truffle?
-    require 'monitor'
-    require 'concurrent/thread_safe/util/array_hash_rbx'
-
-    # @!macro concurrent_array
-    class Array < ::Array
-    end
-
-    ThreadSafe::Util.make_synchronized_on_rbx Array
+
+  # @!macro concurrent_array
+  #
+  #   A thread-safe subclass of Array. 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::Array`. It reads array `a`, then it creates new `Concurrent::Array`
+  #   which is concatenation of `a` and `b`, then it writes the concatenation 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 `#concat` instead.
+  #
+  #   @see http://ruby-doc.org/core-2.2.0/Array.html Ruby standard library `Array`
+
+  # @!macro internal_implementation_note
+  ArrayImplementation = case
+                        when Concurrent.on_cruby?
+                          # Because MRI never runs code in parallel, the existing
+                          # non-thread-safe structures should usually work fine.
+                          ::Array
+
+                        when Concurrent.on_jruby?
+                          require 'jruby/synchronized'
+
+                          class JRubyArray < ::Array
+                            include JRuby::Synchronized
+                          end
+                          JRubyArray
+
+                        when Concurrent.on_rbx?
+                          require 'monitor'
+                          require 'concurrent/thread_safe/util/data_structures'
+
+                          class RbxArray < ::Array
+                          end
+
+                          ThreadSafe::Util.make_synchronized_on_rbx RbxArray
+                          RbxArray
+
+                        when Concurrent.on_truffleruby?
+                          require 'concurrent/thread_safe/util/data_structures'
+
+                          class TruffleRubyArray < ::Array
+                          end
+
+                          ThreadSafe::Util.make_synchronized_on_truffleruby TruffleRubyArray
+                          TruffleRubyArray
+
+                        else
+                          warn 'Possibly unsupported Ruby implementation'
+                          ::Array
+                        end
+  private_constant :ArrayImplementation
+
+  # @!macro concurrent_array
+  class Array < ArrayImplementation
   end
+
 end
 

data/lib/concurrent/async.rb

@@ -159,7 +159,7 @@ module Concurrent
   #
   # To get the state *at the current* time, irrespective of an enqueued method
   # calls, a reader method must be called directly. This is inherently unsafe
-  # unless the instance variable is itself thread-safe, preferrably using one
+  # unless the instance variable is itself thread-safe, preferably using one
   # of the thread-safe classes within this library. Because the thread-safe
   # classes within this library are internally-locking or non-locking, they can
   # be safely used from within asynchronous methods without causing deadlocks.
@@ -188,7 +188,7 @@ module Concurrent
   #
   # Class variables should be avoided. Class variables represent shared state.
   # Shared state is anathema to concurrency. Should there be a need to share
-  # state using class variables they *must* be thread-safe, preferrably
+  # state using class variables they *must* be thread-safe, preferably
   # using the thread-safe classes within this library. When updating class
   # variables, never assign a new value/object to the variable itself. Assignment
   # is not thread-safe in Ruby. Instead, use the thread-safe update functions
@@ -392,7 +392,7 @@ module Concurrent
     # object's thread. The final disposition of the method call can be obtained
     # by inspecting the returned future.
     #
-    # @!macro [attach] async_thread_safety_warning
+    # @!macro async_thread_safety_warning
     #   @note The method call is guaranteed to be thread safe with respect to
     #     all other method calls against the same object that are called with
     #     either `async` or `await`. The mutable nature of Ruby references
@@ -435,7 +435,7 @@ module Concurrent
     #
     # @!visibility private
     def init_synchronization
-      return self if @__async_initialized__
+      return self if defined?(@__async_initialized__) && @__async_initialized__
       @__async_initialized__ = true
       @__async_delegator__ = AsyncDelegator.new(self)
       @__await_delegator__ = AwaitDelegator.new(@__async_delegator__)

data/lib/concurrent/atom.rb

@@ -3,7 +3,7 @@ require 'concurrent/collection/copy_on_notify_observer_set'
 require 'concurrent/concern/observable'
 require 'concurrent/synchronization'
 
-# @!macro [new] thread_safe_variable_comparison
+# @!macro thread_safe_variable_comparison
 #
 #   ## Thread-safe Variable Classes
 #
@@ -96,8 +96,15 @@ module Concurrent
     include Concern::Observable
 
     safe_initialization!
-    private(*attr_atomic(:value))
+    attr_atomic(:value)
+    private :value=, :swap_value, :compare_and_set_value, :update_value
     public :value
+    alias_method :deref, :value
+
+    # @!method value
+    #   The current value of the atom.
+    #
+    #   @return [Object] The current value.
 
     # Create a new atom with the given initial value.
     #
@@ -118,13 +125,6 @@ module Concurrent
       self.value     = value
     end
 
-    # @!method value
-    #   The current value of the atom.
-    #
-    #   @return [Object] The current value.
-
-    alias_method :deref, :value
-
     # Atomically swaps the value of atom using the given block. The current
     # value will be passed to the block, as will any arguments passed as
     # arguments to the function. The new value will be validated against the

data/lib/concurrent/atomic/atomic_boolean.rb

@@ -5,19 +5,19 @@ module Concurrent
 
   ###################################################################
 
-  # @!macro [new] atomic_boolean_method_initialize
+  # @!macro atomic_boolean_method_initialize
   #
   #   Creates a new `AtomicBoolean` with the given initial value.
   #
   #   @param [Boolean] initial the initial value
 
-  # @!macro [new] atomic_boolean_method_value_get
+  # @!macro atomic_boolean_method_value_get
   #
   #   Retrieves the current `Boolean` value.
   #
   #   @return [Boolean] the current value
 
-  # @!macro [new] atomic_boolean_method_value_set
+  # @!macro atomic_boolean_method_value_set
   #
   #   Explicitly sets the value.
   #
@@ -25,25 +25,25 @@ module Concurrent
   #
   #   @return [Boolean] the current value
 
-  # @!macro [new] atomic_boolean_method_true_question
+  # @!macro atomic_boolean_method_true_question
   #
   #   Is the current value `true`
   #
   #   @return [Boolean] true if the current value is `true`, else false
 
-  # @!macro [new] atomic_boolean_method_false_question
+  # @!macro atomic_boolean_method_false_question
   #
   #   Is the current value `false`
   #
   #   @return [Boolean] true if the current value is `false`, else false
 
-  # @!macro [new] atomic_boolean_method_make_true
+  # @!macro atomic_boolean_method_make_true
   #
   #   Explicitly sets the value to true.
   #
   #   @return [Boolean] true is value has changed, otherwise false
 
-  # @!macro [new] atomic_boolean_method_make_false
+  # @!macro atomic_boolean_method_make_false
   #
   #   Explicitly sets the value to false.
   #
@@ -51,7 +51,7 @@ module Concurrent
 
   ###################################################################
 
-  # @!macro [new] atomic_boolean_public_api
+  # @!macro atomic_boolean_public_api
   #
   #   @!method initialize(initial = false)
   #     @!macro  atomic_boolean_method_initialize
@@ -88,7 +88,7 @@ module Concurrent
                                 end
   private_constant :AtomicBooleanImplementation
 
-  # @!macro [attach] atomic_boolean
+  # @!macro atomic_boolean
   #
   #   A boolean value that can be updated atomically. Reads and writes to an atomic
   #   boolean and thread-safe and guaranteed to succeed. Reads and writes may block
@@ -96,17 +96,21 @@ module Concurrent
   #
   #   @!macro thread_safe_variable_comparison
   #
-  #       Testing with ruby 2.1.2
-  #       Testing with Concurrent::MutexAtomicBoolean...
-  #         2.790000   0.000000   2.790000 (  2.791454)
-  #       Testing with Concurrent::CAtomicBoolean...
-  #         0.740000   0.000000   0.740000 (  0.740206)
+  #   Performance:
+  #
+  #   ```
+  #   Testing with ruby 2.1.2
+  #   Testing with Concurrent::MutexAtomicBoolean...
+  #     2.790000   0.000000   2.790000 (  2.791454)
+  #   Testing with Concurrent::CAtomicBoolean...
+  #     0.740000   0.000000   0.740000 (  0.740206)
   #
-  #       Testing with jruby 1.9.3
-  #       Testing with Concurrent::MutexAtomicBoolean...
-  #         5.240000   2.520000   7.760000 (  3.683000)
-  #       Testing with Concurrent::JavaAtomicBoolean...
-  #         3.340000   0.010000   3.350000 (  0.855000)
+  #   Testing with jruby 1.9.3
+  #   Testing with Concurrent::MutexAtomicBoolean...
+  #     5.240000   2.520000   7.760000 (  3.683000)
+  #   Testing with Concurrent::JavaAtomicBoolean...
+  #     3.340000   0.010000   3.350000 (  0.855000)
+  #   ```
   #
   #   @see http://docs.oracle.com/javase/7/docs/api/java/util/concurrent/atomic/AtomicBoolean.html java.util.concurrent.atomic.AtomicBoolean
   #
@@ -114,7 +118,7 @@ module Concurrent
   class AtomicBoolean < AtomicBooleanImplementation
     # @return [String] Short string representation.
     def to_s
-      format '<#%s:0x%x value:%s>', self.class, object_id << 1, value
+      format '%s value:%s>', super[0..-2], value
     end
 
     alias_method :inspect, :to_s

data/lib/concurrent/atomic/atomic_fixnum.rb

@@ -5,20 +5,20 @@ module Concurrent
 
   ###################################################################
 
-  # @!macro [new] atomic_fixnum_method_initialize
+  # @!macro atomic_fixnum_method_initialize
   #
   #   Creates a new `AtomicFixnum` with the given initial value.
   #
   #   @param [Fixnum] initial the initial value
   #   @raise [ArgumentError] if the initial value is not a `Fixnum`
 
-  # @!macro [new] atomic_fixnum_method_value_get
+  # @!macro atomic_fixnum_method_value_get
   #
   #   Retrieves the current `Fixnum` value.
   #
   #   @return [Fixnum] the current value
 
-  # @!macro [new] atomic_fixnum_method_value_set
+  # @!macro atomic_fixnum_method_value_set
   #
   #   Explicitly sets the value.
   #
@@ -28,7 +28,7 @@ module Concurrent
   #
   #   @raise [ArgumentError] if the new value is not a `Fixnum`
 
-  # @!macro [new] atomic_fixnum_method_increment
+  # @!macro atomic_fixnum_method_increment
   #
   #   Increases the current value by the given amount (defaults to 1).
   #
@@ -36,7 +36,7 @@ module Concurrent
   #
   #   @return [Fixnum] the current value after incrementation
 
-  # @!macro [new] atomic_fixnum_method_decrement
+  # @!macro atomic_fixnum_method_decrement
   #
   #   Decreases the current value by the given amount (defaults to 1).
   #
@@ -44,7 +44,7 @@ module Concurrent
   #
   #   @return [Fixnum] the current value after decrementation
 
-  # @!macro [new] atomic_fixnum_method_compare_and_set
+  # @!macro atomic_fixnum_method_compare_and_set
   #
   #   Atomically sets the value to the given updated value if the current
   #   value == the expected value.
@@ -52,9 +52,9 @@ module Concurrent
   #   @param [Fixnum] expect the expected value
   #   @param [Fixnum] update the new value
   #
-  #   @return [Fixnum] true if the value was updated else false
+  #   @return [Boolean] true if the value was updated else false
 
-  # @!macro [new] atomic_fixnum_method_update
+  # @!macro atomic_fixnum_method_update
   #
   #   Pass the current value to the given block, replacing it
   #   with the block's result. May retry if the value changes
@@ -68,7 +68,7 @@ module Concurrent
 
   ###################################################################
 
-  # @!macro [new] atomic_fixnum_public_api
+  # @!macro atomic_fixnum_public_api
   #
   #   @!method initialize(initial = 0)
   #     @!macro atomic_fixnum_method_initialize
@@ -79,10 +79,10 @@ module Concurrent
   #   @!method value=(value)
   #     @!macro atomic_fixnum_method_value_set
   #
-  #   @!method increment
+  #   @!method increment(delta)
   #     @!macro atomic_fixnum_method_increment
   #
-  #   @!method decrement
+  #   @!method decrement(delta)
   #     @!macro atomic_fixnum_method_decrement
   #
   #   @!method compare_and_set(expect, update)
@@ -105,7 +105,7 @@ module Concurrent
                                end
   private_constant :AtomicFixnumImplementation
 
-  # @!macro [attach] atomic_fixnum
+  # @!macro atomic_fixnum
   #
   #   A numeric value that can be updated atomically. Reads and writes to an atomic
   #   fixnum and thread-safe and guaranteed to succeed. Reads and writes may block
@@ -113,17 +113,21 @@ module Concurrent
   #
   #   @!macro thread_safe_variable_comparison
   #
-  #       Testing with ruby 2.1.2
-  #       Testing with Concurrent::MutexAtomicFixnum...
-  #         3.130000   0.000000   3.130000 (  3.136505)
-  #       Testing with Concurrent::CAtomicFixnum...
-  #         0.790000   0.000000   0.790000 (  0.785550)
+  #   Performance:
+  #
+  #   ```
+  #   Testing with ruby 2.1.2
+  #   Testing with Concurrent::MutexAtomicFixnum...
+  #     3.130000   0.000000   3.130000 (  3.136505)
+  #   Testing with Concurrent::CAtomicFixnum...
+  #     0.790000   0.000000   0.790000 (  0.785550)
   #
-  #       Testing with jruby 1.9.3
-  #       Testing with Concurrent::MutexAtomicFixnum...
-  #         5.460000   2.460000   7.920000 (  3.715000)
-  #       Testing with Concurrent::JavaAtomicFixnum...
-  #         4.520000   0.030000   4.550000 (  1.187000)
+  #   Testing with jruby 1.9.3
+  #   Testing with Concurrent::MutexAtomicFixnum...
+  #     5.460000   2.460000   7.920000 (  3.715000)
+  #   Testing with Concurrent::JavaAtomicFixnum...
+  #     4.520000   0.030000   4.550000 (  1.187000)
+  #   ```
   #
   #   @see http://docs.oracle.com/javase/7/docs/api/java/util/concurrent/atomic/AtomicLong.html java.util.concurrent.atomic.AtomicLong
   #
@@ -131,7 +135,7 @@ module Concurrent
   class AtomicFixnum < AtomicFixnumImplementation
     # @return [String] Short string representation.
     def to_s
-      format '<#%s:0x%x value:%s>', self.class, object_id << 1, value
+      format '%s value:%s>', super[0..-2], value
     end
 
     alias_method :inspect, :to_s

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