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.

Most of this code is shamelessly stolen from AtomicReference, and could likely
be condensed. Seeing as these are my first commits, I do not feel comfortable
embarking on such refactoring. So please feel free to rip this code in half and
have your will with it.

Author: ianks

lib/concurrent.rb

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

lib/concurrent/atomic/atomic_markable_reference.rb

@@ -0,0 +1,6 @@
+require 'concurrent/atomic_reference/mutex_markable_atomic'
+
+# @!macro atomic_markable_reference
+module Concurrent
+  class AtomicMarkableReference < MutexAtomicMarkableReference; end
+end

lib/concurrent/atomic_reference/mutex_markable_atomic.rb

@@ -0,0 +1,139 @@
+require 'thread'
+require 'concurrent/atomic_reference/numeric_cas_wrapper'
+
+module Concurrent
+  # @!macro atomic_markable_reference
+  class MutexAtomicMarkableReference
+    include AtomicNumericCompareAndSetWrapper
+
+    # @!macro [attach] atomic_markable_reference_method_initialize
+    def initialize(value = nil, marked = false)
+      @mutex = Mutex.new
+      @value, @marked = value, marked
+    end
+
+    # @!macro [attach] atomic_markable_reference_method_get
+    #
+    #   Gets the current reference and marked values.
+    #
+    #   @return [Array] the current reference and marked values
+    def get
+      @mutex.synchronize { [@value, @marked] }
+    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
+      @mutex.synchronize { @value }
+    end
+
+    # @!macro [attach] atomic_markable_reference_method_marked?
+    #
+    #   Gets the current marked value
+    #
+    #   @return [Boolean] the current marked value
+    def marked?
+      @mutex.synchronize { @marked }
+    end
+    alias_method :marked, :marked?
+
+    # @!macro [attach] atomic_markable_reference_method_set
+    #
+    #   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)
+      @mutex.synchronize do
+        @value, @marked = new_val, new_mark
+
+        [@value, @marked]
+      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 [Array] 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 [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 [Array] 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
+        err = [ConcurrentUpdateError, 'Update failed']
+        err << ConcurrentUpdateError::CONC_UP_ERR_BACKTRACE if $VERBOSE
+
+        fail(*err)
+      end
+
+      [new_val, new_mark]
+    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(old_val, new_val, old_mark, new_mark) #:nodoc:
+      return false unless @mutex.try_lock
+
+      begin
+        return false unless @value.equal?(old_val) && @marked == old_mark
+
+        @value, @marked = new_val, new_mark
+      ensure
+        @mutex.unlock
+      end
+
+      true
+    end
+  end
+end

lib/concurrent/atomic_reference/numeric_cas_wrapper.rb

@@ -4,20 +4,23 @@ module Concurrent
   module AtomicNumericCompareAndSetWrapper
 
     # @!macro atomic_reference_method_compare_and_set
-    def compare_and_set(old_value, new_value)
+    def compare_and_set(*args)
+      old_value = args[0]
+
       if old_value.kind_of? Numeric
         while true
-          old = get
+          old = value
 
           return false unless old.kind_of? Numeric
-
           return false unless old == old_value
 
-          result = _compare_and_set(old, new_value)
+          args[0] = old
+          result = _compare_and_set(*args)
+
           return result if result
         end
       else
-        _compare_and_set(old_value, new_value)
+        _compare_and_set(*args)
       end
     end
     alias_method :compare_and_swap, :compare_and_set

spec/concurrent/atomic/atomic_markable_reference_spec.rb

@@ -13,15 +13,15 @@
     res = atomic.set(1001, true)
 
     expect(atomic.value).to eq 1001
-    expect(atomic.marked).to eq true
+    expect(atomic.marked?).to eq true
     expect(res).to eq [1001, true]
   end
 
   specify :test_update do
     res = atomic.update { |v, m| [v + 1, !m] }
 
     expect(atomic.marked?).to eq false
-    expect(atomic.get_reference).to eq 1001
+    expect(atomic.value).to eq 1001
     expect(res).to eq [1001, false]
   end