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

<refsynopsisdiv id="glib-Atomic-Operations.synopsis" role="synopsis">
<title role="synopsis.title">Synopsis</title>

<synopsis>

#include &lt;glib.h&gt;

<link linkend="gint">gint</link>                <link linkend="g-atomic-int-get">g_atomic_int_get</link>                    ();
<link linkend="void">void</link>                <link linkend="g-atomic-int-set">g_atomic_int_set</link>                    ();
<link linkend="void">void</link>                <link linkend="g-atomic-int-add">g_atomic_int_add</link>                    ();
<link linkend="gint">gint</link>                <link linkend="g-atomic-int-exchange-and-add">g_atomic_int_exchange_and_add</link>       ();
<link linkend="gboolean">gboolean</link>            <link linkend="g-atomic-int-compare-and-exchange">g_atomic_int_compare_and_exchange</link>   ();
<link linkend="gpointer">gpointer</link>            <link linkend="g-atomic-pointer-get">g_atomic_pointer_get</link>                ();
<link linkend="void">void</link>                <link linkend="g-atomic-pointer-set">g_atomic_pointer_set</link>                ();
<link linkend="gboolean">gboolean</link>            <link linkend="g-atomic-pointer-compare-and-exchange">g_atomic_pointer_compare_and_exchange</link>
                                                        ();
<link linkend="void">void</link>                <link linkend="g-atomic-int-inc">g_atomic_int_inc</link>                    (<link linkend="gint">gint</link> *atomic);
<link linkend="gboolean">gboolean</link>            <link linkend="g-atomic-int-dec-and-test">g_atomic_int_dec_and_test</link>           (<link linkend="gint">gint</link> *atomic);
</synopsis>
</refsynopsisdiv>









<refsect1 id="glib-Atomic-Operations.description" role="desc">
<title role="desc.title">Description</title>
<para>
The following functions can be used to atomically access integers and
pointers. They are implemented as inline assembler function on most
platforms and use slower fall-backs otherwise. Using them can sometimes
save you from using a performance-expensive <link linkend="GMutex"><type>GMutex</type></link> to protect the
integer or pointer.
</para>
<para>
The most important usage is reference counting. Using
<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> makes reference
counting a very fast operation.
</para>
<note>
<para>
You must not directly read integers or pointers concurrently accessed
by multiple threads, but use the atomic accessor functions instead.
That is, always use <link linkend="g-atomic-int-get"><function>g_atomic_int_get()</function></link> and <link linkend="g-atomic-pointer-get"><function>g_atomic_pointer_get()</function></link> for
read outs.
They provide the neccessary synchonization mechanisms like memory
barriers to access memory locations concurrently.
</para>
</note>
<note>
<para>
If you are using those functions for anything apart from simple
reference counting, you should really be aware of the implications of
doing that. There are literally thousands of ways to shoot yourself in
the foot. So if in doubt, use a <link linkend="GMutex"><type>GMutex</type></link>. If you don't know, what
memory barriers are, do not use anything but <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>.
</para>
</note>
<note>
<para>
It is not safe to set an integer or pointer just by assigning to it,
when it is concurrently accessed by other threads with the following
functions. Use <link linkend="g-atomic-int-compare-and-exchange"><function>g_atomic_int_compare_and_exchange()</function></link> or
<link linkend="g-atomic-pointer-compare-and-exchange"><function>g_atomic_pointer_compare_and_exchange()</function></link> respectively.
</para>
</note>
</refsect1>

<refsect1 id="glib-Atomic-Operations.details" role="details">
<title role="details.title">Details</title>
<refsect2 id="g-atomic-int-get" role="function" condition="since:2.4">
<title>g_atomic_int_get ()</title>
<indexterm zone="g-atomic-int-get" role="2.4"><primary sortas="atomic_int_get">g_atomic_int_get</primary></indexterm><programlisting><link linkend="gint">gint</link>                g_atomic_int_get                    ();</programlisting>
<para>
Reads the value of the integer pointed to by <parameter>atomic</parameter>. Also acts as
a memory barrier.
</para><variablelist role="params">
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara>the value of *<parameter>atomic</parameter>
</simpara></listitem></varlistentry>
</variablelist><para role="since">Since 2.4</para></refsect2>
<refsect2 id="g-atomic-int-set" role="function" condition="since:2.10">
<title>g_atomic_int_set ()</title>
<indexterm zone="g-atomic-int-set" role="2.10"><primary sortas="atomic_int_set">g_atomic_int_set</primary></indexterm><programlisting><link linkend="void">void</link>                g_atomic_int_set                    ();</programlisting>
<para>
Sets the value of the integer pointed to by <parameter>atomic</parameter>.
Also acts as a memory barrier.
</para><para role="since">Since 2.10</para></refsect2>
<refsect2 id="g-atomic-int-add" role="function" condition="since:2.4">
<title>g_atomic_int_add ()</title>
<indexterm zone="g-atomic-int-add" role="2.4"><primary sortas="atomic_int_add">g_atomic_int_add</primary></indexterm><programlisting><link linkend="void">void</link>                g_atomic_int_add                    ();</programlisting>
<para>
Atomically adds <parameter>val</parameter> to the integer pointed to by <parameter>atomic</parameter>.
Also acts as a memory barrier.
</para><para role="since">Since 2.4</para></refsect2>
<refsect2 id="g-atomic-int-exchange-and-add" role="function" condition="since:2.4">
<title>g_atomic_int_exchange_and_add ()</title>
<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><link linkend="gint">gint</link>                g_atomic_int_exchange_and_add       ();</programlisting>
<para>
Atomically adds <parameter>val</parameter> to the integer pointed to by <parameter>atomic</parameter>. It returns
the value of *<parameter>atomic</parameter> just before the addition took place.
Also acts as a memory barrier.
</para><variablelist role="params">
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara>the value of *<parameter>atomic</parameter> before the addition.
</simpara></listitem></varlistentry>
</variablelist><para role="since">Since 2.4</para></refsect2>
<refsect2 id="g-atomic-int-compare-and-exchange" role="function" condition="since:2.4">
<title>g_atomic_int_compare_and_exchange ()</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><link linkend="gboolean">gboolean</link>            g_atomic_int_compare_and_exchange   ();</programlisting>
<para>
Compares <parameter>oldval</parameter> with the integer pointed to by <parameter>atomic</parameter> and
if they are equal, atomically exchanges *<parameter>atomic</parameter> with <parameter>newval</parameter>.
Also acts as a memory barrier.
</para><variablelist role="params">
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara>%TRUE, if *<parameter>atomic</parameter> was equal <parameter>oldval</parameter>. <link linkend="FALSE--CAPS"><literal>FALSE</literal></link> otherwise.
</simpara></listitem></varlistentry>
</variablelist><para role="since">Since 2.4</para></refsect2>
<refsect2 id="g-atomic-pointer-get" role="function" condition="since:2.4">
<title>g_atomic_pointer_get ()</title>
<indexterm zone="g-atomic-pointer-get" role="2.4"><primary sortas="atomic_pointer_get">g_atomic_pointer_get</primary></indexterm><programlisting><link linkend="gpointer">gpointer</link>            g_atomic_pointer_get                ();</programlisting>
<para>
Reads the value of the pointer pointed to by <parameter>atomic</parameter>. Also acts as
a memory barrier.
</para><variablelist role="params">
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara>the value to add to *<parameter>atomic</parameter>.
</simpara></listitem></varlistentry>
</variablelist><para role="since">Since 2.4</para></refsect2>
<refsect2 id="g-atomic-pointer-set" role="function" condition="since:2.10">
<title>g_atomic_pointer_set ()</title>
<indexterm zone="g-atomic-pointer-set" role="2.10"><primary sortas="atomic_pointer_set">g_atomic_pointer_set</primary></indexterm><programlisting><link linkend="void">void</link>                g_atomic_pointer_set                ();</programlisting>
<para>
Sets the value of the pointer pointed to by <parameter>atomic</parameter>.
Also acts as a memory barrier.
</para><para role="since">Since 2.10</para></refsect2>
<refsect2 id="g-atomic-pointer-compare-and-exchange" role="function" condition="since:2.4">
<title>g_atomic_pointer_compare_and_exchange ()</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><link linkend="gboolean">gboolean</link>            g_atomic_pointer_compare_and_exchange
                                                        ();</programlisting>
<para>
Compares <parameter>oldval</parameter> with the pointer pointed to by <parameter>atomic</parameter> and
if they are equal, atomically exchanges *<parameter>atomic</parameter> with <parameter>newval</parameter>.
Also acts as a memory barrier.
</para><variablelist role="params">
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara>%TRUE, if *<parameter>atomic</parameter> was equal <parameter>oldval</parameter>. <link linkend="FALSE--CAPS"><literal>FALSE</literal></link> otherwise.
</simpara></listitem></varlistentry>
</variablelist><para role="since">Since 2.4</para></refsect2>
<refsect2 id="g-atomic-int-inc" role="function" condition="since:2.4">
<title>g_atomic_int_inc ()</title>
<indexterm zone="g-atomic-int-inc" role="2.4"><primary sortas="atomic_int_inc">g_atomic_int_inc</primary></indexterm><programlisting><link linkend="void">void</link>                g_atomic_int_inc                    (<link linkend="gint">gint</link> *atomic);</programlisting>
<para>
Atomically increments the integer pointed to by <parameter>atomic</parameter> by 1.
</para><variablelist role="params">
<varlistentry><term><parameter>atomic</parameter>&#160;:</term>
<listitem><simpara>a pointer to an integer.
</simpara></listitem></varlistentry>
</variablelist><para role="since">Since 2.4</para></refsect2>
<refsect2 id="g-atomic-int-dec-and-test" role="function" condition="since:2.4">
<title>g_atomic_int_dec_and_test ()</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><link linkend="gboolean">gboolean</link>            g_atomic_int_dec_and_test           (<link linkend="gint">gint</link> *atomic);</programlisting>
<para>
Atomically decrements the integer pointed to by <parameter>atomic</parameter> by 1.
</para><variablelist role="params">
<varlistentry><term><parameter>atomic</parameter>&#160;:</term>
<listitem><simpara>a pointer to an integer.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara>%TRUE, if the integer pointed to by <parameter>atomic</parameter> is 0 after
decrementing it.
</simpara></listitem></varlistentry>
</variablelist><para role="since">Since 2.4</para></refsect2>

</refsect1>



<refsect1 id="glib-Atomic-Operations.see-also">
<title>See Also</title>
<para>
<variablelist>
<varlistentry>
<term><link linkend="GMutex"><type>GMutex</type></link></term>
<listitem><para>GLib mutual exclusions.</para></listitem>
</varlistentry>
</variablelist>
</para>
</refsect1>

</refentry>
