struct

Atomic(T)

Inherits Struct / Value / Object

A value that may be updated atomically.

  • If T is a reference type, or a union type containing only reference types or Nil, then only #compare_and_set, #swap, #set, #lazy_set, #get, and #lazy_get are available.
  • If T is a pointer type, then the above methods plus #max and #min are available.
  • If T is a non-union primitive integer type or enum type, then all operations are supported.

Constructors

new(value : T)

Creates an Atomic with the given initial value.

Source

Instance methods

add(value : T, ordering : Ordering = :sequentially_consistent) : T

Performs atomic_value &+= value. Returns the old value.

T cannot contain any pointer or reference types.

atomic = Atomic.new(1)
atomic.add(2) # => 1
atomic.get    # => 3
Source
and(value : T, ordering : Ordering = :sequentially_consistent) : T

Performs atomic_value &= value. Returns the old value.

T cannot contain any pointer or reference types.

atomic = Atomic.new(5)
atomic.and(3) # => 5
atomic.get    # => 1
Source
compare_and_set(cmp : T, new : T, success_ordering : Ordering, failure_ordering : Ordering) : Tuple(T, Bool)

Compares this atomic's value with cmp using explicit memory orderings:

  • if they are equal, sets the value to new, and returns {old_value, true}
  • if they are not equal the value remains the same, and returns {old_value, false}

Reference types are compared by #same?, not #==.

atomic = Atomic.new(0_u32)

value = atomic.get(:acquire)
loop do
  value, success = atomic.compare_and_set(value, value &+ 1, :acquire_release, :acquire)
  break if success
end
Source
compare_and_set(cmp : T, new : T) : Tuple(T, Bool)

Compares this atomic's value with cmp:

  • if they are equal, sets the value to new, and returns {old_value, true}
  • if they are not equal the value remains the same, and returns {old_value, false}

Reference types are compared by #same?, not #==.

atomic = Atomic.new(1)

atomic.compare_and_set(2, 3) # => {1, false}
atomic.get                   # => 1

atomic.compare_and_set(1, 3) # => {1, true}
atomic.get                   # => 3
Source
get(ordering : Ordering = :sequentially_consistent) : T

Atomically returns this atomic's value.

Source
lazy_get

Non-atomically returns this atomic's value.

NOTE: use with caution, this may break atomic guarantees.

Source
lazy_set(value : T) : T

Non-atomically sets this atomic's value to value. Returns the new value.

atomic = Atomic.new(5)
atomic.lazy_set(10) # => 10
atomic.get          # => 10

NOTE: use with caution, this may break atomic guarantees.

Source
max(value : T, ordering : Ordering = :sequentially_consistent)

Performs atomic_value = {atomic_value, value}.max. Returns the old value.

T cannot contain any reference types.

atomic = Atomic.new(5)

atomic.max(3) # => 5
atomic.get    # => 5

atomic.max(10) # => 5
atomic.get     # => 10
Source
min(value : T, ordering : Ordering = :sequentially_consistent)

Performs atomic_value = {atomic_value, value}.min. Returns the old value.

T cannot contain any reference types.

atomic = Atomic.new(5)

atomic.min(10) # => 5
atomic.get     # => 5

atomic.min(3) # => 5
atomic.get    # => 3
Source
nand(value : T, ordering : Ordering = :sequentially_consistent) : T

Performs atomic_value = ~(atomic_value & value). Returns the old value.

T cannot contain any pointer or reference types.

atomic = Atomic.new(5)
atomic.nand(3) # => 5
atomic.get     # => -2
Source
or(value : T, ordering : Ordering = :sequentially_consistent) : T

Performs atomic_value |= value. Returns the old value.

T cannot contain any pointer or reference types.

atomic = Atomic.new(5)
atomic.or(2) # => 5
atomic.get   # => 7
Source
set(value : T, ordering : Ordering = :sequentially_consistent) : T

Atomically sets this atomic's value to value. Returns the new value.

atomic = Atomic.new(5)
atomic.set(10) # => 10
atomic.get     # => 10
Source
sub(value : T, ordering : Ordering = :sequentially_consistent) : T

Performs atomic_value &-= value. Returns the old value.

T cannot contain any pointer or reference types.

atomic = Atomic.new(9)
atomic.sub(2) # => 9
atomic.get    # => 7
Source
swap(value : T, ordering : Ordering = :sequentially_consistent)

Atomically sets this atomic's value to value. Returns the old value.

atomic = Atomic.new(5)
atomic.swap(10) # => 5
atomic.get      # => 10
Source
xor(value : T, ordering : Ordering = :sequentially_consistent) : T

Performs atomic_value ^= value. Returns the old value.

T cannot contain any pointer or reference types.

atomic = Atomic.new(5)
atomic.xor(3) # => 5
atomic.get    # => 6
Source

Macros

fence(ordering = :sequentially_consistent)

Adds an explicit memory barrier with the specified memory order guarantee.

Source

Nested types