Atomic operations.
More...
|
void | embb_atomic_init_TYPE (emb_atomic_TYPE *variable, TYPE initial_value) |
| Initializes an atomic variable. More...
|
|
void | embb_atomic_destroy_TYPE (emb_atomic_TYPE *variable) |
| Destroys an atomic variable and frees its resources. More...
|
|
void | embb_atomic_and_assign_TYPE (embb_atomic_TYPE *variable, TYPE value) |
| Computes the logical "and" of the value stored in variable and value . More...
|
|
int | embb_atomic_compare_and_swap_TYPE (embb_atomic_TYPE *variable, TYPE *expected, TYPE desired) |
| Compares variable with expected and, if equivalent, swaps its value with desired . More...
|
|
TYPE | embb_atomic_fetch_and_add_TYPE (embb_atomic_TYPE *variable, TYPE value) |
| Adds value to variable and returns its old value. More...
|
|
TYPE | embb_atomic_load_TYPE (const embb_atomic_TYPE *variable) |
| Loads the value of variable and returns it. More...
|
|
void | embb_atomic_memory_barrier () |
| Enforces a memory barrier (full fence). More...
|
|
void | embb_atomic_or_assign_TYPE (embb_atomic_TYPE *variable, TYPE value) |
| Computes the logical "or" of the value stored in variable and value . More...
|
|
void | embb_atomic_store_TYPE (embb_atomic_TYPE *variable, int value) |
| Stores value in variable . More...
|
|
TYPE | embb_atomic_swap_TYPE (embb_atomic_TYPE *variable, TYPE value) |
| Swaps the current value of variable with value . More...
|
|
void | embb_atomic_xor_assign_TYPE (embb_atomic_TYPE *variable, TYPE value) |
| Computes the logical "xor" of the value stored in variable and value . More...
|
|
Atomic operations.
Atomic operations are not directly applied to fundamental types. Instead, there is for each character and integer type an associated atomic type that has the same bit width (if the target CPU supports atomic operations on that type):
Fundamental type | Atomic type |
char | embb_atomic_char |
short | embb_atomic_short |
unsigned short | embb_atomic_unsigned_short |
int | embb_atomic_int |
unsigned int | embb_atomic_unsigned_int |
long | embb_atomic_long |
unsigned long | embb_atomic_unsigned_long |
long long | embb_atomic_long_long |
unsigned long long | embb_atomic_unsigned_long_long |
intptr_t | embb_atomic_intptr_t |
uintptr_t | embb_atomic_uintptr_t |
size_t | embb_atomic_size_t |
ptrdiff_t | embb_atomic_ptrdiff_t |
uintmax_t | embb_atomic_uintmax_t |
Each of the atomic operations described in the following can be applied to the types listed above. However, to avoid unnecessary redundancy, we document them only once in a generic way. The keyword TYPE serves as a placeholder which has to be replaced by the concrete type (e.g., int). If the fundamental type contains spaces (e.g., unsigned int), "_" is used for concatenation (e.g. unsigned_int).
Usage example:
Store the value 5
in an atomic "unsigned int"
variable.
Step 1 (declare atomic variable):
embb_atomic_unsigned_int my_var;
Step 2 (store the value):
embb_atomic_store_unsigned_int( &my_var, 5 );
The current implementation guarantees sequential consistency (full fences) for all atomic operations. Relaxed memory models may be added in the future.
void embb_atomic_init_TYPE |
( |
emb_atomic_TYPE * |
variable, |
|
|
TYPE |
initial_value |
|
) |
| |
Initializes an atomic variable.
- Precondition
- The atomic variable has not been initialized.
- Postcondition
- The atomic variable has the value
initial_value
and can be used in atomic operations.
- Concurrency
- Not thread-safe
- Parameters
-
[in,out] | variable | Pointer to atomic variable to be initialized. |
[in] | initial_value | Initial value to be assigned to atomic variable. |
void embb_atomic_destroy_TYPE |
( |
emb_atomic_TYPE * |
variable | ) |
|
Destroys an atomic variable and frees its resources.
- Precondition
- The atomic variable has been initialized.
- Postcondition
- The atomic variable is uninitialized.
- Concurrency
- Not thread-safe
- Parameters
-
[in,out] | variable | Pointer to atomic variable to be destroyed. |
void embb_atomic_and_assign_TYPE |
( |
embb_atomic_TYPE * |
variable, |
|
|
TYPE |
value |
|
) |
| |
Computes the logical "and" of the value stored in variable
and value
.
- Precondition
- The atomic variable has been initialized with
embb_atomic_init_TYPE
- Postcondition
- The result is stored in
variable
.
- See also
- Detailed description for general information and the meaning of TYPE.
- Concurrency
- Thread-safe and wait-free
- Parameters
-
[in,out] | variable | Pointer to atomic variable which serves as left-hand side for the "and" operation and is used to store the result. |
[in] | value | Right-hand side of "and" operation, passed by value |
int embb_atomic_compare_and_swap_TYPE |
( |
embb_atomic_TYPE * |
variable, |
|
|
TYPE * |
expected, |
|
|
TYPE |
desired |
|
) |
| |
Compares variable
with expected
and, if equivalent, swaps its value with desired
.
Stores desired
in variable
if the value of variable
is equivalent to the value of expected
. Otherwise, stores the value of variable
in expected
.
- Precondition
- The atomic variable has been initialized with
embb_atomic_init_TYPE
- Returns
- != 0 if the values of
variable
and expected
were equivalent
0 otherwise
- See also
- Detailed description for general information and the meaning of TYPE.
- Concurrency
- Thread-safe and wait-free
- Parameters
-
[in,out] | variable | Pointer to atomic variable |
[in,out] | expected | Pointer to expected value |
[in] | desired | Value to be stored in variable |
TYPE embb_atomic_fetch_and_add_TYPE |
( |
embb_atomic_TYPE * |
variable, |
|
|
TYPE |
value |
|
) |
| |
Adds value
to variable
and returns its old value.
- Precondition
- The atomic variable has been initialized with
embb_atomic_init_TYPE
- Returns
- The value before the operation
- See also
- Detailed description for general information and the meaning of TYPE.
- Concurrency
- Thread-safe and wait-free
- Parameters
-
[in,out] | variable | Pointer to atomic variable |
[in] | value | The value to be added to variable (can be negative) |
TYPE embb_atomic_load_TYPE |
( |
const embb_atomic_TYPE * |
variable | ) |
|
Loads the value of variable
and returns it.
- Precondition
- The atomic variable has been initialized with
embb_atomic_init_TYPE
- Returns
- The value of the atomic variable.
- See also
- Detailed description for general information and the meaning of TYPE.
- Concurrency
- Thread-safe and wait-free
- Parameters
-
[in] | variable | Pointer to atomic variable |
void embb_atomic_memory_barrier |
( |
| ) |
|
Enforces a memory barrier (full fence).
- Concurrency
- Thread-safe and wait-free
void embb_atomic_or_assign_TYPE |
( |
embb_atomic_TYPE * |
variable, |
|
|
TYPE |
value |
|
) |
| |
Computes the logical "or" of the value stored in variable
and value
.
- Precondition
- The atomic variable has been initialized with
embb_atomic_init_TYPE
- Postcondition
- The result is stored in
variable
.
- See also
- Detailed description for general information and the meaning of TYPE.
- Concurrency
- Thread-safe and wait-free
- Parameters
-
[in,out] | variable | Pointer to atomic variable which serves as left-hand side for the "or" operation and is used to store the result. |
[in] | value | Right-hand side of "or" operation, passed by value |
void embb_atomic_store_TYPE |
( |
embb_atomic_TYPE * |
variable, |
|
|
int |
value |
|
) |
| |
Stores value
in variable
.
- Precondition
- The atomic variable has been initialized with
embb_atomic_init_TYPE
- See also
- Detailed description for general information and the meaning of TYPE.
- Concurrency
- Thread-safe and wait-free
- Parameters
-
[in,out] | variable | Pointer to atomic variable |
[in] | value | Value to be stored |
TYPE embb_atomic_swap_TYPE |
( |
embb_atomic_TYPE * |
variable, |
|
|
TYPE |
value |
|
) |
| |
Swaps the current value of variable
with value
.
- Precondition
- The atomic variable has been initialized with
embb_atomic_init_TYPE
- Returns
- The old value of
variable
- See also
- Detailed description for general information and the meaning of TYPE.
- Concurrency
- Thread-safe and wait-free
- Parameters
-
[in,out] | variable | Pointer to atomic variable whose value is swapped |
[in] | value | Value which will be stored in the atomic variable |
void embb_atomic_xor_assign_TYPE |
( |
embb_atomic_TYPE * |
variable, |
|
|
TYPE |
value |
|
) |
| |
Computes the logical "xor" of the value stored in variable
and value
.
- Precondition
- The atomic variable has been initialized with
embb_atomic_init_TYPE
- Postcondition
- The result is stored in
variable
.
- See also
- Detailed description for general information and the meaning of TYPE.
- Concurrency
- Thread-safe and wait-free
- Parameters
-
[in,out] | variable | Pointer to atomic variable which serves as left-hand side for the "xor" operation and is used to store the result. |
[in] | value | Right-hand side of "xor" operation, passed by value |