74 lines
2.3 KiB
Text
74 lines
2.3 KiB
Text
.TH funct "3rtapi" "2006-10-12" "LinuxCNC Documentation" "RTAPI"
|
|
.SH NAME
|
|
|
|
rtapi_atomic \- subset of C11 <stdatomic.h>
|
|
|
|
.SH SYNTAX
|
|
.HP
|
|
#include <rtapi_atomic.h>
|
|
.HP
|
|
enum memory_order { ... };
|
|
.HP
|
|
#define atomic_store(obj, desired)...
|
|
.HP
|
|
#define atomic_store_explicit(obj, desired, order)...
|
|
.HP
|
|
#define atomic_load(obj)...
|
|
.HP
|
|
#define atomic_load_explicit(obj, order)...
|
|
|
|
.SH ARGUMENTS
|
|
.IP "\fBvolatile A*\fR \fIobj\fR"
|
|
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.
|
|
.IP "\fBC\fR \fIdesired\fR"
|
|
The value to be stored in the object. "*obj = desired" must be well-formed.
|
|
.IP "\fBmemory_order\fR order"
|
|
The required memory ordering semantic.
|
|
|
|
.SH 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:
|
|
|
|
.RS
|
|
.EX
|
|
// 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
|
|
.EE
|
|
.RE
|
|
|
|
.SH REALTIME CONSIDERATIONS
|
|
May be called from any code.
|
|
.SH RETURN VALUE
|
|
.B atomic_load
|
|
and
|
|
.B atomic_load_explicit
|
|
return the value pointed to by the
|
|
.I obj
|
|
argument.
|
|
|
|
.B atomic_store
|
|
and
|
|
.B atomic_store_explicit
|
|
have no return value.
|
|
|
|
.SH SEE ALSO
|
|
.BR <stdatomic.h> " (C11), " <rtapi_bitops.h> " (for other atomic memory operations supported by rtapi)"
|
|
|