NAME

rtapi_atomic - subset of C11 <stdatomic.h>

SYNTAX

#include <rtapi_atomic.h>

enum memory_order { ... };

#define atomic_store(obj, desired)...

#define atomic_store_explicit(obj, desired, order)...

#define atomic_load(obj)...

#define atomic_load_explicit(obj, order)...

ARGUMENTS

volatile A* obj: A pointer to a volatile object that is the destination of the store or the source of the load. The pointer must have an appropriate type and alignment such that the underlying store or load operation itself is atomic; at a minimum, a properly aligned "int" may be assumed to be such a type. Improper size or alignment are undiagnosed errors.
C desired: The value to be stored in the object. "*obj = desired" must be well-formed.
memory_order order: The required memory ordering semantic.

DESCRIPTION

This header provides at least the subset of C11's <stdatomic.h> given above. When there is an ordering requirement for multiple values read or written in RTAPI shared memory areas by other threads of execution, including the values of HAL pins and parameters, these functions (or function-like macros) are the only way to ensure the ordering requirement is obeyed. Otherwise, according to architecture-specific rules, loads and stores may be reordered from their normal source code order.

For example, to leave a message in a shared memory area from one thread and retrieve it from another, the writer must use an atomic store for the "message is complete" variable, and the reader must use an atomic load when checking that variable:

// producer
*message = 42;
atomic_store_explicit(message_ready, 1, memory_order_release);
// consumer
while(atomic_load_explicit(message_ready, memory_order_acquire) == 0) sched_yield();
printf("message was %d\n", *message); // must print 42

REALTIME CONSIDERATIONS

May be called from any code.

RETURN VALUE

atomic_load and atomic_load_explicit return the value pointed to by the obj argument.