std::atomic - cppreference.com (original) (raw)

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.

Contents

• 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
  • 6.2 Aliases for special-purpose types
• 7 Notes
• 8 Example
• 9 Defect reports
• 10 See also

[edit] Specializations

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

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

1. Partial specializations std::atomic<U*> for all pointer types. These specializations have standard layout, trivial default constructors,(until C++20) 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.

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

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.

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

[edit] Member functions

[edit] Specialized member functions

[edit] Type aliases

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

Note: std::atomic_int_N__t, std::atomic_uint_N__t, std::atomic_intptr_t, and std::atomic_uintptr_t are defined if and only if std::int_N__t, std::uint_N__t, std::intptr_t, and std::uintptr_t are defined, respectively.

[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 #include #include #include   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'; }

Possible output:

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