std::atomic

The compatibility macro _Atomic is provided in <stdatomic.h> such that _Atomic(T) is identical to std::atomic<T> while both are well-formed.

It is unspecified whether any declaration in namespace std is available when <stdatomic.h> is included.

• 1 Specializations
  • 1.1 Primary template
  • 1.2 Partial specializations
  • 1.3 Specializations for integral types
  • 1.4 Specializations for floating-point types
• 2 Member types
• 3 Member functions
• 4 Constants
• 5 Specialized member functions
  • 5.1 Specialized for integral, floating-point(since C++20) and pointer types
  • 5.2 Specialized for integral and pointer types only
  • 5.3 Specialized for integral types only
• 6 Type aliases
  • 6.1 Aliases for all std::atomic<Integral>
  • 6.2 Aliases for special-purpose types
• 7 Notes
• 8 Example
• 9 Defect reports
• 10 See also

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

Specializations for floating-point types

When instantiated with one of the cv-unqualified floating-point types (float, double, long double and cv-unqualified extended floating-point types (since C++23)), 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 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.

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 .

[edit] Member functions

[edit] Specialized member functions

[edit] Type aliases

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

[edit] 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.

[edit] 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

[edit] Defect reports

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

[edit] See also