# std::atomic (3) - Linux Man Pages

## std::atomic: std::atomic

## NAME

## Synopsis

Defined in header <atomic>

template< class T > **(1)** *(since C++11)*

struct atomic;

template< class T > **(2)** *(since C++11)*

struct atomic<T*>;

Defined in header <memory>

template<class T> **(3)** *(since C++20)*

struct atomic<std::shared_ptr<T>>;

template<class T> **(4)** *(since C++20)*

struct atomic<std::weak_ptr<T>>;

Each instantiation and full specialization of the std::atomic template defines an atomic type. If one thread writes to an atomic object while another thread reads from it, the behavior is well-defined (see memory_model for details on data races)

In addition, accesses to atomic objects may establish inter-thread synchronization and order non-atomic memory accesses as specified by std::memory_order.

std::atomic is neither copyable nor movable.

## Specializations

Primary template

The primary std::atomic template may be instantiated with any TriviallyCopyable type T satisfying both CopyConstructible and CopyAssignable. The program is ill-formed if any of following values is false:

* std::is_trivially_copyable<T>::value

* std::is_copy_constructible<T>::value

* std::is_move_constructible<T>::value

* std::is_copy_assignable<T>::value

* std::is_move_assignable<T>::value

std::atomic<bool> uses the primary template. It is guaranteed to be a standard layout struct.

Partial specializations

The standard library provides partial specializations of the std::atomic template for the following types with additional properties that the primary template does not have:

2) Partial specializations std::atomic<T*> for all pointer types. These specializations have standard layout, trivial default constructors, and trivial destructors. Besides the operations provided for all atomic types, these specializations additionally support atomic arithmetic operations appropriate to pointer types, such as fetch_add, fetch_sub.

3-4) Partial specializations std::atomic<std::shared_ptr<T>> and std::atomic<std::weak_ptr<T>> are provided for std::shared_ptr and std::weak_ptr. *(since C++20)*

See std::atomic<std::shared_ptr> and std::atomic<std::weak_ptr> for details.

Specializations for integral types

When instantiated with one of the following integral types, std::atomic provides additional atomic operations appropriate to integral types such as fetch_add, fetch_sub, fetch_and, fetch_or, fetch_xor:

*(since C++20)*, char16_t, char32_t, and wchar_t;

Additionally, the resulting std::atomic<Integral> specialization has standard layout, a trivial default constructor, and a trivial destructor. Signed integer arithmetic is defined to use two's complement; there are no undefined results.

Specializations for floating-point types

*(since C++20)*

When instantiated with one of the floating-point types float, double, and long double, std::atomic provides additional atomic operations appropriate to floating-point types such as fetch_add and fetch_sub.

Additionally, the resulting std::atomic<Floating> specialization has standard layout, a trivial default constructor, and a trivial destructor.

No operations result in undefined behavior even if the result is not representable in the floating-point type. The floating-point_environment in effect may be different from the calling thread's floating-point environment.

Type aliases

Type aliases are provided for bool and all integral types listed above, as follows:

Type alias Definition

std::atomic_bool std::atomic<bool>

std::atomic_char std::atomic<char>

std::atomic_schar std::atomic<signed char>

std::atomic_uchar std::atomic<unsigned char>

std::atomic_short std::atomic<short>

std::atomic_ushort std::atomic<unsigned short>

std::atomic_int std::atomic<int>

std::atomic_uint std::atomic<unsigned int>

std::atomic_long std::atomic<long>

std::atomic_ulong std::atomic<unsigned long>

std::atomic_llong std::atomic<long long>

std::atomic_ullong std::atomic<unsigned long long>

std::atomic_char8_t std::atomic<char8_t> (C++20)

std::atomic_char16_t std::atomic<char16_t>

std::atomic_char32_t std::atomic<char32_t>

std::atomic_wchar_t std::atomic<wchar_t>

std::atomic_int8_t std::atomic<std::int8_t>

std::atomic_uint8_t std::atomic<std::uint8_t>

std::atomic_int16_t std::atomic<std::int16_t>

std::atomic_uint16_t std::atomic<std::uint16_t>

std::atomic_int32_t std::atomic<std::int32_t>

std::atomic_uint32_t std::atomic<std::uint32_t>

std::atomic_int64_t std::atomic<std::int64_t>

std::atomic_uint64_t std::atomic<std::uint64_t>

std::atomic_int_least8_t std::atomic<std::int_least8_t>

std::atomic_uint_least8_t std::atomic<std::uint_least8_t>

std::atomic_int_least16_t std::atomic<std::int_least16_t>

std::atomic_uint_least16_t std::atomic<std::uint_least16_t>

std::atomic_int_least32_t std::atomic<std::int_least32_t>

std::atomic_uint_least32_t std::atomic<std::uint_least32_t>

std::atomic_int_least64_t std::atomic<std::int_least64_t>

std::atomic_uint_least64_t std::atomic<std::uint_least64_t>

std::atomic_int_fast8_t std::atomic<std::int_fast8_t>

std::atomic_uint_fast8_t std::atomic<std::uint_fast8_t>

std::atomic_int_fast16_t std::atomic<std::int_fast16_t>

std::atomic_uint_fast16_t std::atomic<std::uint_fast16_t>

std::atomic_int_fast32_t std::atomic<std::int_fast32_t>

std::atomic_uint_fast32_t std::atomic<std::uint_fast32_t>

std::atomic_int_fast64_t std::atomic<std::int_fast64_t>

std::atomic_uint_fast64_t std::atomic<std::uint_fast64_t>

std::atomic_intptr_t std::atomic<std::intptr_t>

std::atomic_uintptr_t std::atomic<std::uintptr_t>

std::atomic_size_t std::atomic<std::size_t>

std::atomic_ptrdiff_t std::atomic<std::ptrdiff_t>

std::atomic_intmax_t std::atomic<std::intmax_t>

std::atomic_uintmax_t std::atomic<std::uintmax_t>

Note: std::atomic_intN_t, std::atomic_uintN_t, std::atomic_intptr_t, and atomic_uintptr_t are defined if and only if std::intN_t, std::uintN_t, std::intptr_t, and std::uintptr_t are defined, respectively.

## Member types

Member type Definition

value_type see below

difference_type and atomic<Floating>

*(since C++20)* specializations)

For every std::atomic<X> (whether or not specialized), std::atomic<X>::value_type is X.

difference_type is not defined in the primary atomic template or in the partial specializations for std::shared_ptr and std::weak_ptr.

## Member functions

constructor *(public member function)*

operator= *(public member function)*

is_lock_free *(public member function)*

store *(public member function)*

load *(public member function)*

operator_T *(public member function)*

exchange *(public member function)*

compare_exchange_weak *(public member function)*

compare_exchange_strong

## Constants

is_always_lock_free indicates that the type is always lock-free

*(public static member constant)*
**[static]** *(C++17)*

## Specialized member functions

fetch_add *(public member function)*

fetch_sub *(public member function)*

fetch_and *(public member function)*

fetch_or *(public member function)*

fetch_xor *(public member function)*

operator++ increments or decrements the atomic value by one

operator++(int) *(public member function)*

operator--

operator--(int)

operator+=

operator-= adds, subtracts, or performs bitwise AND, OR, XOR with the atomic value

operator&= *(public member function)*

operator|=

operator^=

## Notes

There are non-member function template equivalents for all member functions of std::atomic. Those non-member functions may be additionally overloaded for types that are not specializations of std::atomic, but are able to guarantee atomicity. The only such type in the standard library is std::shared_ptr<T>.

On gcc and clang, some of the functionality described here requires linking against -latomic.

Defect reports

The following behavior-changing defect reports were applied retroactively to previously published C++ standards.

DR Applied to Behavior as published Correct behavior

LWG_2441 C++11 added specializations for the (optional) fixed_width_integer_types

P0558R1 C++11 specification was substantially rewritten to resolve numerous issues

LWG_3012 C++11 std::atomic<T> was permitted for such specializations are forbidden

## See also

atomic_flag the lock-free boolean atomic type

*(class)*
*(C++11)*