Each instantiation and full specialization of thestd::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 (seememory 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 bystd::memory_order.

std::atomic is neither copyable nor movable.

[edit]Specializations

[edit]Primary template

The primarystd::atomic template may be instantiated with anyTriviallyCopyable typeT satisfying bothCopyConstructible andCopyAssignable. The program is ill-formed if any of following values isfalse:

• 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,typenamestd::remove_cv<T>::type>::value

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

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

[edit]Partial specializations

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

[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 asfetch_add,fetch_sub,fetch_and,fetch_or,fetch_xor:

• The character typeschar,char8_t(since C++20),char16_t,char32_t, andwchar_t;
• The standard signed integer types:signedchar,short,int,long, andlonglong;
• The standard unsigned integer types:unsignedchar,unsignedshort,unsignedint,unsignedlong, andunsignedlonglong;
• Any additional integral types needed by the typedefs in the header<cstdint>.

Additionally, the resultingstd::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 primarystd::atomic template or in the partial specializations forstd::shared_ptr andstd::weak_ptr.

[edit]Member functions

[edit]Specialized member functions

[edit]Type aliases

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

[edit]Notes

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

_Atomic is akeyword and used to provideatomic types in C.

Implementations are recommended to ensure that the representation of_Atomic(T) in C is same as that ofstd::atomic<T> in C++ for every possible typeT. 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 100000The 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

• In other languages

• Deutsch
• Español
• Français
• Italiano
• 日本語
• Português
• Русский
• 中文