atomic types

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.

Keywords

_Atomic

Example

Run this code

#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)

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

Basic concepts
Keywords
Preprocessor
Statements
Expressions
Initialization
Declarations
Functions
Miscellaneous
History of C
Technical Specifications

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