Atomic Operations

Atomic Operations

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 guintptr.

There is no support for 64-bit operations on platforms with 32-bit 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 gatomicrefcount (see g_atomic_ref_count_init()) rather than g_atomic_int_inc() and g_atomic_int_dec_and_test().

Uses of g_atomic_int_inc() and g_atomic_int_dec_and_test() that fall outside of simple 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.

Atomic Integer Operations

Atomic Pointer Operations

Deprecated API