Class: Concurrent::AtomicMarkableReference

Inherits:
Synchronization::Object
  • Object
show all
Defined in:
lib/concurrent-ruby/concurrent/atomic/atomic_markable_reference.rb

Overview

An atomic reference which maintains an object reference along with a mark bit that can be updated atomically.

See Also:

Instance Method Summary collapse

Constructor Details

#initialize(value = nil, mark = false) ⇒ AtomicMarkableReference

Returns a new instance of AtomicMarkableReference.



15
16
17
18
 
# File 'lib/concurrent-ruby/concurrent/atomic/atomic_markable_reference.rb', line 15

def initialize(value = nil, mark = false)
  super()
  self.reference = immutable_array(value, mark)
end

Instance Method Details

#compare_and_set(expected_val, new_val, expected_mark, new_mark) ⇒ Boolean Also known as: compare_and_swap

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

that the actual value was not equal to the expected value or the actual mark was not equal to the expected mark

Parameters:

  • expected_val (Object) —

    the expected value

  • new_val (Object) —

    the new value

  • expected_mark (Boolean) —

    the expected mark

  • new_mark (Boolean) —

    the new mark

Returns:

  • (Boolean) —

    ‘true` if successful. A `false` return indicates



33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
 
# File 'lib/concurrent-ruby/concurrent/atomic/atomic_markable_reference.rb', line 33

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

#get ⇒ Array

Gets the current reference and marked values.

Returns:

  • (Array) —

    the current reference and marked values



64
65
66
 
# File 'lib/concurrent-ruby/concurrent/atomic/atomic_markable_reference.rb', line 64

def get
  reference
end

#mark ⇒ Boolean Also known as: marked?

Gets the current marked value

Returns:

  • (Boolean) —

    the current marked value



78
79
80
 
# File 'lib/concurrent-ruby/concurrent/atomic/atomic_markable_reference.rb', line 78

def mark
  reference[1]
end

#set(new_val, new_mark) ⇒ Array

Unconditionally sets to the given value of both the reference and the mark.

Parameters:

  • new_val (Object) —

    the new value

  • new_mark (Boolean) —

    the new mark

Returns:

  • (Array) —

    both the new value and the new mark



91
92
93
 
# File 'lib/concurrent-ruby/concurrent/atomic/atomic_markable_reference.rb', line 91

def set(new_val, new_mark)
  self.reference = immutable_array(new_val, new_mark)
end

#try_update {|Object| ... } ⇒ Array

Pass the current value to the given block, replacing it with the block’s result. Simply return nil if update fails.

the update failed

Yields:

  • (Object) —

    Calculate a new value and marked state for the atomic reference using given (old) value and (old) marked

Yield Parameters:

  • old_val (Object) —

    the starting value of the atomic reference

  • old_mark (Boolean) —

    the starting state of marked

Returns:

  • (Array) —

    the new value and marked state, or nil if



152
153
154
155
156
157
158
159
 
# File 'lib/concurrent-ruby/concurrent/atomic/atomic_markable_reference.rb', line 152

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

#try_update! {|Object| ... } ⇒ Array

Pass the current value to the given block, replacing it with the block’s result. Raise an exception if the update fails.

Yields:

  • (Object) —

    Calculate a new value and marked state for the atomic reference using given (old) value and (old) marked

Yield Parameters:

  • old_val (Object) —

    the starting value of the atomic reference

  • old_mark (Boolean) —

    the starting state of marked

Returns:

  • (Array) —

    the new value and marked state

Raises:



128
129
130
131
132
133
134
135
136
137
138
139
140
 
# File 'lib/concurrent-ruby/concurrent/atomic/atomic_markable_reference.rb', line 128

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

#update {|Object| ... } ⇒ Array

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.

Yields:

  • (Object) —

    Calculate a new value and marked state for the atomic reference using given (old) value and (old) marked

Yield Parameters:

  • old_val (Object) —

    the starting value of the atomic reference

  • old_mark (Boolean) —

    the starting state of marked

Returns:

  • (Array) —

    the new value and new mark



105
106
107
108
109
110
111
112
113
114
 
# File 'lib/concurrent-ruby/concurrent/atomic/atomic_markable_reference.rb', line 105

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

#value ⇒ Object

Gets the current value of the reference

Returns:

  • (Object) —

    the current value of the reference



71
72
73
 
# File 'lib/concurrent-ruby/concurrent/atomic/atomic_markable_reference.rb', line 71

def value
  reference[0]
end