std::atomic

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

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::is_same <T, typename std::remove_cv <T> :: type > :: value

struct Counters { int a; int b; }; // user-defined trivially-copyable type
std::atomic<Counters> cnt;         // specialization for the user-defined type

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

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:

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

• The character types char , char8_t(since C++20), char16_t, char32_t, and wchar_t
• The standard signed integer types: signed char, short, int, long, and long long
• The standard unsigned integer types: unsigned char, unsigned short, unsigned int, unsigned long, and unsigned long long
• Any additional integral types needed by the typedefs in the header <cstdint>.

Additionally, the resulting std::atomic<Integral> specialization has standard layout , a trivial default constructor, (until C++20)

Member types

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

Member functions

Specialized member functions

Type aliases

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

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<U>

_Atomic is a keyword and used to provide atomic types in C.

Implementations are recommended to ensure that the representation of _Atomic(T) in C is same as that of std::atomic<T> in C++ for every possible type T

On GCC and Clang, some of the functionality described here requires linking against -latomic.

Example

#include <atomic>
#include <iostream>
#include <thread>
#include <vector>
 
std::atomic_int acnt;
int cnt;
 
void f()
{
    for (auto n{10000}; n; --n)
    {
        ++acnt;
        ++cnt;
        // Note: for this example, relaxed memory order is sufficient,
        // e.g. acnt.fetch_add(1, std::memory_order_relaxed);
    }
}
 
int main()
{
    {
        std::vector<std::jthread> pool;
        for (int n = 0; n < 10; ++n)
            pool.emplace_back(f);
    }
 
    std::cout << "The atomic counter is " << acnt << '\n'
              << "The non-atomic counter is " << cnt << '\n';
}

The atomic counter is 100000
The non-atomic counter is 69696

Defect reports

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

See also