docs/reference/glib/tmpl/atomic_operations.sgml

   1 <!-- ##### SECTION Title ##### -->
   2 Atomic Operations
   3
   4 <!-- ##### SECTION Short_Description ##### -->
   5 basic atomic integer and pointer operations
   6
   7 <!-- ##### SECTION Long_Description ##### -->
   8 <para>
   9 The following functions can be used to atomically access integers and
  10 pointers. They are implemented as inline assembler function on most
  11 platforms and use slower fall-backs otherwise. Using them can sometimes
  12 save you from using a performance-expensive #GMutex to protect the
  13 integer or pointer.
  14 </para>
  15
  16 <para>
  17 The most important usage is reference counting. Using
  18 g_atomic_int_inc() and g_atomic_int_dec_and_test() makes reference
  19 counting a very fast operation.
  20 </para>
  21
  22 <note>
  23 <para>
  24 You must not directly read integers or pointers concurrently accessed
  25 by other threads with with the following functions directly. Always use
  26 g_atomic_int_get() and g_atomic_pointer_get() respectively. They are
  27 acting as a memory barrier.
  28 </para>
  29 </note>
  30
  31 <note>
  32 <para>
  33 If you are using those functions for anything apart from simple
  34 reference counting, you should really be aware of the implications of
  35 doing that. There are literally thousands of ways to shoot yourself in
  36 the foot. So if in doubt, use a #GMutex. If you don't know, what
  37 memory barriers are, do not use anything but g_atomic_int_inc() and
  38 g_atomic_int_dec_and_test().
  39 </para>
  40 </note>
  41
  42 <note>
  43 <para>
  44 It is not safe to set an integer or pointer just by assigning to it,
  45 when it is concurrently accessed by other threads with the following
  46 functions. Use g_atomic_int_compare_and_exchange() or
  47 g_atomic_pointer_compare_and_exchange() respectively.
  48 </para>
  49 </note>
  50
  51 <!-- ##### SECTION See_Also ##### -->
  52 <para>
  53 <variablelist>
  54
  55 <varlistentry>
  56 <term>#GMutex</term>
  57 <listitem><para>GLib mutual exclusions.</para></listitem>
  58 </varlistentry>
  59
  60 </variablelist>
  61 </para>
  62
  63 <!-- ##### FUNCTION g_atomic_int_get ##### -->
  64 <para>
  65 Reads the value of the integer pointed to by @atomic. Also acts as
  66 a memory barrier.
  67 </para>
  68
  69 @atomic: a pointer to a 32-bit integer.
  70 @Returns: the value of *@atomic.
  71 @Since: 2.4
  72
  73
  74 <!-- ##### FUNCTION g_atomic_int_add ##### -->
  75 <para>
  76 Atomically adds @val to the integer pointed to by @atomic.
  77 Also acts as a memory barrier.
  78 </para>
  79
  80 @atomic: a pointer to a 32-bit integer.
  81 @val: the value to add to *@atomic.
  82 @Since: 2.4
  83
  84
  85 <!-- ##### FUNCTION g_atomic_int_exchange_and_add ##### -->
  86 <para>
  87 Atomically adds @val to the integer pointed to by @atomic. It returns
  88 the value of *@atomic just before the addition took place.
  89 Also acts as a memory barrier.
  90 </para>
  91
  92 @atomic: a pointer to a 32-bit integer.
  93 @val: the value to add to *@atomic.
  94 @Returns: the value of *@atomic before the addition.
  95 @Since: 2.4
  96
  97
  98 <!-- ##### FUNCTION g_atomic_int_compare_and_exchange ##### -->
  99 <para>
 100 Compares @oldval with the integer pointed to by @atomic and
 101 if they are equal, atomically exchanges *@atomic with @newval.
 102 Also acts as a memory barrier.
 103 </para>
 104
 105 @atomic: a pointer to a 32-bit integer.
 106 @oldval: the assumed old value of *@atomic.
 107 @newval: the new value of *@atomic.
 108 @Returns: %TRUE, if *@atomic was equal @oldval. %FALSE otherwise.
 109 @Since: 2.4
 110
 111
 112 <!-- ##### FUNCTION g_atomic_pointer_get ##### -->
 113 <para>
 114 Reads the value of the pointer pointed to by @atomic. Also acts as
 115 a memory barrier.
 116 </para>
 117
 118 @atomic: a pointer to a #gpointer.
 119 @Returns: the value to add to *@atomic.
 120 @Since: 2.4
 121
 122
 123 <!-- ##### FUNCTION g_atomic_pointer_compare_and_exchange ##### -->
 124 <para>
 125 Compares @oldval with the pointer pointed to by @atomic and
 126 if they are equal, atomically exchanges *@atomic with @newval.
 127 Also acts as a memory barrier.
 128 </para>
 129
 130 @atomic: a pointer to a #gpointer.
 131 @oldval: the assumed old value of *@atomic.
 132 @newval: the new value of *@atomic.
 133 @Returns: %TRUE, if *@atomic was equal @oldval. %FALSE otherwise.
 134 @Since: 2.4
 135
 136
 137 <!-- ##### FUNCTION g_atomic_int_inc ##### -->
 138 <para>
 139 Atomically increments the integer pointed to by @atomic by 1.
 140 </para>
 141
 142 @atomic: a pointer to a 32-bit integer.
 143 @Since: 2.4
 144
 145
 146 <!-- ##### FUNCTION g_atomic_int_dec_and_test ##### -->
 147 <para>
 148 Atomically decrements the integer pointed to by @atomic by 1.
 149 </para>
 150
 151 @atomic: a pointer to a 32-bit integer.
 152 @Returns: %TRUE, if the integer pointed to by @atomic is 0 after
 153 decrementing it.
 154 @Since: 2.4
 155
 156