stdatomic.h, stdatomic - atomics header
#include <stdatomic.h>
The <stdatomic.h> header defines the following macros:
The above 10 macros indicate the lock-free property of the corresponding atomic types. For the non-pointer types, the results apply to both signed and unsigned types.
The ATOMIC_FLAG_INIT macro expands to an intializer for an object of type atomic_flag. It may be used to initialize an atomic_flag to the clear state. An atomic_flag that is not explicitly initialized with ATOMIC_FLAG_INIT is initially in an indeterminate state.
Example:
atomic_flag guard = ATOMIC_FLAG_INIT;
The ATOMIC_VAR_INIT macro expands to a token sequence suitable for initializing an atomic object of a type that is initialization-compatible with value.
Example:
atomic_int guide = ATOMIC_VAR_INIT(42);
Returns the value of y and terminates a dependency chain on variable y. Refer to C Standard for the meaning of terminating a dependency chain.
The following data types are defined through typedef:
A structure type representing a lock-free, primitive atomic flag. An object of type atomic_flag can have two states: set and clear. It provides the classic test-and-set functionality.
An enumarated type whose enumerators identify memory ordering constraints. It specifies the detailed regular (non-atomic) memory synchronization operations as defined in C standard 5.1.2.4 and may provide for operation ordering. Its enumeration constants are as follows:
memory_order_relaxed memory_order_consume memory_order_acquire memory_order_release memory_order_acq_rel memory_order_seq_cst
For memory_order_relaxed, no operation orders memory.
For memory_order_release, memory_order_acq_rel, and memory_order_seq_cst, a store operation performs a release operation on the affected memory location.
For memory_order_acquire, memory_order_acq_rel, and memory_order_seq_cst, a load operation performs an acquire operation on the affected memory location.
For memory_order_consume, a load operation performs a consume operation on the affected memory location.
There will be a single total order S on all memory_order_seq_cst operations, consistent with the “happens before” order and modification orders for all affected locations, such that each memory_order_seq_cst operation B that loads a value from an atomic object M observes one of the following values:
the result of the last modification A of M that precedes B in S, if it exists, or
if A exists, the result of some modification of M in the visible sequence of side effects with respect to B that is not memory_order_seq_cst and that does not happen before A, or
if A does not exist, the result of some modification of M in the visible sequence of side effects with respect to B that is not memory_order_seq_cst.
For an atomic operation B that reads the value of an atomic object M, if there is a memory_order_seq_cst fence X sequenced before B, then B observes either the last memory_order_seq_cst modification of M preceding X in the total order S or a later modification of M in its modification order.
For atomic operations A and B on an atomic object M, where A modifies M and B takes its value, if there is a memory_order_seq_cst fence X such that A is sequenced before X and B follows X in S, then B observes either the effects of A or a later modification of M in its modification order.
For atomic operations A and B on an atomic object M, where A modifies M and B takes its value, if there are memory_order_seq_cst fences X and Y such that A is sequenced before X, Y is sequenced before B, and X precedes Y in S, then B observes either the effects of A or a later modification of M in its modification order.
Atomic read-modify-write operations always read the last value (in the modification order) stored before the write associated with the read-modify-write operation.
An atomic store only stores a value that has been computed from constants and program input values by a finite sequence of program evaluations, such that each evaluation observes the values of variables as computed by the last prior assignment in the sequence. The ordering of evaluations in this sequence will be such that
If an evaluation B observes a value computed by A in a different thread, then B does not happen before A.
If an evaluation A is included in the sequence, then all evaluations that assign to the same variable and happen before A are also included.
The following data types are defined through typedef. They are equivalent to the corresponding _Atomic qualified types listed on their right.
|
The following is a list of generic functions defined in the header. Generic functions are type generic macros, which expand to compiler intrinsics.
In the following description:
An A refers to an atomic type,
A C refers to A's corresponding non-atomic type.
An M refers to the type of the other argument for arithmetic operations. For atomic integer types, M is C. For atomic pointer types, M is ptrdiff_t.
Initializes the atomic object pointed to by obj to value. If A is a locked atomic type, the lock associated with obj will also have been initialized after atomic_init() call.
Returns whether the object pointed to by obj is lock-free.
In the following description, the generic functions not ending in _explicit have the same semantics as the corresponding _explicit function with memory_order_seq_cst for the memory_order argument. If there is no further description, for each generic function, memory is affected according to the value of memory_order argument. Refer to memory_order and C standard 5.1.2.4 for details about memory order.
Atomically replace the value pointed to by object with the value of desired.
The order argument cannot be memory_order_acquire, memory_order_consume, nor memory_order_acq_rel.
Atomically return the value pointed to by object.
The order argument cannot be memory_order_release nor memory_order_acq_rel.
Atomically replace the value pointed to by object with the value of desired. The return value is the value pointed to by object immediately before the effect. These operations are read-modify-write operations.
Atomically, compare if the value pointed to by object equal to the value pointed to by expected, and if true, replace the value pointed to by object with desired, and if false, update the value in expected with the value pointed to by object. Further, if the comparison is true, memory is affected according to the value of success, and if the comparison is false, memory is affected according to the value of failure. The return value is the result of the comparison.
These operations are atomic read-modify-write operations.
A weak compare-and-exchange operation may fail spuriously. That is, even when the contents of memory referred to by expected and object are equal, it may return zero and store back to expected the same memory contents that were originally there.
The following operations perform arithmetic and bitwise computations. All of these operations are applicable to an object of any atomic integer type. None of these operations is applicable to atomic_bool.
Atomically replace the value pointed to by object with the result of the computation applied to the value pointed to by object and the given operand. Atomically, return the value pointed to by object immediately before the effects.
The operator of the computation is indicated by the key in the name of the generic function, the following table shows the key, operator, and computation correspondence
|
These operations are atomic read-modify-write operations.
For signed integer types, arithmetic is defined to use two's complement representation with silent wrap-around on overflow. There is no undefinied behavior on signed integer overflow for these atomic operations.
For address types, the result may be an undefined address, but the operations otherwise have no undefined behavior for these atomic operations.
See attributes(5) for descriptions of the following attributes:
|
atomic_flag_clear(3A), atomic_flag_clear_explicit(3A), atomic_flag_test_and_set(3A), atomic_flag_test_and_set_explicit(3A), atomic_signal_fence(3A), atomic_thread_fence(3A)