# atomic types

< c‎ | language

C
 Language Headers Type support Program utilities Variadic function support Error handling Dynamic memory management Date and time utilities Strings library Algorithms Numerics Input/output support Localization support Atomic operations (C11) Thread support (C11) Technical Specifications

Declarations
 pointer array enum storage duration and linkage const volatile restrict(C99) struct union bit field alignas(C11) typedef static_assert(C11) atomic types(C11) external and tentative definitions

## Contents

### Syntax

 _Atomic ( type-name ) (1) (since C11) _Atomic type-name (2) (since C11)
1) Use as a type specifier; this designates a new atomic type
2) Use as a type qualifier; this designates the atomic version of type-name. In this role, it may be mixed with const, volatile, and restrict), although unlike other qualifiers, the atomic version of type-name may have a different size, alignment, and object representation.
 type-name - any type other than array or function. For (1), type-name also cannot be atomic or cvr-qualified

The header <stdatomic.h> defines 37 convenience macros, from atomic_bool to atomic_uintmax_t, which simplify the use of this keyword with built-in and library types.

_Atomic const int * p1;  // p is a pointer to an atomic const int
const atomic_int * p2;   // same
const _Atomic(int) * p3; // same

### Explanation

Objects of atomic types are the only objects that are free from data races, that is, they may be modified by two threads concurrently or modified by one and read by another.

Each atomic object has its own associated modification order, which is a total order of modifications made to that object. If, from some thread's point of view, modification A of some atomic M happens-before modification B of the same atomic M, then in the modification order of M, A occurs before B.

Note that although each atomic object has its own modification order, it is not a total order; different threads may observe modifications to different atomic objects in different orders.

There are four coherences that are guaranteed for all atomic operations:

• write-write coherence: If an operation A that modifies an atomic object M happens-before an operation B that modifies M, then A appears earlier than B in the modification order of M.
• read-read coherence: If a value computation A of an atomic object M happens before a value computation B of M, and A takes its value from a side effect X on M, then the value computed by B is either the value stored by X or is the value stored by a side effect Y on M, where Y appears later than X in the modification order of M.
• read-write coherence: If a value computation A of an atomic object M happens-before an operation B on M, then A takes its value from a side effect X on M, where X appears before B in the modification order of M.
• write-read coherence: If a side effect X on an atomic object M happens-before a value computation B of M, then the evaluation B takes its value from X or from a side effect Y that appears after X in the modification order of M.

Some atomic operations are also synchronization operations; they may have additional release semantics, acquire semantics, or sequentially-consistent semantics. See memory_order.

Built-in increment and decrement operators and compound assignment are read-modify-write atomic operations with total sequentially consistent ordering (as if using memory_order_seq_cst). If less strict synchronization semantics are desired, the standard library functions may be used instead.

Atomic properties are only meaningful for lvalue expressions. Lvalue-to-rvalue conversion (which models a memory read from an atomic location to a CPU register) strips atomicity along with other qualifiers.

### Notes

If the macro constant __STDC_NO_ATOMICS__(C11) is defined by the compiler, the keyword _Atomic as well as the header <stdatomic.h>, is not provided.

Accessing a member of an atomic struct/union is undefined behavior.

The library type sig_atomic_t does not provide inter-thread synchronization or memory ordering, only atomicity.

The volatile types do not provide inter-thread synchronization, memory ordering, or atomicity.

### Example

#include <stdio.h>
#include <threads.h>
#include <stdatomic.h>

atomic_int acnt;
int cnt;

int f(void* thr_data)
{
for(int n = 0; n < 1000; ++n) {
++cnt;
++acnt;
// for this example, relaxed memory order is sufficient, e.g.
// atomic_fetch_add_explicit(&acnt, 1, memory_order_relaxed);
}
return 0;
}

int main(void)
{
thrd_t thr[10];
for(int n = 0; n < 10; ++n)
thrd_create(&thr[n], f, NULL);
for(int n = 0; n < 10; ++n)
thrd_join(thr[n], NULL);

printf("The atomic counter is %u\n", acnt);
printf("The non-atomic counter is %u\n", cnt);
}

Possible output:

The atomic counter is 10000
The non-atomic counter is 8644

### References

• C11 standard (ISO/IEC 9899:2011):
• 6.7.2.4 Atomic type specifiers (p: 121)
• 7.17 Atomics <stdatomic.h> (p: 273-286)