AtomicMarkableReference: Add initial Ruby version

This commit adds a pure Ruby implementation of an AtomicMarkableReference. An
AtomicMarkableReference is much like an AtomicReference with that added
property that it can be, you guessed it, marked either true or false. They are
useful for implementing more advanced data sctructures such as recursive
split-ordered hash tables, etc.

Author: ianks

lib/concurrent.rb

@@ -9,6 +9,7 @@
 require 'concurrent/executors'
 require 'concurrent/utilities'
 
+require 'concurrent/atomic/atomic_markable_reference'
 require 'concurrent/atomic/atomic_reference'
 require 'concurrent/atom'
 require 'concurrent/async'

lib/concurrent/atomic/atomic_markable_reference.rb

@@ -0,0 +1,152 @@
+module Edge
+  module Concurrent
+    # @!macro atomic_markable_reference
+    class AtomicMarkableReference < ::Concurrent::Synchronization::Object
+      # TODO: Remove once out of edge module
+      include ::Concurrent
+
+      # @!macro [attach] atomic_markable_reference_method_initialize
+      def initialize(value = nil, mark = false)
+        super
+        @reference = AtomicReference.new ImmutableArray[value, mark]
+        ensure_ivar_visibility!
+      end
+
+      # @!macro [attach] atomic_markable_reference_method_compare_and_set
+      #
+      #   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] old_val the expected value
+      #   @param [Object] new_val the new value
+      #   @param [Boolean] old_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.get
+        curr_val, curr_mark = current
+
+        # Ensure that that the expected values match.
+        return false unless (expected_val == curr_val) &&
+                            (expected_mark == curr_mark)
+
+        # In this case, it would be redundant to set the fields. Just
+        # shortcircuit without wasting CPU time on CAS.
+        return true if (new_val == curr_val) &&
+                       (new_mark == curr_mark)
+
+        prospect = ImmutableArray[new_val, new_mark]
+
+        @reference.compare_and_set current, prospect
+      end
+
+      # @!macro [attach] atomic_markable_reference_method_get
+      #
+      #   Gets the current reference and marked values.
+      #
+      #   @return [ImmutableArray] the current reference and marked values
+      def get
+        @reference.get
+      end
+
+      # @!macro [attach] atomic_markable_reference_method_value
+      #
+      #   Gets the current value of the reference
+      #
+      #   @return [Object] the current value of the reference
+      def value
+        @reference.get[0]
+      end
+
+      # @!macro [attach] atomic_markable_reference_method_mark
+      #
+      #   Gets the current marked value
+      #
+      #   @return [Boolean] the current marked value
+      def mark
+        @reference.get[1]
+      end
+      alias_method :marked?, :mark
+
+      # @!macro [attach] atomic_markable_reference_method_set
+      #
+      #   _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 [ImmutableArray] both the new value and the new mark
+      def set(new_val, new_mark)
+        ImmutableArray[new_val, new_mark].tap do |pair|
+          @reference.set pair
+        end
+      end
+
+      # @!macro [attach] atomic_markable_reference_method_update
+      #
+      # 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 [ImmutableArray] the new value and new mark
+      def update
+        loop do
+          old_val, old_mark = value, marked?
+          new_val, new_mark = yield old_val, old_mark
+
+          if compare_and_set old_val, new_val, old_mark, new_mark
+            return ImmutableArray[new_val, new_mark]
+          end
+        end
+      end
+
+      # @!macro [attach] atomic_markable_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 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 [ImmutableArray] the new value and marked state
+      #
+      # @raise [Concurrent::ConcurrentUpdateError] if the update fails
+      def try_update
+        old_val, old_mark = value, marked?
+        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
+
+        ImmutableArray[new_val, new_mark]
+      end
+
+      # Internal/private ImmutableArray for representing pairs
+      class ImmutableArray < Array
+        def self.new(*args)
+          super(*args).freeze
+        end
+      end
+    end
+  end
+end

spec/concurrent/atomic/atomic_markable_reference_spec.rb

@@ -0,0 +1,160 @@
+# Concurrent::AtomicMarkableReference;w
+shared_examples :atomic_markable_reference do
+  # use a number outside JRuby's fixnum cache range, to ensure identity is
+  # preserved
+  let(:atomic) { Edge::Concurrent::AtomicMarkableReference.new 1000, true }
+
+  specify :test_construct do
+    expect(atomic.value).to eq 1000
+    expect(atomic.marked?).to eq true
+  end
+
+  specify :test_set do
+    val, mark = atomic.set(1001, true)
+
+    expect(atomic.value).to eq 1001
+    expect(atomic.marked?).to eq true
+
+    expect(val).to eq 1001
+    expect(mark).to eq true
+  end
+
+  specify :test_update do
+    val, mark = atomic.update { |v, m| [v + 1, !m] }
+
+    expect(atomic.value).to eq 1001
+    expect(atomic.marked?).to eq false
+
+    expect(val).to eq 1001
+    expect(mark).to eq false
+  end
+
+  specify :test_try_update do
+    val, mark = atomic.try_update { |v, m| [v + 1, !m] }
+
+    expect(atomic.value).to eq 1001
+
+    expect(val).to eq 1001
+    expect(mark).to eq false
+  end
+
+  specify :test_try_update_fails do
+    expect do
+      # assigning within block exploits implementation detail for test
+      atomic.try_update do |v, m|
+        atomic.set(1001, false)
+        [v + 1, !m]
+      end
+    end.to raise_error Concurrent::ConcurrentUpdateError
+  end
+
+  specify :test_update_retries do
+    tries = 0
+
+    # assigning within block exploits implementation detail for test
+    atomic.update do |v, m|
+      tries += 1
+      atomic.set(1001, false)
+      [v + 1, !m]
+    end
+
+    expect(tries).to eq 2
+  end
+
+  specify :test_numeric_cas do
+    # non-idempotent Float (JRuby, Rubinius, MRI < 2.0.0 or 32-bit)
+    atomic.set(1.0 + 0.1, true)
+    expect(atomic.compare_and_set(1.0 + 0.1, 1.2, true, false))
+      .to be_truthy, "CAS failed for (#{1.0 + 0.1}, true) => (1.2, false)"
+
+    # Bignum
+    atomic.set(2**100, false)
+    expect(atomic.compare_and_set(2**100, 2**99, false, true))
+      .to be_truthy, "CAS failed for (#{2**100}, false) => (0, true)"
+
+    # Rational
+    require 'rational' unless ''.respond_to? :to_r
+    atomic.set(Rational(1, 3), true)
+    expect(atomic.compare_and_set(Rational(1, 3), Rational(3, 1), true, false))
+      .to be_truthy, "CAS failed for (#{Rational(1, 3)}, true) => (0, false)"
+
+    # Complex
+    require 'complex' unless ''.respond_to? :to_c
+    atomic.set(Complex(1, 2), false)
+    expect(atomic.compare_and_set(Complex(1, 2), Complex(1, 3), false, true))
+      .to be_truthy, "CAS failed for (#{Complex(1, 2)}, false) => (0, false)"
+  end
+end
+
+# Specs for platform specific implementations
+module Edge
+  module Concurrent
+    describe AtomicMarkableReference do
+      it_should_behave_like :atomic_markable_reference
+    end
+
+    if defined? Concurrent::CAtomicMarkableReference
+      describe CAtomicMarkableReference do
+        skip 'Unimplemented'
+      end
+    elsif defined? Concurrent::JavaAtomicMarkableReference
+      describe JavaAtomicMarkableReference do
+        skip 'Unimplemented'
+      end
+    elsif defined? Concurrent::RbxAtomicMarkableReference
+      describe RbxAtomicMarkableReference do
+        skip 'Unimplemented'
+      end
+    end
+
+    describe AtomicMarkableReference do
+      if ::Concurrent.on_jruby?
+        it 'inherits from JavaAtomicMarkableReference' do
+          skip 'Unimplemented'
+        end
+      elsif ::Concurrent.allow_c_extensions?
+        it 'inherits from CAtomicMarkableReference' do
+          skip 'Unimplemented'
+        end
+      elsif ::Concurrent.on_rbx?
+        it 'inherits from RbxAtomicMarkableReference' do
+          skip 'Unimplemented'
+        end
+      else
+        it 'inherits from MutexAtomicMarkableReference' do
+          skip 'Unimplemented'
+        end
+      end
+    end
+
+    if defined? Concurrent::CAtomicMarkableReference
+      describe CAtomicMarkableReference do
+        skip 'Unimplemented'
+      end
+    elsif defined? Concurrent::JavaAtomicMarkableReference
+      describe JavaAtomicMarkableReference do
+        skip 'Unimplemented'
+      end
+    elsif defined? Concurrent::RbxAtomicMarkableReference
+      describe RbxAtomicMarkableReference do
+        skip 'Unimplemented'
+      end
+    end
+
+    describe AtomicMarkableReference do
+      if ::Concurrent.on_jruby?
+        it 'inherits from JavaAtomicMarkableReference' do
+          skip 'Unimplemented'
+        end
+      elsif ::Concurrent.allow_c_extensions?
+        it 'inherits from CAtomicMarkableReference' do
+          skip 'Unimplemented'
+        end
+      elsif ::Concurrent.on_rbx?
+        it 'inherits from RbxAtomicMarkableReference' do
+          skip 'Unimplemented'
+        end
+      end
+    end
+  end
+end