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 multiple threads, but use the atomic accessor functions instead.
  26 That is, always use g_atomic_int_get() and g_atomic_pointer_get() for
  27 read outs.
  28 They provide the neccessary synchonization mechanisms like memory
  29 barriers to access memory locations concurrently.
  30 </para>
  31 </note>
  32
  33 <note>
  34 <para>
  35 If you are using those functions for anything apart from simple
  36 reference counting, you should really be aware of the implications of
  37 doing that. There are literally thousands of ways to shoot yourself in
  38 the foot. So if in doubt, use a #GMutex. If you don't know, what
  39 memory barriers are, do not use anything but g_atomic_int_inc() and
  40 g_atomic_int_dec_and_test().
  41 </para>
  42 </note>
  43
  44 <note>
  45 <para>
  46 It is not safe to set an integer or pointer just by assigning to it,
  47 when it is concurrently accessed by other threads with the following
  48 functions. Use g_atomic_int_compare_and_exchange() or
  49 g_atomic_pointer_compare_and_exchange() respectively.
  50 </para>
  51 </note>
  52
  53 <!-- ##### SECTION See_Also ##### -->
  54 <para>
  55 <variablelist>
  56
  57 <varlistentry>
  58 <term>#GMutex</term>
  59 <listitem><para>GLib mutual exclusions.</para></listitem>
  60 </varlistentry>
  61
  62 </variablelist>
  63 </para>
  64
  65 <!-- ##### SECTION Stability_Level ##### -->
  66
  67
  68 <!-- ##### FUNCTION g_atomic_int_get ##### -->
  69 <para>
  70 Reads the value of the integer pointed to by @atomic. Also acts as
  71 a memory barrier.
  72 </para>
  73
  74 @Returns: the value of *@atomic
  75 @Since: 2.4
  76 <!-- # Unused Parameters # -->
  77 @atomic: a pointer to an integer
  78
  79
  80 <!-- ##### FUNCTION g_atomic_int_set ##### -->
  81 <para>
  82 Sets the value of the integer pointed to by @atomic.
  83 Also acts as a memory barrier.
  84 </para>
  85
  86 @Since: 2.10
  87 <!-- # Unused Parameters # -->
  88 @atomic: a pointer to an integer
  89 @newval: the new value
  90
  91
  92 <!-- ##### FUNCTION g_atomic_int_add ##### -->
  93 <para>
  94 Atomically adds @val to the integer pointed to by @atomic.
  95 Also acts as a memory barrier.
  96 </para>
  97
  98 @Since: 2.4
  99 <!-- # Unused Parameters # -->
 100 @atomic: a pointer to an integer.
 101 @val: the value to add to *@atomic.
 102
 103
 104 <!-- ##### FUNCTION g_atomic_int_exchange_and_add ##### -->
 105 <para>
 106 Atomically adds @val to the integer pointed to by @atomic. It returns
 107 the value of *@atomic just before the addition took place.
 108 Also acts as a memory barrier.
 109 </para>
 110
 111 @Returns: the value of *@atomic before the addition.
 112 @Since: 2.4
 113 <!-- # Unused Parameters # -->
 114 @atomic: a pointer to an integer.
 115 @val: the value to add to *@atomic.
 116
 117
 118 <!-- ##### FUNCTION g_atomic_int_compare_and_exchange ##### -->
 119 <para>
 120 Compares @oldval with the integer pointed to by @atomic and
 121 if they are equal, atomically exchanges *@atomic with @newval.
 122 Also acts as a memory barrier.
 123 </para>
 124
 125 @Returns: %TRUE, if *@atomic was equal @oldval. %FALSE otherwise.
 126 @Since: 2.4
 127 <!-- # Unused Parameters # -->
 128 @atomic: a pointer to an integer.
 129 @oldval: the assumed old value of *@atomic.
 130 @newval: the new value of *@atomic.
 131
 132
 133 <!-- ##### FUNCTION g_atomic_pointer_get ##### -->
 134 <para>
 135 Reads the value of the pointer pointed to by @atomic. Also acts as
 136 a memory barrier.
 137 </para>
 138
 139 @Returns: the value to add to *@atomic.
 140 @Since: 2.4
 141 <!-- # Unused Parameters # -->
 142 @atomic: a pointer to a #gpointer.
 143
 144
 145 <!-- ##### FUNCTION g_atomic_pointer_set ##### -->
 146 <para>
 147 Sets the value of the pointer pointed to by @atomic.
 148 Also acts as a memory barrier.
 149 </para>
 150
 151 @Since: 2.10
 152 <!-- # Unused Parameters # -->
 153 @atomic: a pointer to a #gpointer
 154 @newval: the new value
 155
 156
 157 <!-- ##### FUNCTION g_atomic_pointer_compare_and_exchange ##### -->
 158 <para>
 159 Compares @oldval with the pointer pointed to by @atomic and
 160 if they are equal, atomically exchanges *@atomic with @newval.
 161 Also acts as a memory barrier.
 162 </para>
 163
 164 @Returns: %TRUE, if *@atomic was equal @oldval. %FALSE otherwise.
 165 @Since: 2.4
 166 <!-- # Unused Parameters # -->
 167 @atomic: a pointer to a #gpointer.
 168 @oldval: the assumed old value of *@atomic.
 169 @newval: the new value of *@atomic.
 170
 171
 172 <!-- ##### FUNCTION g_atomic_int_inc ##### -->
 173 <para>
 174 Atomically increments the integer pointed to by @atomic by 1.
 175 </para>
 176
 177 @atomic: a pointer to an integer.
 178 @Since: 2.4
 179
 180
 181 <!-- ##### FUNCTION g_atomic_int_dec_and_test ##### -->
 182 <para>
 183 Atomically decrements the integer pointed to by @atomic by 1.
 184 </para>
 185
 186 @atomic: a pointer to an integer.
 187 @Returns: %TRUE, if the integer pointed to by @atomic is 0 after
 188 decrementing it.
 189 @Since: 2.4
 190
 191