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 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:: 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) and a trivial destructor. Signed integer arithmetic is defined to use two's complement; there are no undefined results.

Member types

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 . The mechanisms used to ensure atomicity and memory ordering should be compatible.

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 (int n = 0; n < 10000; ++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