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.

       atomic_store and atomic_store_explicit have no return value.

SEE ALSO

       <stdatomic.h> (C11), <rtapi_bitops.h> (for other atomic  memory  operations  supported  by
       rtapi)