Embedded Multicore Building Blocks V1.0.0
Functions

Atomic operations. More...

Functions

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...
 

Detailed Description

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.

Function Documentation

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]variablePointer to atomic variable to be initialized.
[in]initial_valueInitial 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]variablePointer 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]variablePointer to atomic variable which serves as left-hand side for the "and" operation and is used to store the result.
[in]valueRight-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]variablePointer to atomic variable
[in,out]expectedPointer to expected value
[in]desiredValue 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]variablePointer to atomic variable
[in]valueThe 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]variablePointer 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]variablePointer to atomic variable which serves as left-hand side for the "or" operation and is used to store the result.
[in]valueRight-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]variablePointer to atomic variable
[in]valueValue 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]variablePointer to atomic variable whose value is swapped
[in]valueValue 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]variablePointer to atomic variable which serves as left-hand side for the "xor" operation and is used to store the result.
[in]valueRight-hand side of "xor" operation, passed by value