2 * Copyright © 2011 Ryan Lortie
4 * This library is free software; you can redistribute it and/or modify
5 * it under the terms of the GNU Lesser General Public License as
6 * published by the Free Software Foundation; either version 2 of the
7 * licence, or (at your option) any later version.
9 * This library is distributed in the hope that it will be useful, but
10 * WITHOUT ANY WARRANTY; without even the implied warranty of
11 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
12 * Lesser General Public License for more details.
14 * You should have received a copy of the GNU Lesser General Public
15 * License along with this library; if not, write to the Free Software
16 * Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307,
19 * Author: Ryan Lortie <desrt@desrt.ca>
27 * SECTION:atomic_operations
28 * @title: Atomic Operations
29 * @short_description: basic atomic integer and pointer operations
32 * The following is a collection of compiler macros to provide atomic
33 * access to integer and pointer-sized values.
35 * The macros that have 'int' in the name will operate on pointers to
36 * #gint and #guint. The macros with 'pointer' in the name will operate
37 * on pointers to any pointer-sized value, including #gsize. There is
38 * no support for 64bit operations on platforms with 32bit pointers
39 * because it is not generally possible to perform these operations
42 * The get, set and exchange operations for integers and pointers
43 * nominally operate on #gint and #gpointer, respectively. Of the
44 * arithmetic operations, the 'add' operation operates on (and returns)
45 * signed integer values (#gint and #gssize) and the 'and', 'or', and
46 * 'xor' operations operate on (and return) unsigned integer values
47 * (#guint and #gsize).
49 * All of the operations act as a full compiler and (where appropriate)
50 * hardware memory barrier. Acquire and release or producer and
51 * consumer barrier semantics are not available through this API.
53 * On GCC, these macros are implemented using GCC intrinsic operations.
54 * On non-GCC compilers they will evaluate to function calls to
55 * functions implemented by GLib.
57 * If GLib itself was compiled with GCC then these functions will again
58 * be implemented by the GCC intrinsics. On Windows without GCC, the
59 * interlocked API is used to implement the functions.
61 * With non-GCC compilers on non-Windows systems, the functions are
62 * currently incapable of implementing true atomic operations --
63 * instead, they fallback to holding a global lock while performing the
64 * operation. This provides atomicity between the threads of one
65 * process, but not between separate processes. For this reason, one
66 * should exercise caution when attempting to use these options on
67 * shared memory regions.
69 * It is very important that all accesses to a particular integer or
70 * pointer be performed using only this API and that different sizes of
71 * operation are not mixed or used on overlapping memory regions. Never
72 * read or assign directly from or to a value -- always use this API.
74 * For simple reference counting purposes you should use
75 * g_atomic_int_inc() and g_atomic_int_dec_and_test(). Other uses that
76 * fall outside of simple reference counting patterns are prone to
77 * subtle bugs and occasionally undefined behaviour. It is also worth
78 * noting that since all of these operations require global
79 * synchronisation of the entire machine, they can be quite slow. In
80 * the case of performing multiple atomic operations it can often be
81 * faster to simply acquire a mutex lock around the critical area,
82 * perform the operations normally and then release the lock.
85 #ifdef G_ATOMIC_OP_USE_GCC_BUILTINS
88 #error Using GCC builtin atomic ops, but not compiling with GCC?
93 * @atomic: a pointer to a #gint or #guint
95 * Gets the current value of @atomic.
97 * This call acts as a full compiler and hardware
98 * memory barrier (before the get).
100 * Returns: the value of the integer
105 (g_atomic_int_get) (volatile gint *atomic)
107 return g_atomic_int_get (atomic);
112 * @atomic: a pointer to a #gint or #guint
113 * @newval: a new value to store
115 * Sets the value of @atomic to @newval.
117 * This call acts as a full compiler and hardware
118 * memory barrier (after the set).
123 (g_atomic_int_set) (volatile gint *atomic,
126 g_atomic_int_set (atomic, newval);
131 * @atomic: a pointer to a #gint or #guint
133 * Increments the value of @atomic by 1.
135 * Think of this operation as an atomic version of
136 * <literal>{ *@atomic += 1; }</literal>
138 * This call acts as a full compiler and hardware memory barrier.
143 (g_atomic_int_inc) (volatile gint *atomic)
145 g_atomic_int_inc (atomic);
149 * g_atomic_int_dec_and_test:
150 * @atomic: a pointer to a #gint or #guint
152 * Decrements the value of @atomic by 1.
154 * Think of this operation as an atomic version of
155 * <literal>{ *@atomic -= 1; return (*@atomic == 0); }</literal>
157 * This call acts as a full compiler and hardware memory barrier.
159 * Returns: %TRUE if the resultant value is zero
164 (g_atomic_int_dec_and_test) (volatile gint *atomic)
166 return g_atomic_int_dec_and_test (atomic);
170 * g_atomic_int_compare_and_exchange:
171 * @atomic: a pointer to a #gint or #guint
172 * @oldval: the value to compare with
173 * @newval: the value to conditionally replace with
175 * Compares @atomic to @oldval and, if equal, sets it to @newval.
176 * If @atomic was not equal to @oldval then no change occurs.
178 * This compare and exchange is done atomically.
180 * Think of this operation as an atomic version of
181 * <literal>{ if (*@atomic == @oldval) { *@atomic = @newval; return TRUE; } else return FALSE; }</literal>
183 * This call acts as a full compiler and hardware memory barrier.
185 * Returns: %TRUE if the exchange took place
190 (g_atomic_int_compare_and_exchange) (volatile gint *atomic,
194 return g_atomic_int_compare_and_exchange (atomic, oldval, newval);
199 * @atomic: a pointer to a #gint or #guint
200 * @val: the value to add
202 * Atomically adds @val to the value of @atomic.
204 * Think of this operation as an atomic version of
205 * <literal>{ tmp = *atomic; *@atomic += @val; return tmp; }</literal>
207 * This call acts as a full compiler and hardware memory barrier.
209 * Returns: the value of @atomic before the add, signed
214 (g_atomic_int_add) (volatile gint *atomic,
217 return g_atomic_int_add (atomic, val);
222 * @atomic: a pointer to a #gint or #guint
223 * @val: the value to 'and'
225 * Performs an atomic bitwise 'and' of the value of @atomic and @val,
226 * storing the result back in @atomic.
228 * This call acts as a full compiler and hardware memory barrier.
230 * Think of this operation as an atomic version of
231 * <literal>{ tmp = *atomic; *@atomic &= @val; return tmp; }</literal>
233 * Returns: the value of @atomic before the operation, unsigned
238 (g_atomic_int_and) (volatile guint *atomic,
241 return g_atomic_int_and (atomic, val);
246 * @atomic: a pointer to a #gint or #guint
247 * @val: the value to 'or'
249 * Performs an atomic bitwise 'or' of the value of @atomic and @val,
250 * storing the result back in @atomic.
252 * Think of this operation as an atomic version of
253 * <literal>{ tmp = *atomic; *@atomic |= @val; return tmp; }</literal>
255 * This call acts as a full compiler and hardware memory barrier.
257 * Returns: the value of @atomic before the operation, unsigned
262 (g_atomic_int_or) (volatile guint *atomic,
265 return g_atomic_int_or (atomic, val);
270 * @atomic: a pointer to a #gint or #guint
271 * @val: the value to 'xor'
273 * Performs an atomic bitwise 'xor' of the value of @atomic and @val,
274 * storing the result back in @atomic.
276 * Think of this operation as an atomic version of
277 * <literal>{ tmp = *atomic; *@atomic ^= @val; return tmp; }</literal>
279 * This call acts as a full compiler and hardware memory barrier.
281 * Returns: the value of @atomic before the operation, unsigned
286 (g_atomic_int_xor) (volatile guint *atomic,
289 return g_atomic_int_xor (atomic, val);
294 * g_atomic_pointer_get:
295 * @atomic: a pointer to a #gpointer-sized value
297 * Gets the current value of @atomic.
299 * This call acts as a full compiler and hardware
300 * memory barrier (before the get).
302 * Returns: the value of the pointer
307 (g_atomic_pointer_get) (volatile void *atomic)
309 return g_atomic_pointer_get ((volatile gpointer *) atomic);
313 * g_atomic_pointer_set:
314 * @atomic: a pointer to a #gpointer-sized value
315 * @newval: a new value to store
317 * Sets the value of @atomic to @newval.
319 * This call acts as a full compiler and hardware
320 * memory barrier (after the set).
325 (g_atomic_pointer_set) (volatile void *atomic,
328 g_atomic_pointer_set ((volatile gpointer *) atomic, newval);
332 * g_atomic_pointer_compare_and_exchange:
333 * @atomic: a pointer to a #gpointer-sized value
334 * @oldval: the value to compare with
335 * @newval: the value to conditionally replace with
337 * Compares @atomic to @oldval and, if equal, sets it to @newval.
338 * If @atomic was not equal to @oldval then no change occurs.
340 * This compare and exchange is done atomically.
342 * Think of this operation as an atomic version of
343 * <literal>{ if (*@atomic == @oldval) { *@atomic = @newval; return TRUE; } else return FALSE; }</literal>
345 * This call acts as a full compiler and hardware memory barrier.
347 * Returns: %TRUE if the exchange took place
352 (g_atomic_pointer_compare_and_exchange) (volatile void *atomic,
356 return g_atomic_pointer_compare_and_exchange ((volatile gpointer *) atomic,
361 * g_atomic_pointer_add:
362 * @atomic: a pointer to a #gpointer-sized value
363 * @val: the value to add
365 * Atomically adds @val to the value of @atomic.
367 * Think of this operation as an atomic version of
368 * <literal>{ tmp = *atomic; *@atomic += @val; return tmp; }</literal>
370 * This call acts as a full compiler and hardware memory barrier.
372 * Returns: the value of @atomic before the add, signed
377 (g_atomic_pointer_add) (volatile void *atomic,
380 return g_atomic_pointer_add ((volatile gpointer *) atomic, val);
384 * g_atomic_pointer_and:
385 * @atomic: a pointer to a #gpointer-sized value
386 * @val: the value to 'and'
388 * Performs an atomic bitwise 'and' of the value of @atomic and @val,
389 * storing the result back in @atomic.
391 * Think of this operation as an atomic version of
392 * <literal>{ tmp = *atomic; *@atomic &= @val; return tmp; }</literal>
394 * This call acts as a full compiler and hardware memory barrier.
396 * Returns: the value of @atomic before the operation, unsigned
401 (g_atomic_pointer_and) (volatile void *atomic,
404 return g_atomic_pointer_and ((volatile gpointer *) atomic, val);
408 * g_atomic_pointer_or:
409 * @atomic: a pointer to a #gpointer-sized value
410 * @val: the value to 'or'
412 * Performs an atomic bitwise 'or' of the value of @atomic and @val,
413 * storing the result back in @atomic.
415 * Think of this operation as an atomic version of
416 * <literal>{ tmp = *atomic; *@atomic |= @val; return tmp; }</literal>
418 * This call acts as a full compiler and hardware memory barrier.
420 * Returns: the value of @atomic before the operation, unsigned
425 (g_atomic_pointer_or) (volatile void *atomic,
428 return g_atomic_pointer_or ((volatile gpointer *) atomic, val);
432 * g_atomic_pointer_xor:
433 * @atomic: a pointer to a #gpointer-sized value
434 * @val: the value to 'xor'
436 * Performs an atomic bitwise 'xor' of the value of @atomic and @val,
437 * storing the result back in @atomic.
439 * Think of this operation as an atomic version of
440 * <literal>{ tmp = *atomic; *@atomic ^= @val; return tmp; }</literal>
442 * This call acts as a full compiler and hardware memory barrier.
444 * Returns: the value of @atomic before the operation, unsigned
449 (g_atomic_pointer_xor) (volatile void *atomic,
452 return g_atomic_pointer_xor ((volatile gpointer *) atomic, val);
455 #elif defined (G_PLATFORM_WIN32)
458 * http://msdn.microsoft.com/en-us/library/ms684122(v=vs.85).aspx
461 (g_atomic_int_get) (volatile gint *atomic)
468 (g_atomic_int_set) (volatile gint *atomic,
476 (g_atomic_int_inc) (volatile gint *atomic)
478 InterlockedIncrement (atomic);
482 (g_atomic_int_dec_and_test) (volatile gint *atomic)
484 return InterlockedDecrement (atomic) == 0;
488 (g_atomic_int_compare_and_exchange) (volatile gint *atomic,
492 return InterlockedCompareExchange (atomic, newval, oldval) == oldval;
496 (g_atomic_int_add) (volatile gint *atomic,
499 return InterlockedExchangeAdd (atomic, val);
503 (g_atomic_int_and) (volatile guint *atomic,
506 return InterlockedAnd (atomic, val);
510 (g_atomic_int_or) (volatile guint *atomic,
513 return InterlockedOr (atomic, val);
517 (g_atomic_int_xor) (volatile guint *atomic,
520 return InterlockedXor (atomic, val);
525 (g_atomic_pointer_get) (volatile void *atomic)
527 volatile gpointer *ptr = atomic;
534 (g_atomic_pointer_set) (volatile void *atomic,
537 volatile gpointer *ptr = atomic;
544 (g_atomic_pointer_compare_and_exchange) (volatile void *atomic,
548 return InterlockedCompareExchangePointer (atomic, newval, oldval) == oldval;
552 (g_atomic_pointer_add) (volatile void *atomic,
555 #if GLIB_SIZEOF_VOID_P == 8
556 return InterlockedExchangeAdd64 (atomic, val);
558 return InterlockedExchangeAdd (atomic, val);
563 (g_atomic_pointer_and) (volatile void *atomic,
566 #if GLIB_SIZEOF_VOID_P == 8
567 return InterlockedAnd64 (atomic, val);
569 return InterlockedAnd (atomic, val);
574 (g_atomic_pointer_or) (volatile void *atomic,
577 #if GLIB_SIZEOF_VOID_P == 8
578 return InterlockedOr64 (atomic, val);
580 return InterlockedOr (atomic, val);
585 (g_atomic_pointer_xor) (volatile void *atomic,
588 #if GLIB_SIZEOF_VOID_P == 8
589 return InterlockedXor64 (atomic, val);
591 return InterlockedXor (atomic, val);
599 static GStaticMutex g_atomic_lock;
602 (g_atomic_int_get) (volatile gint *atomic)
606 g_static_mutex_lock (&g_atomic_lock);
608 g_static_mutex_unlock (&g_atomic_lock);
614 (g_atomic_int_set) (volatile gint *atomic,
617 g_static_mutex_lock (&g_atomic_lock);
619 g_static_mutex_unlock (&g_atomic_lock);
623 (g_atomic_int_inc) (volatile gint *atomic)
625 g_static_mutex_lock (&g_atomic_lock);
627 g_static_mutex_unlock (&g_atomic_lock);
631 (g_atomic_int_dec_and_test) (volatile gint *atomic)
635 g_static_mutex_lock (&g_atomic_lock);
636 is_zero = --(*atomic) == 0;
637 g_static_mutex_unlock (&g_atomic_lock);
643 (g_atomic_int_compare_and_exchange) (volatile gint *atomic,
649 g_static_mutex_lock (&g_atomic_lock);
651 if ((success = (*atomic == oldval)))
654 g_static_mutex_unlock (&g_atomic_lock);
660 (g_atomic_int_add) (volatile gint *atomic,
665 g_static_mutex_lock (&g_atomic_lock);
667 *atomic = oldval + val;
668 g_static_mutex_unlock (&g_atomic_lock);
674 (g_atomic_int_and) (volatile guint *atomic,
679 g_static_mutex_lock (&g_atomic_lock);
681 *atomic = oldval & val;
682 g_static_mutex_unlock (&g_atomic_lock);
688 (g_atomic_int_or) (volatile guint *atomic,
693 g_static_mutex_lock (&g_atomic_lock);
695 *atomic = oldval | val;
696 g_static_mutex_unlock (&g_atomic_lock);
702 (g_atomic_int_xor) (volatile guint *atomic,
707 g_static_mutex_lock (&g_atomic_lock);
709 *atomic = oldval ^ val;
710 g_static_mutex_unlock (&g_atomic_lock);
717 (g_atomic_pointer_get) (volatile void *atomic)
719 volatile gpointer *ptr = atomic;
722 g_static_mutex_lock (&g_atomic_lock);
724 g_static_mutex_unlock (&g_atomic_lock);
730 (g_atomic_pointer_set) (volatile void *atomic,
733 volatile gpointer *ptr = atomic;
735 g_static_mutex_lock (&g_atomic_lock);
737 g_static_mutex_unlock (&g_atomic_lock);
741 (g_atomic_pointer_compare_and_exchange) (volatile void *atomic,
745 volatile gpointer *ptr = atomic;
748 g_static_mutex_lock (&g_atomic_lock);
750 if ((success = (*ptr == oldval)))
753 g_static_mutex_unlock (&g_atomic_lock);
759 (g_atomic_pointer_add) (volatile void *atomic,
762 volatile gssize *ptr = atomic;
765 g_static_mutex_lock (&g_atomic_lock);
768 g_static_mutex_unlock (&g_atomic_lock);
774 (g_atomic_pointer_and) (volatile void *atomic,
777 volatile gsize *ptr = atomic;
780 g_static_mutex_lock (&g_atomic_lock);
783 g_static_mutex_unlock (&g_atomic_lock);
789 (g_atomic_pointer_or) (volatile void *atomic,
792 volatile gsize *ptr = atomic;
795 g_static_mutex_lock (&g_atomic_lock);
798 g_static_mutex_unlock (&g_atomic_lock);
804 (g_atomic_pointer_xor) (volatile void *atomic,
807 volatile gsize *ptr = atomic;
810 g_static_mutex_lock (&g_atomic_lock);
813 g_static_mutex_unlock (&g_atomic_lock);
821 * g_atomic_int_exchange_and_add:
822 * @atomic: a pointer to a #gint
823 * @val: the value to add
825 * This function existed before g_atomic_int_add() returned the prior
826 * value of the integer (which it now does). It is retained only for
827 * compatibility reasons. Don't use this function in new code.
829 * Returns: the value of @atomic before the add, signed
831 * Deprecated: 2.30: Use g_atomic_int_add() instead.
834 g_atomic_int_exchange_and_add (volatile gint *atomic,
837 return (g_atomic_int_add) (atomic, val);