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)

LinuxCNC Documentation                             2006-10-12                                      funct(3rtapi)