1  .TH funct "3rtapi" "2006-10-12" "LinuxCNC Documentation" "RTAPI"
 2  .SH NAME
 3  
 4  rtapi_atomic \- subset of C11 <stdatomic.h>
 5  
 6  .SH SYNTAX
 7  .HP
 8  #include <rtapi_atomic.h>
 9  .HP
10  enum memory_order { ... };
11  .HP
12  #define atomic_store(obj, desired)...
13  .HP
14  #define atomic_store_explicit(obj, desired, order)...
15  .HP
16  #define atomic_load(obj)...
17  .HP
18  #define atomic_load_explicit(obj, order)...
19  
20  .SH  ARGUMENTS
21  .IP "\fBvolatile A*\fR \fIobj\fR"
22  A pointer to a volatile object that is the destination of the store or the
23  source of the load.  The pointer must have an appropriate type and alignment
24  such that the underlying store or load operation itself is atomic; at a
25  minimum, a properly aligned "int" may be assumed to be such a type.  Improper
26  size or alignment are undiagnosed errors.
27  .IP "\fBC\fR \fIdesired\fR"
28  The value to be stored in the object.  "*obj = desired" must be well-formed.
29  .IP "\fBmemory_order\fR order"
30  The required memory ordering semantic.
31  
32  .SH DESCRIPTION
33  This header provides at least the subset of C11's <stdatomic.h> given above.
34  When there is an ordering requirement for multiple values read or written in RTAPI
35  shared memory areas by other threads of execution, including the values of HAL
36  pins and parameters, these functions (or function-like macros) are the only way
37  to ensure the ordering requirement is obeyed.  Otherwise, according to
38  architecture-specific rules, loads and stores may be reordered from their
39  normal source code order.
40  
41  For example, to leave a message in a shared memory area from one thread and
42  retrieve it from another, the writer must use an atomic store for the "message
43  is complete" variable, and the reader must use an atomic load when checking that variable:
44  
45  .RS
46  .EX
47  // producer
48  *message = 42;
49  atomic_store_explicit(message_ready, 1, memory_order_release);
50  
51  // consumer
52  while(atomic_load_explicit(message_ready, memory_order_acquire) == 0) sched_yield();
53  printf("message was %d\\n", *message); // must print 42
54  .EE
55  .RE
56  
57  .SH REALTIME CONSIDERATIONS
58  May be called from any code.
59  .SH RETURN VALUE
60  .B atomic_load
61  and
62  .B atomic_load_explicit
63  return the value pointed to by the
64  .I obj
65  argument.
66  
67  .B atomic_store
68  and
69  .B atomic_store_explicit
70  have no return value.
71  
72  .SH SEE ALSO
73  .BR <stdatomic.h> " (C11), " <rtapi_bitops.h> " (for other atomic memory operations supported by rtapi)"
74