<?xml version="1.0"?>
<!DOCTYPE refentry PUBLIC '-//OASIS//DTD DocBook XML V4.5//EN'
                      'http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd' [
<!ENTITY % local.common.attrib "xmlns:xi  CDATA  #FIXED 'http://www.w3.org/2003/XInclude'">
<!ENTITY version SYSTEM "version.xml">
]>
<refentry id="glib-Atomic-Operations">
<refmeta>
<refentrytitle role="top_of_page" id="glib-Atomic-Operations.top_of_page">Atomic Operations</refentrytitle>
<manvolnum>3</manvolnum>
<refmiscinfo>GLIB Library</refmiscinfo>
</refmeta>
<refnamediv>
<refname>Atomic Operations</refname>
<refpurpose>basic atomic integer and pointer operations</refpurpose>
</refnamediv>

<refsect1 id="glib-Atomic-Operations.functions" role="functions_proto">
<title role="functions_proto.title">Functions</title>
<informaltable pgwide="1" frame="none">
<tgroup cols="2">
<colspec colname="functions_return" colwidth="150px"/>
<colspec colname="functions_name"/>
<tbody>
<row><entry role="function_type"><link linkend="gint"><returnvalue>gint</returnvalue></link>
</entry><entry role="function_name"><link linkend="g-atomic-int-get">g_atomic_int_get</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="void"><returnvalue>void</returnvalue></link>
</entry><entry role="function_name"><link linkend="g-atomic-int-set">g_atomic_int_set</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="void"><returnvalue>void</returnvalue></link>
</entry><entry role="function_name"><link linkend="g-atomic-int-inc">g_atomic_int_inc</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="gboolean"><returnvalue>gboolean</returnvalue></link>
</entry><entry role="function_name"><link linkend="g-atomic-int-dec-and-test">g_atomic_int_dec_and_test</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="gboolean"><returnvalue>gboolean</returnvalue></link>
</entry><entry role="function_name"><link linkend="g-atomic-int-compare-and-exchange">g_atomic_int_compare_and_exchange</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="gint"><returnvalue>gint</returnvalue></link>
</entry><entry role="function_name"><link linkend="g-atomic-int-add">g_atomic_int_add</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="guint"><returnvalue>guint</returnvalue></link>
</entry><entry role="function_name"><link linkend="g-atomic-int-and">g_atomic_int_and</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="guint"><returnvalue>guint</returnvalue></link>
</entry><entry role="function_name"><link linkend="g-atomic-int-or">g_atomic_int_or</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="guint"><returnvalue>guint</returnvalue></link>
</entry><entry role="function_name"><link linkend="g-atomic-int-xor">g_atomic_int_xor</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>

<row><entry role="function_type"><link linkend="gpointer"><returnvalue>gpointer</returnvalue></link>
</entry><entry role="function_name"><link linkend="g-atomic-pointer-get">g_atomic_pointer_get</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="void"><returnvalue>void</returnvalue></link>
</entry><entry role="function_name"><link linkend="g-atomic-pointer-set">g_atomic_pointer_set</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="gboolean"><returnvalue>gboolean</returnvalue></link>
</entry><entry role="function_name"><link linkend="g-atomic-pointer-compare-and-exchange">g_atomic_pointer_compare_and_exchange</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="gssize"><returnvalue>gssize</returnvalue></link>
</entry><entry role="function_name"><link linkend="g-atomic-pointer-add">g_atomic_pointer_add</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="gsize"><returnvalue>gsize</returnvalue></link>
</entry><entry role="function_name"><link linkend="g-atomic-pointer-and">g_atomic_pointer_and</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="gsize"><returnvalue>gsize</returnvalue></link>
</entry><entry role="function_name"><link linkend="g-atomic-pointer-or">g_atomic_pointer_or</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="gsize"><returnvalue>gsize</returnvalue></link>
</entry><entry role="function_name"><link linkend="g-atomic-pointer-xor">g_atomic_pointer_xor</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>

<row><entry role="function_type"><link linkend="gint"><returnvalue>gint</returnvalue></link>
</entry><entry role="function_name"><link linkend="g-atomic-int-exchange-and-add">g_atomic_int_exchange_and_add</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>

</tbody>
</tgroup>
</informaltable>
</refsect1>
<refsect1 id="glib-Atomic-Operations.other" role="other_proto">
<title role="other_proto.title">Types and Values</title>
<informaltable role="enum_members_table" pgwide="1" frame="none">
<tgroup cols="2">
<colspec colname="name" colwidth="150px"/>
<colspec colname="description"/>
<tbody>
<row><entry role="define_keyword">#define</entry><entry role="function_name"><link linkend="G-ATOMIC-LOCK-FREE:CAPS">G_ATOMIC_LOCK_FREE</link></entry></row>

</tbody>
</tgroup>
</informaltable>
</refsect1>

<refsect1 id="glib-Atomic-Operations.includes"><title>Includes</title><synopsis>#include &lt;glib.h&gt;
</synopsis></refsect1>

<refsect1 id="glib-Atomic-Operations.description" role="desc">
<title role="desc.title">Description</title>
<para>The following is a collection of compiler macros to provide atomic
access to integer and pointer-sized values.</para>
<para>The macros that have 'int' in the name will operate on pointers to
<link linkend="gint"><type>gint</type></link> and <link linkend="guint"><type>guint</type></link>.  The macros with 'pointer' in the name will operate
on pointers to any pointer-sized value, including <link linkend="gsize"><type>gsize</type></link>.  There is
no support for 64bit operations on platforms with 32bit pointers
because it is not generally possible to perform these operations
atomically.</para>
<para>The get, set and exchange operations for integers and pointers
nominally operate on <link linkend="gint"><type>gint</type></link> and <link linkend="gpointer"><type>gpointer</type></link>, respectively.  Of the
arithmetic operations, the 'add' operation operates on (and returns)
signed integer values (<link linkend="gint"><type>gint</type></link> and <link linkend="gssize"><type>gssize</type></link>) and the 'and', 'or', and
'xor' operations operate on (and return) unsigned integer values
(<link linkend="guint"><type>guint</type></link> and <link linkend="gsize"><type>gsize</type></link>).</para>
<para>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.</para>
<para>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.</para>
<para>For simple reference counting purposes you should use
<link linkend="g-atomic-int-inc"><function>g_atomic_int_inc()</function></link> and <link linkend="g-atomic-int-dec-and-test"><function>g_atomic_int_dec_and_test()</function></link>.  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.</para>

</refsect1>
<refsect1 id="glib-Atomic-Operations.functions_details" role="details">
<title role="details.title">Functions</title>
<refsect2 id="g-atomic-int-get" role="function" condition="since:2.4">
<title>g_atomic_int_get&#160;()</title>
<indexterm zone="g-atomic-int-get" role="2.4"><primary sortas="atomic_int_get">g_atomic_int_get</primary></indexterm>
<programlisting language="C"><link linkend="gint"><returnvalue>gint</returnvalue></link>
g_atomic_int_get (<parameter>const volatile <link linkend="gint"><type>gint</type></link> *atomic</parameter>);</programlisting>
<para>Gets the current value of <parameter>atomic</parameter>
.</para>
<para>This call acts as a full compiler and hardware
memory barrier (before the get).</para>
<refsect3 id="g-atomic-int-get.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>atomic</para></entry>
<entry role="parameter_description"><para>a pointer to a <link linkend="gint"><type>gint</type></link> or <link linkend="guint"><type>guint</type></link></para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3><refsect3 id="g-atomic-int-get.returns" role="returns">
<title>Returns</title>
<para> the value of the integer</para>
</refsect3><para role="since">Since: <link linkend="api-index-2.4">2.4</link></para></refsect2>
<refsect2 id="g-atomic-int-set" role="function" condition="since:2.4">
<title>g_atomic_int_set&#160;()</title>
<indexterm zone="g-atomic-int-set" role="2.4"><primary sortas="atomic_int_set">g_atomic_int_set</primary></indexterm>
<programlisting language="C"><link linkend="void"><returnvalue>void</returnvalue></link>
g_atomic_int_set (<parameter>volatile <link linkend="gint"><type>gint</type></link> *atomic</parameter>,
                  <parameter><link linkend="gint"><type>gint</type></link> newval</parameter>);</programlisting>
<para>Sets the value of <parameter>atomic</parameter>
 to <parameter>newval</parameter>
.</para>
<para>This call acts as a full compiler and hardware
memory barrier (after the set).</para>
<refsect3 id="g-atomic-int-set.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>atomic</para></entry>
<entry role="parameter_description"><para>a pointer to a <link linkend="gint"><type>gint</type></link> or <link linkend="guint"><type>guint</type></link></para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>newval</para></entry>
<entry role="parameter_description"><para>a new value to store</para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3><para role="since">Since: <link linkend="api-index-2.4">2.4</link></para></refsect2>
<refsect2 id="g-atomic-int-inc" role="function" condition="since:2.4">
<title>g_atomic_int_inc&#160;()</title>
<indexterm zone="g-atomic-int-inc" role="2.4"><primary sortas="atomic_int_inc">g_atomic_int_inc</primary></indexterm>
<programlisting language="C"><link linkend="void"><returnvalue>void</returnvalue></link>
g_atomic_int_inc (<parameter><link linkend="gint"><type>gint</type></link> *atomic</parameter>);</programlisting>
<para>Increments the value of <parameter>atomic</parameter>
 by 1.</para>
<para>Think of this operation as an atomic version of <literal>{ *atomic += 1; }</literal>.</para>
<para>This call acts as a full compiler and hardware memory barrier.</para>
<refsect3 id="g-atomic-int-inc.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>atomic</para></entry>
<entry role="parameter_description"><para>a pointer to a <link linkend="gint"><type>gint</type></link> or <link linkend="guint"><type>guint</type></link></para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3><para role="since">Since: <link linkend="api-index-2.4">2.4</link></para></refsect2>
<refsect2 id="g-atomic-int-dec-and-test" role="function" condition="since:2.4">
<title>g_atomic_int_dec_and_test&#160;()</title>
<indexterm zone="g-atomic-int-dec-and-test" role="2.4"><primary sortas="atomic_int_dec_and_test">g_atomic_int_dec_and_test</primary></indexterm>
<programlisting language="C"><link linkend="gboolean"><returnvalue>gboolean</returnvalue></link>
g_atomic_int_dec_and_test (<parameter><link linkend="gint"><type>gint</type></link> *atomic</parameter>);</programlisting>
<para>Decrements the value of <parameter>atomic</parameter>
 by 1.</para>
<para>Think of this operation as an atomic version of
<literal>{ *atomic -= 1; return (*atomic == 0); }</literal>.</para>
<para>This call acts as a full compiler and hardware memory barrier.</para>
<refsect3 id="g-atomic-int-dec-and-test.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>atomic</para></entry>
<entry role="parameter_description"><para>a pointer to a <link linkend="gint"><type>gint</type></link> or <link linkend="guint"><type>guint</type></link></para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3><refsect3 id="g-atomic-int-dec-and-test.returns" role="returns">
<title>Returns</title>
<para> <link linkend="TRUE:CAPS"><literal>TRUE</literal></link> if the resultant value is zero</para>
</refsect3><para role="since">Since: <link linkend="api-index-2.4">2.4</link></para></refsect2>
<refsect2 id="g-atomic-int-compare-and-exchange" role="function" condition="since:2.4">
<title>g_atomic_int_compare_and_exchange&#160;()</title>
<indexterm zone="g-atomic-int-compare-and-exchange" role="2.4"><primary sortas="atomic_int_compare_and_exchange">g_atomic_int_compare_and_exchange</primary></indexterm>
<programlisting language="C"><link linkend="gboolean"><returnvalue>gboolean</returnvalue></link>
g_atomic_int_compare_and_exchange (<parameter>volatile <link linkend="gint"><type>gint</type></link> *atomic</parameter>,
                                   <parameter><link linkend="gint"><type>gint</type></link> oldval</parameter>,
                                   <parameter><link linkend="gint"><type>gint</type></link> newval</parameter>);</programlisting>
<para>Compares <parameter>atomic</parameter>
 to <parameter>oldval</parameter>
 and, if equal, sets it to <parameter>newval</parameter>
.
If <parameter>atomic</parameter>
 was not equal to <parameter>oldval</parameter>
 then no change occurs.</para>
<para>This compare and exchange is done atomically.</para>
<para>Think of this operation as an atomic version of
<literal>{ if (*atomic == oldval) { *atomic = newval; return TRUE; } else return FALSE; }</literal>.</para>
<para>This call acts as a full compiler and hardware memory barrier.</para>
<refsect3 id="g-atomic-int-compare-and-exchange.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>atomic</para></entry>
<entry role="parameter_description"><para>a pointer to a <link linkend="gint"><type>gint</type></link> or <link linkend="guint"><type>guint</type></link></para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>oldval</para></entry>
<entry role="parameter_description"><para>the value to compare with</para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>newval</para></entry>
<entry role="parameter_description"><para>the value to conditionally replace with</para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3><refsect3 id="g-atomic-int-compare-and-exchange.returns" role="returns">
<title>Returns</title>
<para> <link linkend="TRUE:CAPS"><literal>TRUE</literal></link> if the exchange took place</para>
</refsect3><para role="since">Since: <link linkend="api-index-2.4">2.4</link></para></refsect2>
<refsect2 id="g-atomic-int-add" role="function" condition="since:2.4">
<title>g_atomic_int_add&#160;()</title>
<indexterm zone="g-atomic-int-add" role="2.4"><primary sortas="atomic_int_add">g_atomic_int_add</primary></indexterm>
<programlisting language="C"><link linkend="gint"><returnvalue>gint</returnvalue></link>
g_atomic_int_add (<parameter>volatile <link linkend="gint"><type>gint</type></link> *atomic</parameter>,
                  <parameter><link linkend="gint"><type>gint</type></link> val</parameter>);</programlisting>
<para>Atomically adds <parameter>val</parameter>
 to the value of <parameter>atomic</parameter>
.</para>
<para>Think of this operation as an atomic version of
<literal>{ tmp = *atomic; *atomic += val; return tmp; }</literal>.</para>
<para>This call acts as a full compiler and hardware memory barrier.</para>
<para>Before version 2.30, this function did not return a value
(but <link linkend="g-atomic-int-exchange-and-add"><function>g_atomic_int_exchange_and_add()</function></link> did, and had the same meaning).</para>
<refsect3 id="g-atomic-int-add.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>atomic</para></entry>
<entry role="parameter_description"><para>a pointer to a <link linkend="gint"><type>gint</type></link> or <link linkend="guint"><type>guint</type></link></para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>val</para></entry>
<entry role="parameter_description"><para>the value to add</para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3><refsect3 id="g-atomic-int-add.returns" role="returns">
<title>Returns</title>
<para> the value of <parameter>atomic</parameter>
before the add, signed</para>
</refsect3><para role="since">Since: <link linkend="api-index-2.4">2.4</link></para></refsect2>
<refsect2 id="g-atomic-int-and" role="function" condition="since:2.30">
<title>g_atomic_int_and&#160;()</title>
<indexterm zone="g-atomic-int-and" role="2.30"><primary sortas="atomic_int_and">g_atomic_int_and</primary></indexterm>
<programlisting language="C"><link linkend="guint"><returnvalue>guint</returnvalue></link>
g_atomic_int_and (<parameter>volatile <link linkend="guint"><type>guint</type></link> *atomic</parameter>,
                  <parameter><link linkend="guint"><type>guint</type></link> val</parameter>);</programlisting>
<para>Performs an atomic bitwise 'and' of the value of <parameter>atomic</parameter>
 and <parameter>val</parameter>
,
storing the result back in <parameter>atomic</parameter>
.</para>
<para>This call acts as a full compiler and hardware memory barrier.</para>
<para>Think of this operation as an atomic version of
<literal>{ tmp = *atomic; *atomic &amp;amp;= val; return tmp; }</literal>.</para>
<refsect3 id="g-atomic-int-and.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>atomic</para></entry>
<entry role="parameter_description"><para>a pointer to a <link linkend="gint"><type>gint</type></link> or <link linkend="guint"><type>guint</type></link></para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>val</para></entry>
<entry role="parameter_description"><para>the value to 'and'</para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3><refsect3 id="g-atomic-int-and.returns" role="returns">
<title>Returns</title>
<para> the value of <parameter>atomic</parameter>
before the operation, unsigned</para>
</refsect3><para role="since">Since: <link linkend="api-index-2.30">2.30</link></para></refsect2>
<refsect2 id="g-atomic-int-or" role="function" condition="since:2.30">
<title>g_atomic_int_or&#160;()</title>
<indexterm zone="g-atomic-int-or" role="2.30"><primary sortas="atomic_int_or">g_atomic_int_or</primary></indexterm>
<programlisting language="C"><link linkend="guint"><returnvalue>guint</returnvalue></link>
g_atomic_int_or (<parameter>volatile <link linkend="guint"><type>guint</type></link> *atomic</parameter>,
                 <parameter><link linkend="guint"><type>guint</type></link> val</parameter>);</programlisting>
<para>Performs an atomic bitwise 'or' of the value of <parameter>atomic</parameter>
 and <parameter>val</parameter>
,
storing the result back in <parameter>atomic</parameter>
.</para>
<para>Think of this operation as an atomic version of
<literal>{ tmp = *atomic; *atomic |= val; return tmp; }</literal>.</para>
<para>This call acts as a full compiler and hardware memory barrier.</para>
<refsect3 id="g-atomic-int-or.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>atomic</para></entry>
<entry role="parameter_description"><para>a pointer to a <link linkend="gint"><type>gint</type></link> or <link linkend="guint"><type>guint</type></link></para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>val</para></entry>
<entry role="parameter_description"><para>the value to 'or'</para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3><refsect3 id="g-atomic-int-or.returns" role="returns">
<title>Returns</title>
<para> the value of <parameter>atomic</parameter>
before the operation, unsigned</para>
</refsect3><para role="since">Since: <link linkend="api-index-2.30">2.30</link></para></refsect2>
<refsect2 id="g-atomic-int-xor" role="function" condition="since:2.30">
<title>g_atomic_int_xor&#160;()</title>
<indexterm zone="g-atomic-int-xor" role="2.30"><primary sortas="atomic_int_xor">g_atomic_int_xor</primary></indexterm>
<programlisting language="C"><link linkend="guint"><returnvalue>guint</returnvalue></link>
g_atomic_int_xor (<parameter>volatile <link linkend="guint"><type>guint</type></link> *atomic</parameter>,
                  <parameter><link linkend="guint"><type>guint</type></link> val</parameter>);</programlisting>
<para>Performs an atomic bitwise 'xor' of the value of <parameter>atomic</parameter>
 and <parameter>val</parameter>
,
storing the result back in <parameter>atomic</parameter>
.</para>
<para>Think of this operation as an atomic version of
<literal>{ tmp = *atomic; *atomic ^= val; return tmp; }</literal>.</para>
<para>This call acts as a full compiler and hardware memory barrier.</para>
<refsect3 id="g-atomic-int-xor.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>atomic</para></entry>
<entry role="parameter_description"><para>a pointer to a <link linkend="gint"><type>gint</type></link> or <link linkend="guint"><type>guint</type></link></para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>val</para></entry>
<entry role="parameter_description"><para>the value to 'xor'</para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3><refsect3 id="g-atomic-int-xor.returns" role="returns">
<title>Returns</title>
<para> the value of <parameter>atomic</parameter>
before the operation, unsigned</para>
</refsect3><para role="since">Since: <link linkend="api-index-2.30">2.30</link></para></refsect2>
<refsect2 id="g-atomic-pointer-get" role="function" condition="since:2.4">
<title>g_atomic_pointer_get&#160;()</title>
<indexterm zone="g-atomic-pointer-get" role="2.4"><primary sortas="atomic_pointer_get">g_atomic_pointer_get</primary></indexterm>
<programlisting language="C"><link linkend="gpointer"><returnvalue>gpointer</returnvalue></link>
g_atomic_pointer_get (<parameter>const volatile <link linkend="void"><type>void</type></link> *atomic</parameter>);</programlisting>
<para>Gets the current value of <parameter>atomic</parameter>
.</para>
<para>This call acts as a full compiler and hardware
memory barrier (before the get).</para>
<refsect3 id="g-atomic-pointer-get.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>atomic</para></entry>
<entry role="parameter_description"><para>a pointer to a <link linkend="gpointer-sized"><type>gpointer-sized</type></link> value. </para></entry>
<entry role="parameter_annotations"><emphasis role="annotation">[<acronym>not nullable</acronym>]</emphasis></entry></row>
</tbody></tgroup></informaltable>
</refsect3><refsect3 id="g-atomic-pointer-get.returns" role="returns">
<title>Returns</title>
<para> the value of the pointer</para>
</refsect3><para role="since">Since: <link linkend="api-index-2.4">2.4</link></para></refsect2>
<refsect2 id="g-atomic-pointer-set" role="function" condition="since:2.4">
<title>g_atomic_pointer_set&#160;()</title>
<indexterm zone="g-atomic-pointer-set" role="2.4"><primary sortas="atomic_pointer_set">g_atomic_pointer_set</primary></indexterm>
<programlisting language="C"><link linkend="void"><returnvalue>void</returnvalue></link>
g_atomic_pointer_set (<parameter>volatile <link linkend="void"><type>void</type></link> *atomic</parameter>,
                      <parameter><link linkend="gpointer"><type>gpointer</type></link> newval</parameter>);</programlisting>
<para>Sets the value of <parameter>atomic</parameter>
 to <parameter>newval</parameter>
.</para>
<para>This call acts as a full compiler and hardware
memory barrier (after the set).</para>
<refsect3 id="g-atomic-pointer-set.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>atomic</para></entry>
<entry role="parameter_description"><para>a pointer to a <link linkend="gpointer-sized"><type>gpointer-sized</type></link> value. </para></entry>
<entry role="parameter_annotations"><emphasis role="annotation">[<acronym>not nullable</acronym>]</emphasis></entry></row>
<row><entry role="parameter_name"><para>newval</para></entry>
<entry role="parameter_description"><para>a new value to store</para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3><para role="since">Since: <link linkend="api-index-2.4">2.4</link></para></refsect2>
<refsect2 id="g-atomic-pointer-compare-and-exchange" role="function" condition="since:2.4">
<title>g_atomic_pointer_compare_and_exchange&#160;()</title>
<indexterm zone="g-atomic-pointer-compare-and-exchange" role="2.4"><primary sortas="atomic_pointer_compare_and_exchange">g_atomic_pointer_compare_and_exchange</primary></indexterm>
<programlisting language="C"><link linkend="gboolean"><returnvalue>gboolean</returnvalue></link>
g_atomic_pointer_compare_and_exchange (<parameter>volatile <link linkend="void"><type>void</type></link> *atomic</parameter>,
                                       <parameter><link linkend="gpointer"><type>gpointer</type></link> oldval</parameter>,
                                       <parameter><link linkend="gpointer"><type>gpointer</type></link> newval</parameter>);</programlisting>
<para>Compares <parameter>atomic</parameter>
 to <parameter>oldval</parameter>
 and, if equal, sets it to <parameter>newval</parameter>
.
If <parameter>atomic</parameter>
 was not equal to <parameter>oldval</parameter>
 then no change occurs.</para>
<para>This compare and exchange is done atomically.</para>
<para>Think of this operation as an atomic version of
<literal>{ if (*atomic == oldval) { *atomic = newval; return TRUE; } else return FALSE; }</literal>.</para>
<para>This call acts as a full compiler and hardware memory barrier.</para>
<refsect3 id="g-atomic-pointer-compare-and-exchange.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>atomic</para></entry>
<entry role="parameter_description"><para>a pointer to a <link linkend="gpointer-sized"><type>gpointer-sized</type></link> value. </para></entry>
<entry role="parameter_annotations"><emphasis role="annotation">[<acronym>not nullable</acronym>]</emphasis></entry></row>
<row><entry role="parameter_name"><para>oldval</para></entry>
<entry role="parameter_description"><para>the value to compare with</para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>newval</para></entry>
<entry role="parameter_description"><para>the value to conditionally replace with</para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3><refsect3 id="g-atomic-pointer-compare-and-exchange.returns" role="returns">
<title>Returns</title>
<para> <link linkend="TRUE:CAPS"><literal>TRUE</literal></link> if the exchange took place</para>
</refsect3><para role="since">Since: <link linkend="api-index-2.4">2.4</link></para></refsect2>
<refsect2 id="g-atomic-pointer-add" role="function" condition="since:2.30">
<title>g_atomic_pointer_add&#160;()</title>
<indexterm zone="g-atomic-pointer-add" role="2.30"><primary sortas="atomic_pointer_add">g_atomic_pointer_add</primary></indexterm>
<programlisting language="C"><link linkend="gssize"><returnvalue>gssize</returnvalue></link>
g_atomic_pointer_add (<parameter>volatile <link linkend="void"><type>void</type></link> *atomic</parameter>,
                      <parameter><link linkend="gssize"><type>gssize</type></link> val</parameter>);</programlisting>
<para>Atomically adds <parameter>val</parameter>
 to the value of <parameter>atomic</parameter>
.</para>
<para>Think of this operation as an atomic version of
<literal>{ tmp = *atomic; *atomic += val; return tmp; }</literal>.</para>
<para>This call acts as a full compiler and hardware memory barrier.</para>
<refsect3 id="g-atomic-pointer-add.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>atomic</para></entry>
<entry role="parameter_description"><para>a pointer to a <link linkend="gpointer-sized"><type>gpointer-sized</type></link> value. </para></entry>
<entry role="parameter_annotations"><emphasis role="annotation">[<acronym>not nullable</acronym>]</emphasis></entry></row>
<row><entry role="parameter_name"><para>val</para></entry>
<entry role="parameter_description"><para>the value to add</para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3><refsect3 id="g-atomic-pointer-add.returns" role="returns">
<title>Returns</title>
<para> the value of <parameter>atomic</parameter>
before the add, signed</para>
</refsect3><para role="since">Since: <link linkend="api-index-2.30">2.30</link></para></refsect2>
<refsect2 id="g-atomic-pointer-and" role="function" condition="since:2.30">
<title>g_atomic_pointer_and&#160;()</title>
<indexterm zone="g-atomic-pointer-and" role="2.30"><primary sortas="atomic_pointer_and">g_atomic_pointer_and</primary></indexterm>
<programlisting language="C"><link linkend="gsize"><returnvalue>gsize</returnvalue></link>
g_atomic_pointer_and (<parameter>volatile <link linkend="void"><type>void</type></link> *atomic</parameter>,
                      <parameter><link linkend="gsize"><type>gsize</type></link> val</parameter>);</programlisting>
<para>Performs an atomic bitwise 'and' of the value of <parameter>atomic</parameter>
 and <parameter>val</parameter>
,
storing the result back in <parameter>atomic</parameter>
.</para>
<para>Think of this operation as an atomic version of
<literal>{ tmp = *atomic; *atomic &amp;amp;= val; return tmp; }</literal>.</para>
<para>This call acts as a full compiler and hardware memory barrier.</para>
<refsect3 id="g-atomic-pointer-and.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>atomic</para></entry>
<entry role="parameter_description"><para>a pointer to a <link linkend="gpointer-sized"><type>gpointer-sized</type></link> value. </para></entry>
<entry role="parameter_annotations"><emphasis role="annotation">[<acronym>not nullable</acronym>]</emphasis></entry></row>
<row><entry role="parameter_name"><para>val</para></entry>
<entry role="parameter_description"><para>the value to 'and'</para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3><refsect3 id="g-atomic-pointer-and.returns" role="returns">
<title>Returns</title>
<para> the value of <parameter>atomic</parameter>
before the operation, unsigned</para>
</refsect3><para role="since">Since: <link linkend="api-index-2.30">2.30</link></para></refsect2>
<refsect2 id="g-atomic-pointer-or" role="function" condition="since:2.30">
<title>g_atomic_pointer_or&#160;()</title>
<indexterm zone="g-atomic-pointer-or" role="2.30"><primary sortas="atomic_pointer_or">g_atomic_pointer_or</primary></indexterm>
<programlisting language="C"><link linkend="gsize"><returnvalue>gsize</returnvalue></link>
g_atomic_pointer_or (<parameter>volatile <link linkend="void"><type>void</type></link> *atomic</parameter>,
                     <parameter><link linkend="gsize"><type>gsize</type></link> val</parameter>);</programlisting>
<para>Performs an atomic bitwise 'or' of the value of <parameter>atomic</parameter>
 and <parameter>val</parameter>
,
storing the result back in <parameter>atomic</parameter>
.</para>
<para>Think of this operation as an atomic version of
<literal>{ tmp = *atomic; *atomic |= val; return tmp; }</literal>.</para>
<para>This call acts as a full compiler and hardware memory barrier.</para>
<refsect3 id="g-atomic-pointer-or.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>atomic</para></entry>
<entry role="parameter_description"><para>a pointer to a <link linkend="gpointer-sized"><type>gpointer-sized</type></link> value. </para></entry>
<entry role="parameter_annotations"><emphasis role="annotation">[<acronym>not nullable</acronym>]</emphasis></entry></row>
<row><entry role="parameter_name"><para>val</para></entry>
<entry role="parameter_description"><para>the value to 'or'</para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3><refsect3 id="g-atomic-pointer-or.returns" role="returns">
<title>Returns</title>
<para> the value of <parameter>atomic</parameter>
before the operation, unsigned</para>
</refsect3><para role="since">Since: <link linkend="api-index-2.30">2.30</link></para></refsect2>
<refsect2 id="g-atomic-pointer-xor" role="function" condition="since:2.30">
<title>g_atomic_pointer_xor&#160;()</title>
<indexterm zone="g-atomic-pointer-xor" role="2.30"><primary sortas="atomic_pointer_xor">g_atomic_pointer_xor</primary></indexterm>
<programlisting language="C"><link linkend="gsize"><returnvalue>gsize</returnvalue></link>
g_atomic_pointer_xor (<parameter>volatile <link linkend="void"><type>void</type></link> *atomic</parameter>,
                      <parameter><link linkend="gsize"><type>gsize</type></link> val</parameter>);</programlisting>
<para>Performs an atomic bitwise 'xor' of the value of <parameter>atomic</parameter>
 and <parameter>val</parameter>
,
storing the result back in <parameter>atomic</parameter>
.</para>
<para>Think of this operation as an atomic version of
<literal>{ tmp = *atomic; *atomic ^= val; return tmp; }</literal>.</para>
<para>This call acts as a full compiler and hardware memory barrier.</para>
<refsect3 id="g-atomic-pointer-xor.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>atomic</para></entry>
<entry role="parameter_description"><para>a pointer to a <link linkend="gpointer-sized"><type>gpointer-sized</type></link> value. </para></entry>
<entry role="parameter_annotations"><emphasis role="annotation">[<acronym>not nullable</acronym>]</emphasis></entry></row>
<row><entry role="parameter_name"><para>val</para></entry>
<entry role="parameter_description"><para>the value to 'xor'</para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3><refsect3 id="g-atomic-pointer-xor.returns" role="returns">
<title>Returns</title>
<para> the value of <parameter>atomic</parameter>
before the operation, unsigned</para>
</refsect3><para role="since">Since: <link linkend="api-index-2.30">2.30</link></para></refsect2>
<refsect2 id="g-atomic-int-exchange-and-add" role="function" condition="deprecated:2.30: Use g_atomic_int_add() instead.|since:2.4">
<title>g_atomic_int_exchange_and_add&#160;()</title>
<indexterm zone="g-atomic-int-exchange-and-add" role="deprecated"><primary sortas="atomic_int_exchange_and_add">g_atomic_int_exchange_and_add</primary></indexterm><indexterm zone="g-atomic-int-exchange-and-add" role="2.4"><primary sortas="atomic_int_exchange_and_add">g_atomic_int_exchange_and_add</primary></indexterm>
<programlisting language="C"><link linkend="gint"><returnvalue>gint</returnvalue></link>
g_atomic_int_exchange_and_add (<parameter>volatile <link linkend="gint"><type>gint</type></link> *atomic</parameter>,
                               <parameter><link linkend="gint"><type>gint</type></link> val</parameter>);</programlisting>
<warning><para><literal>g_atomic_int_exchange_and_add</literal> has been deprecated since version 2.30 and should not be used in newly-written code.</para> <para>Use <link linkend="g-atomic-int-add"><function>g_atomic_int_add()</function></link> instead.</para>
</warning>
<para>This function existed before <link linkend="g-atomic-int-add"><function>g_atomic_int_add()</function></link> returned the prior
value of the integer (which it now does).  It is retained only for
compatibility reasons.  Don't use this function in new code.</para>
<refsect3 id="g-atomic-int-exchange-and-add.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>atomic</para></entry>
<entry role="parameter_description"><para>a pointer to a <link linkend="gint"><type>gint</type></link></para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>val</para></entry>
<entry role="parameter_description"><para>the value to add</para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3><refsect3 id="g-atomic-int-exchange-and-add.returns" role="returns">
<title>Returns</title>
<para> the value of <parameter>atomic</parameter>
before the add, signed</para>
</refsect3><para role="since">Since: <link linkend="api-index-2.4">2.4</link></para></refsect2>

</refsect1>
<refsect1 id="glib-Atomic-Operations.other_details" role="details">
<title role="details.title">Types and Values</title>
<refsect2 id="G-ATOMIC-LOCK-FREE:CAPS" role="macro">
<title>G_ATOMIC_LOCK_FREE</title>
<indexterm zone="G-ATOMIC-LOCK-FREE:CAPS"><primary sortas="ATOMIC_LOCK_FREE">G_ATOMIC_LOCK_FREE</primary></indexterm>
<programlisting language="C">#define G_ATOMIC_LOCK_FREE
</programlisting>
<para>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.</para>
<para>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.</para>
</refsect2>

</refsect1>
<refsect1 id="glib-Atomic-Operations.see-also">
<title>See Also</title>
<para><link linkend="GMutex"><type>GMutex</type></link></para>

</refsect1>

</refentry>
