- * The following functions can be used to atomically access integers and
- * pointers. They are implemented as inline assembler function on most
- * platforms and use slower fall-backs otherwise. Using them can sometimes
- * save you from using a performance-expensive #GMutex to protect the
- * integer or pointer.
- *
- * The most important usage is reference counting. Using
- * g_atomic_int_inc() and g_atomic_int_dec_and_test() makes reference
- * counting a very fast operation.
- *
- * <note><para>You must not directly read integers or pointers concurrently
- * accessed by multiple threads, but use the atomic accessor functions
- * instead. That is, always use g_atomic_int_get() and g_atomic_pointer_get()
- * for read outs. They provide the neccessary synchonization mechanisms
- * like memory barriers to access memory locations concurrently.
- * </para></note>
- *
- * <note><para>If you are using those functions for anything apart from
- * simple reference counting, you should really be aware of the implications
- * of doing that. There are literally thousands of ways to shoot yourself
- * in the foot. So if in doubt, use a #GMutex. If you don't know, what
- * memory barriers are, do not use anything but g_atomic_int_inc() and
- * g_atomic_int_dec_and_test().
- * </para></note>
- *
- * <note><para>It is not safe to set an integer or pointer just by assigning
- * to it, when it is concurrently accessed by other threads with the following
- * functions. Use g_atomic_int_compare_and_exchange() or
- * g_atomic_pointer_compare_and_exchange() respectively.
- * </para></note>
+ * The following is a collection of compiler macros to provide atomic
+ * access to integer and pointer-sized values.
+ *
+ * The macros that have 'int' in the name will operate on pointers to
+ * #gint and #guint. The macros with 'pointer' in the name will operate
+ * on pointers to any pointer-sized value, including #gsize. There is
+ * no support for 64bit operations on platforms with 32bit pointers
+ * because it is not generally possible to perform these operations
+ * atomically.
+ *
+ * The get, set and exchange operations for integers and pointers
+ * nominally operate on #gint and #gpointer, respectively. Of the
+ * arithmetic operations, the 'add' operation operates on (and returns)
+ * signed integer values (#gint and #gssize) and the 'and', 'or', and
+ * 'xor' operations operate on (and return) unsigned integer values
+ * (#guint and #gsize).
+ *
+ * All of the operations act as a full compiler and (where appropriate)
+ * hardware memory barrier. Acquire and release or producer and
+ * consumer barrier semantics are not available through this API.
+ *
+ * It is very important that all accesses to a particular integer or
+ * pointer be performed using only this API and that different sizes of
+ * operation are not mixed or used on overlapping memory regions. Never
+ * read or assign directly from or to a value -- always use this API.
+ *
+ * For simple reference counting purposes you should use
+ * g_atomic_int_inc() and g_atomic_int_dec_and_test(). Other uses that
+ * fall outside of simple reference counting patterns are prone to
+ * subtle bugs and occasionally undefined behaviour. It is also worth
+ * noting that since all of these operations require global
+ * synchronisation of the entire machine, they can be quite slow. In * the case of performing multiple atomic operations it can often be
+ * faster to simply acquire a mutex lock around the critical area,
+ * perform the operations normally and then release the lock.
+ **/
+
+/**
+ * G_ATOMIC_LOCK_FREE:
+ *
+ * This macro is defined if the atomic operations of GLib are
+ * implemented using real hardware atomic operations. This means that
+ * the GLib atomic API can be used between processes and safely mixed
+ * with other (hardware) atomic APIs.
+ *
+ * If this macro is not defined, the atomic operations may be
+ * emulated using a mutex. In that case, the GLib atomic operations are
+ * only atomic relative to themselves and within a single process.
+ **/
+
+/* NOTE CAREFULLY:
+ *
+ * This file is the lowest-level part of GLib.
+ *
+ * Other lowlevel parts of GLib (threads, slice allocator, g_malloc,
+ * messages, etc) call into these functions and macros to get work done.
+ *
+ * As such, these functions can not call back into any part of GLib
+ * without risking recursion.