glib-Atomic-Operations.html [plain text]
<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>Atomic Operations</title><meta name="generator" content="DocBook XSL Stylesheets V1.65.1"><link rel="home" href="index.html" title="GLib Reference Manual"><link rel="up" href="glib-fundamentals.html" title="GLib Fundamentals"><link rel="previous" href="glib-Miscellaneous-Macros.html" title="Miscellaneous Macros"><link rel="next" href="glib-core.html" title="GLib Core Application Support"><link rel="chapter" href="glib.html" title="GLib Overview"><link rel="refentry" href="glib-building.html" title="Compiling the GLib package"><link rel="refentry" href="glib-cross-compiling.html" title="Cross-compiling the GLib package"><link rel="refentry" href="glib-compiling.html" title="Compiling GLib Applications"><link rel="refentry" href="glib-running.html" title="Running GLib Applications"><link rel="refentry" href="glib-changes.html" title="Changes to GLib"><link rel="refentry" href="glib-resources.html" title="Mailing lists and bug reports"><link rel="chapter" href="glib-fundamentals.html" title="GLib Fundamentals"><link rel="refentry" href="glib-Basic-Types.html" title="Basic Types"><link rel="refentry" href="glib-Limits-of-Basic-Types.html" title="Limits of Basic Types"><link rel="refentry" href="glib-Standard-Macros.html" title="Standard Macros"><link rel="refentry" href="glib-Type-Conversion-Macros.html" title="Type Conversion Macros"><link rel="refentry" href="glib-Byte-Order-Macros.html" title="Byte Order Macros"><link rel="refentry" href="glib-Numerical-Definitions.html" title="Numerical Definitions"><link rel="refentry" href="glib-Miscellaneous-Macros.html" title="Miscellaneous Macros"><link rel="refentry" href="glib-Atomic-Operations.html" title="Atomic Operations"><link rel="chapter" href="glib-core.html" title="GLib Core Application Support"><link rel="refentry" href="glib-The-Main-Event-Loop.html" title="The Main Event Loop"><link rel="refentry" href="glib-Threads.html" title="
Threads"><link rel="refentry" href="glib-Thread-Pools.html" title="Thread Pools"><link rel="refentry" href="glib-Asynchronous-Queues.html" title="Asynchronous Queues"><link rel="refentry" href="glib-Dynamic-Loading-of-Modules.html" title="Dynamic Loading of Modules"><link rel="refentry" href="glib-Memory-Allocation.html" title="Memory Allocation"><link rel="refentry" href="glib-IO-Channels.html" title="IO Channels"><link rel="refentry" href="glib-Error-Reporting.html" title="Error Reporting"><link rel="refentry" href="glib-Warnings-and-Assertions.html" title="Message Output and Debugging Functions"><link rel="refentry" href="glib-Message-Logging.html" title="Message Logging"><link rel="chapter" href="glib-utilities.html" title="GLib Utilities"><link rel="refentry" href="glib-String-Utility-Functions.html" title="String Utility Functions"><link rel="refentry" href="glib-Character-Set-Conversion.html" title="Character Set Conversion"><link rel="refentry" href="glib-Unicode-Manipulation.html" title="Unicode Manipulation"><link rel="refentry" href="glib-I18N.html" title="Internationalization"><link rel="refentry" href="glib-Date-and-Time-Functions.html" title="Date and Time Functions"><link rel="refentry" href="glib-Random-Numbers.html" title="Random Numbers"><link rel="refentry" href="glib-Hook-Functions.html" title="Hook Functions"><link rel="refentry" href="glib-Miscellaneous-Utility-Functions.html" title="Miscellaneous Utility Functions"><link rel="refentry" href="glib-Lexical-Scanner.html" title="Lexical Scanner"><link rel="refentry" href="glib-Automatic-String-Completion.html" title="Automatic String Completion"><link rel="refentry" href="glib-Timers.html" title="Timers"><link rel="refentry" href="glib-Spawning-Processes.html" title="Spawning Processes"><link rel="refentry" href="glib-File-Utilities.html" title="File Utilities"><link rel="refentry" href="glib-Shell-related-Utilities.html" title="Shell-related Utilities"><link rel="refentry" href="glib-Glob-style-pattern-matching.html" title="Glob-style pattern matching"><link rel="refentry" href="glib-Simple-XML-Subset-Parser.html" title="Simple XML Subset Parser"><link rel="refentry" href="glib-Windows-Compatability-Functions.html" title="Windows Compatibility Functions"><link rel="chapter" href="glib-data-types.html" title="GLib Data Types"><link rel="refentry" href="glib-Memory-Chunks.html" title="Memory Chunks"><link rel="refentry" href="glib-Doubly-Linked-Lists.html" title="Doubly-Linked Lists"><link rel="refentry" href="glib-Singly-Linked-Lists.html" title="Singly-Linked Lists"><link rel="refentry" href="glib-Double-ended-Queues.html" title="Double-ended Queues"><link rel="refentry" href="glib-Trash-Stacks.html" title="Trash Stacks"><link rel="refentry" href="glib-Hash-Tables.html" title="Hash Tables"><link rel="refentry" href="glib-Strings.html" title="Strings"><link rel="refentry" href="glib-String-Chunks.html" title="String Chunks"><link rel="refentry" href="glib-Arrays.html" title="Arrays"><link rel="refentry" href="glib-Pointer-Arrays.html" title="Pointer Arrays"><link rel="refentry" href="glib-Byte-Arrays.html" title="Byte Arrays"><link rel="refentry" href="glib-Balanced-Binary-Trees.html" title="Balanced Binary Trees"><link rel="refentry" href="glib-N-ary-Trees.html" title="N-ary Trees"><link rel="refentry" href="glib-Quarks.html" title="Quarks"><link rel="refentry" href="glib-Keyed-Data-Lists.html" title="Keyed Data Lists"><link rel="refentry" href="glib-Datasets.html" title="Datasets"><link rel="refentry" href="glib-Relations-and-Tuples.html" title="Relations and Tuples"><link rel="refentry" href="glib-Caches.html" title="Caches"><link rel="refentry" href="glib-Memory-Allocators.html" title="Memory Allocators"><link rel="chapter" href="tools.html" title="GLib Tools"><link rel="refentry" href="glib-gettextize.html" title="glib-gettextize"><link rel="index" href="ix01.html" title="Index"><link rel="section" href="glib-Atomic-Operations.html#id2998958" title="Description"><link rel="section" href="glib-Atomic-Operations.html#id2999113" title="Details"><link rel="section" href="glib-Atomic-Operations.html#id3000050" title="See Also"><meta name="generator" content="GTK-Doc V1.2 (XML mode)"><link rel="stylesheet" href="style.css" type="text/css"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><table class="navigation" width="100%" summary="Navigation header" cellpadding="2" cellspacing="2"><tr valign="middle"><td><a accesskey="p" href="glib-Miscellaneous-Macros.html"><img src="left.png" width="24" height="24" border="0" alt="Prev"></a></td><td><a accesskey="u" href="glib-fundamentals.html"><img src="up.png" width="24" height="24" border="0" alt="Up"></a></td><td><a accesskey="h" href="index.html"><img src="home.png" width="24" height="24" border="0" alt="Home"></a></td><th width="100%" align="center">GLib Reference Manual</th><td><a accesskey="n" href="glib-core.html"><img src="right.png" width="24" height="24" border="0" alt="Next"></a></td></tr></table><div class="refentry" lang="en"><a name="glib-Atomic-Operations"></a><div class="titlepage"><div></div><div></div></div><div class="refnamediv"><h2><span class="refentrytitle">Atomic Operations</span></h2><p>Atomic Operations — basic atomic integer and pointer operations</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><pre class="synopsis">
#include <glib.h>
<a href="glib-Basic-Types.html#gint">gint</a> <a href="glib-Atomic-Operations.html#g-atomic-int-get">g_atomic_int_get</a> (<a href="glib-Basic-Types.html#gint">gint</a> *atomic);
void <a href="glib-Atomic-Operations.html#g-atomic-int-add">g_atomic_int_add</a> (<a href="glib-Basic-Types.html#gint">gint</a> *atomic,
<a href="glib-Basic-Types.html#gint">gint</a> val);
<a href="glib-Basic-Types.html#gint">gint</a> <a href="glib-Atomic-Operations.html#g-atomic-int-exchange-and-add">g_atomic_int_exchange_and_add</a> (<a href="glib-Basic-Types.html#gint">gint</a> *atomic,
<a href="glib-Basic-Types.html#gint">gint</a> val);
<a href="glib-Basic-Types.html#gboolean">gboolean</a> <a href="glib-Atomic-Operations.html#g-atomic-int-compare-and-exchange">g_atomic_int_compare_and_exchange</a>
(<a href="glib-Basic-Types.html#gint">gint</a> *atomic,
<a href="glib-Basic-Types.html#gint">gint</a> oldval,
<a href="glib-Basic-Types.html#gint">gint</a> newval);
<a href="glib-Basic-Types.html#gpointer">gpointer</a> <a href="glib-Atomic-Operations.html#g-atomic-pointer-get">g_atomic_pointer_get</a> (<a href="glib-Basic-Types.html#gpointer">gpointer</a> *atomic);
<a href="glib-Basic-Types.html#gboolean">gboolean</a> <a href="glib-Atomic-Operations.html#g-atomic-pointer-compare-and-exchange">g_atomic_pointer_compare_and_exchange</a>
(<a href="glib-Basic-Types.html#gpointer">gpointer</a> *atomic,
<a href="glib-Basic-Types.html#gpointer">gpointer</a> oldval,
<a href="glib-Basic-Types.html#gpointer">gpointer</a> newval);
void <a href="glib-Atomic-Operations.html#g-atomic-int-inc">g_atomic_int_inc</a> (<a href="glib-Basic-Types.html#gint">gint</a> *atomic);
<a href="glib-Basic-Types.html#gboolean">gboolean</a> <a href="glib-Atomic-Operations.html#g-atomic-int-dec-and-test">g_atomic_int_dec_and_test</a> (<a href="glib-Basic-Types.html#gint">gint</a> *atomic);
</pre></div><div class="refsect1" lang="en"><a name="id2998958"></a><h2>Description</h2><p>
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 <a href="glib-Threads.html#GMutex"><span class="type">GMutex</span></a> to protect the
integer or pointer.
</p><p>
The most important usage is reference counting. Using
<a href="glib-Atomic-Operations.html#g-atomic-int-inc"><tt class="function">g_atomic_int_inc()</tt></a> and <a href="glib-Atomic-Operations.html#g-atomic-int-dec-and-test"><tt class="function">g_atomic_int_dec_and_test()</tt></a> makes reference
counting a very fast operation.
</p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>
You must not directly read integers or pointers concurrently accessed
by other threads with with the following functions directly. Always use
<a href="glib-Atomic-Operations.html#g-atomic-int-get"><tt class="function">g_atomic_int_get()</tt></a> and <a href="glib-Atomic-Operations.html#g-atomic-pointer-get"><tt class="function">g_atomic_pointer_get()</tt></a> respectively. They are
acting as a memory barrier.
</p></div><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>
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 <a href="glib-Threads.html#GMutex"><span class="type">GMutex</span></a>. If you don't know, what
memory barriers are, do not use anything but <a href="glib-Atomic-Operations.html#g-atomic-int-inc"><tt class="function">g_atomic_int_inc()</tt></a> and
<a href="glib-Atomic-Operations.html#g-atomic-int-dec-and-test"><tt class="function">g_atomic_int_dec_and_test()</tt></a>.
</p></div><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>
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 <a href="glib-Atomic-Operations.html#g-atomic-int-compare-and-exchange"><tt class="function">g_atomic_int_compare_and_exchange()</tt></a> or
<a href="glib-Atomic-Operations.html#g-atomic-pointer-compare-and-exchange"><tt class="function">g_atomic_pointer_compare_and_exchange()</tt></a> respectively.
</p></div></div><div class="refsect1" lang="en"><a name="id2999113"></a><h2>Details</h2><div class="refsect2" lang="en"><a name="id2999119"></a><h3><a name="g-atomic-int-get"></a>g_atomic_int_get ()</h3><a class="indexterm" name="id2999130"></a><pre class="programlisting"><a href="glib-Basic-Types.html#gint">gint</a> g_atomic_int_get (<a href="glib-Basic-Types.html#gint">gint</a> *atomic);</pre><p>
Reads the value of the integer pointed to by <i class="parameter"><tt>atomic</tt></i>. Also acts as
a memory barrier.
</p><div class="variablelist"><table border="0"><col align="left" valign="top"><tbody><tr><td><span class="term"><i class="parameter"><tt>atomic</tt></i> :</span></td><td>a pointer to an integer.
</td></tr><tr><td><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></td><td>the value of *<i class="parameter"><tt>atomic</tt></i>.
</td></tr></tbody></table></div><p>Since 2.4
</p></div><hr><div class="refsect2" lang="en"><a name="id2999204"></a><h3><a name="g-atomic-int-add"></a>g_atomic_int_add ()</h3><a class="indexterm" name="id2999215"></a><pre class="programlisting">void g_atomic_int_add (<a href="glib-Basic-Types.html#gint">gint</a> *atomic,
<a href="glib-Basic-Types.html#gint">gint</a> val);</pre><p>
Atomically adds <i class="parameter"><tt>val</tt></i> to the integer pointed to by <i class="parameter"><tt>atomic</tt></i>.
Also acts as a memory barrier.
</p><div class="variablelist"><table border="0"><col align="left" valign="top"><tbody><tr><td><span class="term"><i class="parameter"><tt>atomic</tt></i> :</span></td><td>a pointer to an integer.
</td></tr><tr><td><span class="term"><i class="parameter"><tt>val</tt></i> :</span></td><td>the value to add to *<i class="parameter"><tt>atomic</tt></i>.
</td></tr></tbody></table></div><p>Since 2.4
</p></div><hr><div class="refsect2" lang="en"><a name="id2999306"></a><h3><a name="g-atomic-int-exchange-and-add"></a>g_atomic_int_exchange_and_add ()</h3><a class="indexterm" name="id2999318"></a><pre class="programlisting"><a href="glib-Basic-Types.html#gint">gint</a> g_atomic_int_exchange_and_add (<a href="glib-Basic-Types.html#gint">gint</a> *atomic,
<a href="glib-Basic-Types.html#gint">gint</a> val);</pre><p>
Atomically adds <i class="parameter"><tt>val</tt></i> to the integer pointed to by <i class="parameter"><tt>atomic</tt></i>. It returns
the value of *<i class="parameter"><tt>atomic</tt></i> just before the addition took place.
Also acts as a memory barrier.
</p><div class="variablelist"><table border="0"><col align="left" valign="top"><tbody><tr><td><span class="term"><i class="parameter"><tt>atomic</tt></i> :</span></td><td>a pointer to an integer.
</td></tr><tr><td><span class="term"><i class="parameter"><tt>val</tt></i> :</span></td><td>the value to add to *<i class="parameter"><tt>atomic</tt></i>.
</td></tr><tr><td><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></td><td>the value of *<i class="parameter"><tt>atomic</tt></i> before the addition.
</td></tr></tbody></table></div><p>Since 2.4
</p></div><hr><div class="refsect2" lang="en"><a name="id2999433"></a><h3><a name="g-atomic-int-compare-and-exchange"></a>g_atomic_int_compare_and_exchange ()</h3><a class="indexterm" name="id2999445"></a><pre class="programlisting"><a href="glib-Basic-Types.html#gboolean">gboolean</a> g_atomic_int_compare_and_exchange
(<a href="glib-Basic-Types.html#gint">gint</a> *atomic,
<a href="glib-Basic-Types.html#gint">gint</a> oldval,
<a href="glib-Basic-Types.html#gint">gint</a> newval);</pre><p>
Compares <i class="parameter"><tt>oldval</tt></i> with the integer pointed to by <i class="parameter"><tt>atomic</tt></i> and
if they are equal, atomically exchanges *<i class="parameter"><tt>atomic</tt></i> with <i class="parameter"><tt>newval</tt></i>.
Also acts as a memory barrier.
</p><div class="variablelist"><table border="0"><col align="left" valign="top"><tbody><tr><td><span class="term"><i class="parameter"><tt>atomic</tt></i> :</span></td><td>a pointer to an integer.
</td></tr><tr><td><span class="term"><i class="parameter"><tt>oldval</tt></i> :</span></td><td>the assumed old value of *<i class="parameter"><tt>atomic</tt></i>.
</td></tr><tr><td><span class="term"><i class="parameter"><tt>newval</tt></i> :</span></td><td>the new value of *<i class="parameter"><tt>atomic</tt></i>.
</td></tr><tr><td><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></td><td><tt class="literal">TRUE</tt>, if *<i class="parameter"><tt>atomic</tt></i> was equal <i class="parameter"><tt>oldval</tt></i>. <tt class="literal">FALSE</tt> otherwise.
</td></tr></tbody></table></div><p>Since 2.4
</p></div><hr><div class="refsect2" lang="en"><a name="id2999610"></a><h3><a name="g-atomic-pointer-get"></a>g_atomic_pointer_get ()</h3><a class="indexterm" name="id2999622"></a><pre class="programlisting"><a href="glib-Basic-Types.html#gpointer">gpointer</a> g_atomic_pointer_get (<a href="glib-Basic-Types.html#gpointer">gpointer</a> *atomic);</pre><p>
Reads the value of the pointer pointed to by <i class="parameter"><tt>atomic</tt></i>. Also acts as
a memory barrier.
</p><div class="variablelist"><table border="0"><col align="left" valign="top"><tbody><tr><td><span class="term"><i class="parameter"><tt>atomic</tt></i> :</span></td><td>a pointer to a <a href="glib-Basic-Types.html#gpointer"><span class="type">gpointer</span></a>.
</td></tr><tr><td><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></td><td>the value to add to *<i class="parameter"><tt>atomic</tt></i>.
</td></tr></tbody></table></div><p>Since 2.4
</p></div><hr><div class="refsect2" lang="en"><a name="id2999704"></a><h3><a name="g-atomic-pointer-compare-and-exchange"></a>g_atomic_pointer_compare_and_exchange ()</h3><a class="indexterm" name="id2999716"></a><pre class="programlisting"><a href="glib-Basic-Types.html#gboolean">gboolean</a> g_atomic_pointer_compare_and_exchange
(<a href="glib-Basic-Types.html#gpointer">gpointer</a> *atomic,
<a href="glib-Basic-Types.html#gpointer">gpointer</a> oldval,
<a href="glib-Basic-Types.html#gpointer">gpointer</a> newval);</pre><p>
Compares <i class="parameter"><tt>oldval</tt></i> with the pointer pointed to by <i class="parameter"><tt>atomic</tt></i> and
if they are equal, atomically exchanges *<i class="parameter"><tt>atomic</tt></i> with <i class="parameter"><tt>newval</tt></i>.
Also acts as a memory barrier.
</p><div class="variablelist"><table border="0"><col align="left" valign="top"><tbody><tr><td><span class="term"><i class="parameter"><tt>atomic</tt></i> :</span></td><td>a pointer to a <a href="glib-Basic-Types.html#gpointer"><span class="type">gpointer</span></a>.
</td></tr><tr><td><span class="term"><i class="parameter"><tt>oldval</tt></i> :</span></td><td>the assumed old value of *<i class="parameter"><tt>atomic</tt></i>.
</td></tr><tr><td><span class="term"><i class="parameter"><tt>newval</tt></i> :</span></td><td>the new value of *<i class="parameter"><tt>atomic</tt></i>.
</td></tr><tr><td><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></td><td><tt class="literal">TRUE</tt>, if *<i class="parameter"><tt>atomic</tt></i> was equal <i class="parameter"><tt>oldval</tt></i>. <tt class="literal">FALSE</tt> otherwise.
</td></tr></tbody></table></div><p>Since 2.4
</p></div><hr><div class="refsect2" lang="en"><a name="id2999889"></a><h3><a name="g-atomic-int-inc"></a>g_atomic_int_inc ()</h3><a class="indexterm" name="id2999900"></a><pre class="programlisting">void g_atomic_int_inc (<a href="glib-Basic-Types.html#gint">gint</a> *atomic);</pre><p>
Atomically increments the integer pointed to by <i class="parameter"><tt>atomic</tt></i> by 1.
</p><div class="variablelist"><table border="0"><col align="left" valign="top"><tbody><tr><td><span class="term"><i class="parameter"><tt>atomic</tt></i> :</span></td><td>a pointer to an integer.
</td></tr></tbody></table></div><p>Since 2.4
</p></div><hr><div class="refsect2" lang="en"><a name="id2999958"></a><h3><a name="g-atomic-int-dec-and-test"></a>g_atomic_int_dec_and_test ()</h3><a class="indexterm" name="id2999970"></a><pre class="programlisting"><a href="glib-Basic-Types.html#gboolean">gboolean</a> g_atomic_int_dec_and_test (<a href="glib-Basic-Types.html#gint">gint</a> *atomic);</pre><p>
Atomically decrements the integer pointed to by <i class="parameter"><tt>atomic</tt></i> by 1.
</p><div class="variablelist"><table border="0"><col align="left" valign="top"><tbody><tr><td><span class="term"><i class="parameter"><tt>atomic</tt></i> :</span></td><td>a pointer to an integer.
</td></tr><tr><td><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></td><td><tt class="literal">TRUE</tt>, if the integer pointed to by <i class="parameter"><tt>atomic</tt></i> is 0 after
decrementing it.
</td></tr></tbody></table></div><p>Since 2.4
</p></div></div><div class="refsect1" lang="en"><a name="id3000050"></a><h2>See Also</h2><p>
</p><div class="variablelist"><table border="0"><col align="left" valign="top"><tbody><tr><td><span class="term"><a href="glib-Threads.html#GMutex"><span class="type">GMutex</span></a></span></td><td><p>GLib mutual exclusions.</p></td></tr></tbody></table></div><p>
</p></div></div><table class="navigation" width="100%" summary="Navigation footer" cellpadding="2" cellspacing="0"><tr valign="middle"><td align="left"><a accesskey="p" href="glib-Miscellaneous-Macros.html"><b><< Miscellaneous Macros</b></a></td><td align="right"><a accesskey="n" href="glib-core.html"><b>GLib Core Application Support >></b></a></td></tr></table></body></html>