atomic types

 

C

Language

headers

Type support

Dynamic memory management

Error handling

Program utilities

Variadic function support

Date and time utilities

Strings library

Algorithms

Numerics

Input/output support

Localization support

Thread support (C11)

Atomic operations (C11)

Technical Specifications

 

C language

ASCII chart

Basic concepts

translation phases

comment

identifier

scope

lifetime

name space

type

arithmetic types

object

main function

memory model

Keywords

Preprocessor

Statements

Expressions

Initialization

Declarations

Functions

Miscellaneous

history of C

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

 

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)