Edit

Share via

atomic Structure

  • Article

Describes an object that performs atomic operations on a stored value of type Ty.

Syntax

template <class Ty>
struct atomic;

Members

Member Description
Constructor
atomic Constructs an atomic object.
Operators
atomic::operator Ty Reads and returns the stored value. (atomic::load)
atomic::operator= Uses a specified value to replace the stored value. (atomic::store)
atomic::operator++ Increments the stored value. Used only by integral and pointer specializations.
atomic::operator+= Adds a specified value to the stored value. Used only by integral and pointer specializations.
atomic::operator-- Decrements the stored value. Used only by integral and pointer specializations.
atomic::operator-= Subtracts a specified value from the stored value. Used only by integral and pointer specializations.
atomic::operator&= Performs a bitwise "and" (&) on a specified value and the stored value. Used only by integral specializations.
atomic::operator|= Performs a bitwise "or" (|) on a specified value and the stored value. Used only by integral specializations.
atomic::operator^= Performs a bitwise "exclusive or" (^) on a specified value and the stored value. Used only by integral specializations.
Functions
compare_exchange_strong Performs an atomic_compare_and_exchange operation on this and returns the result.
compare_exchange_weak Performs a weak_atomic_compare_and_exchange operation on this and returns the result.
fetch_add Adds a specified value to the stored value.
fetch_and Performs a bitwise "and" (&) on a specified value and the stored value.
fetch_or Performs a bitwise "or" (|) on a specified value and the stored value.
fetch_sub Subtracts a specified value from the stored value.
fetch_xor Performs a bitwise "exclusive or" (^) on a specified value and the stored value.
is_lock_free Specifies whether atomic operations on this are lock free. An atomic type is lock free if no atomic operations on that type use locks.
load Reads and returns the stored value.
store Uses a specified value to replace the stored value.

Remarks

The type Ty must be trivially copyable. That is, using memcpy to copy its bytes must produce a valid Ty object that compares equal to the original object. The compare_exchange_weak and compare_exchange_strong member functions use memcmp to determine whether two Ty values are equal. These functions won't use a Ty-defined operator==. The member functions of atomic use memcpy to copy values of type Ty.

A partial specialization, atomic<Ty*>, exists for all pointer types. The specialization enables the addition of an offset to the managed pointer value or the subtraction of an offset from it. The arithmetic operations take an argument of type ptrdiff_t and adjust that argument according to the size of Ty to be consistent with ordinary address arithmetic.

A specialization exists for every integral type except bool. Each specialization provides a rich set of methods for atomic arithmetic and logical operations.

atomic<char>
atomic<signed char>
atomic<unsigned char>
atomic<char16_t>
atomic<char32_t>
atomic<wchar_t>
atomic<short>

atomic<unsigned short>
atomic<int>
atomic<unsigned int>
atomic<long>
atomic<unsigned long>
atomic<long long>
atomic<unsigned long long>

Integral specializations are derived from corresponding atomic_integral types. For example, atomic<unsigned int> is derived from atomic_uint.

Requirements

Header: <atomic>

Namespace: std

atomic::atomic

Constructs an atomic object.

atomic();
atomic( const atomic& );
atomic( Ty Value ) noexcept;

Parameters

Value
Initialization value.

Remarks

Atomic objects can't be copied or moved.

Objects that are instantiations of atomic<Ty> can be initialized only by the constructor that takes an argument of type Ty and not by using aggregate initialization. However, atomic_integral objects can be initialized only by using aggregate initialization.

atomic<int> ai0 = ATOMIC_VAR_INIT(0);
atomic<int> ai1(0);

atomic::operator Ty

The operator for the type specified to the template, atomic<Ty>. Retrieves the stored value in *this.

atomic<Ty>::operator Ty() const volatile noexcept;
atomic<Ty>::operator Ty() const noexcept;

Remarks

This operator applies the memory_order_seq_cst memory_order.

atomic::operator=

Stores a specified value.

Ty operator=(
   Ty Value
) volatile noexcept;
Ty operator=(
   Ty Value
) noexcept;

Parameters

Value
A Ty object.

Return Value

Returns Value.

atomic::operator++

Increments the stored value. Used only by integral and pointer specializations.

Ty atomic<Ty>::operator++(int) volatile noexcept;
Ty atomic<Ty>::operator++(int) noexcept;
Ty atomic<Ty>::operator++() volatile noexcept;
Ty atomic<Ty>::operator++() noexcept;

Return Value

The first two operators return the incremented value; the last two operators return the value before the increment. The operators use the memory_order_seq_cst memory_order.

atomic::operator+=

Adds a specified value to the stored value. Used only by integral and pointer specializations.

Ty atomic<Ty>::operator+=(
   Ty Value
) volatile noexcept;
Ty atomic<Ty>::operator+=(
   Ty Value
) noexcept;

Parameters

Value
An integral or pointer value.

Return Value

A Ty object that contains the result of the addition.

Remarks

This operator uses the memory_order_seq_cst memory_order.

atomic::operator--

Decrements the stored value. Used only by integral and pointer specializations.

Ty atomic<Ty>::operator--(int) volatile noexcept;
Ty atomic<Ty>::operator--(int) noexcept;
Ty atomic<Ty>::operator--() volatile noexcept;
Ty atomic<Ty>::operator--() noexcept;

Return Value

The first two operators return the decremented value; the last two operators return the value before the decrement. The operators use the memory_order_seq_cst memory_order.

atomic::operator-=

Subtracts a specified value from the stored value. Used only by integral and pointer specializations.

Ty atomic<Ty>::operator-=(
   Ty Value
) volatile noexcept;
Ty atomic<Ty>::operator-=(
   Ty Value
) noexcept;

Parameters

Value
An integral or pointer value.

Return Value

A Ty object that contains the result of the subtraction.

Remarks

This operator uses the memory_order_seq_cst memory_order.

atomic::operator&=

Performs a bitwise "and" (&) on a specified value and the stored value of *this. Used only by integral specializations.

atomic<Ty>::operator&= (
   Ty Value
) volatile noexcept;
atomic<Ty>::operator&= (
   Ty Value
) noexcept;

Parameters

Value
A value of type Ty.

Return Value

The result of the bitwise "and" (&).

Remarks

This operator performs a read-modify-write operation to replace the stored value of *this with a bitwise "and" (&) of Value and the current value that is stored in *this, within the constraints of the memory_order_seq_cst memory_order.

atomic::operator|=

Performs a bitwise "or" (|) on a specified value and the stored value of *this. Used only by integral specializations.

atomic<Ty>::operator|= (
   Ty Value
) volatile noexcept;
atomic<Ty>::operator|= (
   Ty Value
) noexcept;

Parameters

Value
A value of type Ty.

Return Value

The result of the bitwise "or" (|).

Remarks

This operator performs a read-modify-write operation to replace the stored value of *this with a bitwise "or" (|) of Value and the current value that is stored in *this, within the constraints of the memory_order_seq_cst memory_order constraints.

atomic::operator^=

Performs a bitwise "exclusive or" (^) on a specified value and the stored value of *this. Used only by integral specializations.

atomic<Ty>::operator^= (
   Ty Value
) volatile noexcept;
atomic<Ty>::operator^= (
   Ty Value
) noexcept;

Parameters

Value
A value of type Ty.

Return Value

The result of the bitwise "exclusive or" (^).

Remarks

This operator performs a read-modify-write operation to replace the stored value of *this with a bitwise "exclusive or" (^) of Value and the current value that is stored in *this, within the constraints of the memory_order_seq_cst memory_order constraints.

atomic::compare_exchange_strong

Performs an atomic compare and exchange operation on *this.

bool compare_exchange_strong(
   Ty& Exp,
   Ty Value,
   memory_order Order1,
   memory_order Order2
) volatile noexcept;
bool compare_exchange_strong(
   Ty& Exp,
   Ty Value,
   memory_order Order1,
   memory_order Order2
) noexcept;
bool compare_exchange_strong(
   Ty& Exp,
   Ty Value,
   memory_order Order1 = memory_order_seq_cst
) volatile noexcept;
bool compare_exchange_strong(
   Ty& Exp,
   Ty Value,
   memory_order Order1 = memory_order_seq_cst
) noexcept;

Parameters

Exp
A value of type Ty.

Value
A value of type Ty.

Order1
First memory_order argument.

Order2
Second memory_order argument.

Return Value

A bool that indicates the result of the value comparison.

Remarks

This atomic compare and exchange operation compares the value that is stored in *this with Exp. If the values are equal, the operation replaces the value that is stored in *this with Value by using a read-modify-write operation and applying the memory order constraints that are specified by Order1. If the values aren't equal, the operation uses the value that is stored in *this to replace Exp and applies the memory order constraints that are specified by Order2.

Overloads that don't have a second memory_order use an implicit Order2 that is based on the value of Order1. If Order1 is memory_order_acq_rel, Order2 is memory_order_acquire. If Order1 is memory_order_release, Order2 is memory_order_relaxed. In all other cases, Order2 is equal to Order1.

For overloads that take two memory_order parameters, the value of Order2 must not be memory_order_release or memory_order_acq_rel, and must not be stronger than the value of Order1.

atomic::compare_exchange_weak

Performs a weak atomic compare and exchange operation on *this.

bool compare_exchange_weak(
   Ty& Exp,
   Ty Value,
   memory_order Order1,
   memory_order Order2
) volatile noexcept;
bool compare_exchange_weak(
   Ty& Exp,
   Ty Value,
   memory_order Order1,
   memory_order Order2
) noexcept;
bool compare_exchange_weak(
   Ty& Exp,
   Ty Value,
   memory_order Order1 = memory_order_seq_cst
) volatile noexcept;
bool compare_exchange_weak(
   Ty& Exp,
   Ty Value,
   memory_order Order1 = memory_order_seq_cst
) noexcept;

Parameters

Exp
A value of type Ty.

Value
A value of type Ty.

Order1
First memory_order argument.

Order2
Second memory_order argument.

Return Value

A bool that indicates the result of the value comparison.

Remarks

This atomic compare and exchange operation compares the value that is stored in *this with Exp. If the values are equal, the operation replaces the value that is stored in *this with Value by using a read-modify-write operation and applying the memory order constraints that are specified by Order1. If the values aren't equal, the operation uses the value that is stored in *this to replace Exp and applies the memory order constraints that are specified by Order2.

A weak atomic compare and exchange operation performs an exchange if the compared values are equal. If the values aren't equal, the operation isn't guaranteed to perform an exchange.

Overloads that don't have a second memory_order use an implicit Order2 that is based on the value of Order1. If Order1 is memory_order_acq_rel, Order2 is memory_order_acquire. If Order1 is memory_order_release, Order2 is memory_order_relaxed. In all other cases, Order2 is equal to Order1.

For overloads that take two memory_order parameters, the value of Order2 must not be memory_order_release or memory_order_acq_rel, and must not be stronger than the value of Order1.

atomic::exchange

Uses a specified value to replace the stored value of *this.

Ty atomic<Ty>::exchange(
   Ty Value,
   memory_order Order = memory_order_seq_cst
) volatile noexcept;
Ty atomic<Ty>::exchange(
   Ty Value,
   memory_order Order = memory_order_seq_cst
) noexcept;

Parameters

Value
A value of type Ty.

Order
A memory_order.

Return Value

The stored value of *this before the exchange.

Remarks

This operation performs a read-modify-write operation to use Value to replace the value that is stored in *this, within the memory constraints that are specified by Order.

atomic::fetch_add

Fetches the value stored in *this, and then adds a specified value to the stored value.

Ty atomic<Ty>::fetch_add (
   Ty Value,
   memory_order Order = memory_order_seq_cst
) volatile noexcept;
Ty atomic<Ty>::fetch_add (
   Ty Value,
   memory_order Order = memory_order_seq_cst
) noexcept;

Parameters

Value
A value of type Ty.

Order
A memory_order.

Return Value

A Ty object that contains the value stored in *this prior to the addition.

Remarks

The fetch_add method performs a read-modify-write operation to atomically add Value to the stored value in *this, and applies the memory constraints that are specified by Order.

atomic::fetch_and

Performs a bitwise "and" (&) on a value and an existing value that is stored in *this.

Ty atomic<Ty>::fetch_and (
   Ty Value,
   memory_order Order = memory_order_seq_cst
) volatile noexcept;
Ty atomic<Ty>::fetch_and (
   Ty Value,
   memory_order Order = memory_order_seq_cst
) noexcept;

Parameters

Value
A value of type Ty.

Order
A memory_order.

Return Value

A Ty object that contains the result of the bitwise "and" (&).

Remarks

The fetch_and method performs a read-modify-write operation to replace the stored value of *this with a bitwise "and" (&) of Value and the current value that is stored in *this, within the memory constraints that are specified by Order.

atomic::fetch_or

Performs a bitwise "or" (|) on a value and an existing value that is stored in *this.

Ty atomic<Ty>::fetch_or (
   Ty Value,
   memory_order Order = memory_order_seq_cst
) volatile noexcept;
Ty atomic<Ty>::fetch_or (
   Ty Value,
   memory_order Order = memory_order_seq_cst
) noexcept;

Parameters

Value
A value of type Ty.

Order
A memory_order.

Return Value

A Ty object that contains the result of the bitwise "or" (|).

Remarks

The fetch_or method performs a read-modify-write operation to replace the stored value of *this with a bitwise "or" (|) of Value and the current value that is stored in *this, within the memory constraints that are specified by Order.

atomic::fetch_sub

Subtracts a specified value from the stored value.

Ty atomic<Ty>::fetch_sub (
   Ty Value,
   memory_order Order = memory_order_seq_cst
) volatile noexcept;
Ty atomic<Ty>::fetch_sub (
   Ty Value,
   memory_order Order = memory_order_seq_cst
) noexcept;

Parameters

Value
A value of type Ty.

Order
A memory_order.

Return Value

A Ty object that contains the result of the subtraction.

Remarks

The fetch_sub method performs a read-modify-write operation to atomically subtract Value from the stored value in *this, within the memory constraints that are specified by Order.

atomic::fetch_xor

Performs a bitwise "exclusive or" (^) on a value and an existing value that is stored in *this.

Ty atomic<Ty>::fetch_xor (
   Ty Value,
   memory_order Order = memory_order_seq_cst
) volatile noexcept;
Ty atomic<Ty>::fetch_xor (
   Ty Value,
   memory_order Order = memory_order_seq_cst
) noexcept;

Parameters

Value
A value of type Ty.

Order
A memory_order.

Return Value

A Ty object that contains the result of the bitwise "exclusive or" (^).

Remarks

The fetch_xor method performs a read-modify-write operation to replace the stored value of *this with a bitwise "exclusive or" (^) of Value and the current value that is stored in *this, and applies the memory constraints that are specified by Order.

atomic::is_lock_free

Specifies whether atomic operations on *this are lock free.

bool is_lock_free() const volatile noexcept;

Return Value

true if atomic operations on *this are lock free; otherwise, false.

Remarks

An atomic type is lock free if no atomic operations on that type use locks.

atomic::load

Retrieves the stored value in *this, within the specified memory constraints.

Ty atomic::load(
   memory_order Order = memory_order_seq_cst
) const volatile noexcept;
Ty atomic::load(
   memory_order Order = memory_order_seq_cst
) const noexcept;

Parameters

Order
A memory_order. Order must not be memory_order_release or memory_order_acq_rel.

Return Value

The retrieved value that is stored in *this.

atomic::store

Stores a specified value.

void atomic<Ty>::store(
   Ty Value,
   memory_order Order = memory_order_seq_cst
) volatile noexcept;
void atomic<Ty>::store(
   Ty Value,
   memory_order Order = memory_order_seq_cst
) noexcept;

Parameters

Value
A Ty object.

Order
A memory_order constraint.

Remarks

This member function atomically stores Value in *this, within the memory constraints that are specified by Order.

See also

<atomic>
Header Files Reference