glib-Asynchronous-Queues.html [plain text]
<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>Asynchronous Queues</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-core.html" title="GLib Core Application Support"><link rel="previous" href="glib-Thread-Pools.html" title="Thread Pools"><link rel="next" href="glib-Dynamic-Loading-of-Modules.html" title="Dynamic Loading of Modules"><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-Asynchronous-Queues.html#id3052167" title="Description"><link rel="section" href="glib-Asynchronous-Queues.html#id3052324" title="Details"><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-Thread-Pools.html"><img src="left.png" width="24" height="24" border="0" alt="Prev"></a></td><td><a accesskey="u" href="glib-core.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-Dynamic-Loading-of-Modules.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-Asynchronous-Queues"></a><div class="titlepage"><div></div><div></div></div><div class="refnamediv"><h2><span class="refentrytitle">Asynchronous Queues</span></h2><p>Asynchronous Queues — asynchronous communication between threads.</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><pre class="synopsis">
#include <glib.h>
struct <a href="glib-Asynchronous-Queues.html#GAsyncQueue">GAsyncQueue</a>;
<a href="glib-Asynchronous-Queues.html#GAsyncQueue">GAsyncQueue</a>* <a href="glib-Asynchronous-Queues.html#g-async-queue-new">g_async_queue_new</a> (void);
void <a href="glib-Asynchronous-Queues.html#g-async-queue-ref">g_async_queue_ref</a> (<a href="glib-Asynchronous-Queues.html#GAsyncQueue">GAsyncQueue</a> *queue);
void <a href="glib-Asynchronous-Queues.html#g-async-queue-unref">g_async_queue_unref</a> (<a href="glib-Asynchronous-Queues.html#GAsyncQueue">GAsyncQueue</a> *queue);
void <a href="glib-Asynchronous-Queues.html#g-async-queue-push">g_async_queue_push</a> (<a href="glib-Asynchronous-Queues.html#GAsyncQueue">GAsyncQueue</a> *queue,
<a href="glib-Basic-Types.html#gpointer">gpointer</a> data);
<a href="glib-Basic-Types.html#gpointer">gpointer</a> <a href="glib-Asynchronous-Queues.html#g-async-queue-pop">g_async_queue_pop</a> (<a href="glib-Asynchronous-Queues.html#GAsyncQueue">GAsyncQueue</a> *queue);
<a href="glib-Basic-Types.html#gpointer">gpointer</a> <a href="glib-Asynchronous-Queues.html#g-async-queue-try-pop">g_async_queue_try_pop</a> (<a href="glib-Asynchronous-Queues.html#GAsyncQueue">GAsyncQueue</a> *queue);
<a href="glib-Basic-Types.html#gpointer">gpointer</a> <a href="glib-Asynchronous-Queues.html#g-async-queue-timed-pop">g_async_queue_timed_pop</a> (<a href="glib-Asynchronous-Queues.html#GAsyncQueue">GAsyncQueue</a> *queue,
<a href="glib-Date-and-Time-Functions.html#GTimeVal">GTimeVal</a> *end_time);
<a href="glib-Basic-Types.html#gint">gint</a> <a href="glib-Asynchronous-Queues.html#g-async-queue-length">g_async_queue_length</a> (<a href="glib-Asynchronous-Queues.html#GAsyncQueue">GAsyncQueue</a> *queue);
void <a href="glib-Asynchronous-Queues.html#g-async-queue-lock">g_async_queue_lock</a> (<a href="glib-Asynchronous-Queues.html#GAsyncQueue">GAsyncQueue</a> *queue);
void <a href="glib-Asynchronous-Queues.html#g-async-queue-unlock">g_async_queue_unlock</a> (<a href="glib-Asynchronous-Queues.html#GAsyncQueue">GAsyncQueue</a> *queue);
void <a href="glib-Asynchronous-Queues.html#g-async-queue-ref-unlocked">g_async_queue_ref_unlocked</a> (<a href="glib-Asynchronous-Queues.html#GAsyncQueue">GAsyncQueue</a> *queue);
void <a href="glib-Asynchronous-Queues.html#g-async-queue-unref-and-unlock">g_async_queue_unref_and_unlock</a> (<a href="glib-Asynchronous-Queues.html#GAsyncQueue">GAsyncQueue</a> *queue);
void <a href="glib-Asynchronous-Queues.html#g-async-queue-push-unlocked">g_async_queue_push_unlocked</a> (<a href="glib-Asynchronous-Queues.html#GAsyncQueue">GAsyncQueue</a> *queue,
<a href="glib-Basic-Types.html#gpointer">gpointer</a> data);
<a href="glib-Basic-Types.html#gpointer">gpointer</a> <a href="glib-Asynchronous-Queues.html#g-async-queue-pop-unlocked">g_async_queue_pop_unlocked</a> (<a href="glib-Asynchronous-Queues.html#GAsyncQueue">GAsyncQueue</a> *queue);
<a href="glib-Basic-Types.html#gpointer">gpointer</a> <a href="glib-Asynchronous-Queues.html#g-async-queue-try-pop-unlocked">g_async_queue_try_pop_unlocked</a> (<a href="glib-Asynchronous-Queues.html#GAsyncQueue">GAsyncQueue</a> *queue);
<a href="glib-Basic-Types.html#gpointer">gpointer</a> <a href="glib-Asynchronous-Queues.html#g-async-queue-timed-pop-unlocked">g_async_queue_timed_pop_unlocked</a>
(<a href="glib-Asynchronous-Queues.html#GAsyncQueue">GAsyncQueue</a> *queue,
<a href="glib-Date-and-Time-Functions.html#GTimeVal">GTimeVal</a> *end_time);
<a href="glib-Basic-Types.html#gint">gint</a> <a href="glib-Asynchronous-Queues.html#g-async-queue-length-unlocked">g_async_queue_length_unlocked</a> (<a href="glib-Asynchronous-Queues.html#GAsyncQueue">GAsyncQueue</a> *queue);
</pre></div><div class="refsect1" lang="en"><a name="id3052167"></a><h2>Description</h2><p>
Often you need to communicate between different threads. In general
it's safer not to do this by shared memory, but by explicit message
passing. These messages only make sense asynchronously for
multi-threaded applications though, as a synchronous operation could as
well be done in the same thread.
</p><p>
Asynchronous queues are an exception from most other GLib data
structures, as they can be used simultaneously from multiple threads
without explicit locking and they bring their own builtin reference
counting. This is because the nature of an asynchronous queue is that
it will always be used by at least 2 concurrent threads.
</p><p>
For using an asynchronous queue you first have to create one with
<a href="glib-Asynchronous-Queues.html#g-async-queue-new"><tt class="function">g_async_queue_new()</tt></a>. A newly-created queue will get the reference
count 1. Whenever another thread is creating a new reference of (that
is, pointer to) the queue, it has to increase the reference count
(using <a href="glib-Asynchronous-Queues.html#g-async-queue-ref"><tt class="function">g_async_queue_ref()</tt></a>). Also, before removing this reference, the
reference count has to be decreased (using
<a href="glib-Asynchronous-Queues.html#g-async-queue-unref"><tt class="function">g_async_queue_unref()</tt></a>). After that the queue might no longer exist so
you must not access it after that point.
</p><p>
A thread, which wants to send a message to that queue simply calls
<a href="glib-Asynchronous-Queues.html#g-async-queue-push"><tt class="function">g_async_queue_push()</tt></a> to push the message to the queue.
</p><p>
A thread, which is expecting messages from an asynchronous queue
simply calls <a href="glib-Asynchronous-Queues.html#g-async-queue-pop"><tt class="function">g_async_queue_pop()</tt></a> for that queue. If no message is
available in the queue at that point, the thread is now put to sleep
until a message arrives. The message will be removed from the queue
and returned. The functions <a href="glib-Asynchronous-Queues.html#g-async-queue-try-pop"><tt class="function">g_async_queue_try_pop()</tt></a> and
<a href="glib-Asynchronous-Queues.html#g-async-queue-timed-pop"><tt class="function">g_async_queue_timed_pop()</tt></a> can be used to only check for the presence
of messages or to only wait a certain time for messages respectively.
</p><p>
For almost every function there exist two variants, one that locks the
queue and one that doesn't. That way you can hold the queue lock
(acquire it with <a href="glib-Asynchronous-Queues.html#g-async-queue-lock"><tt class="function">g_async_queue_lock()</tt></a> and release it with
<a href="glib-Asynchronous-Queues.html#g-async-queue-unlock"><tt class="function">g_async_queue_unlock()</tt></a>) over multiple queue accessing
instructions. This can be necessary to ensure the integrity of the
queue, but should only be used when really necessary, as it can make
your life harder if used unwisely. Normally you should only use the
locking function variants (those without the suffix _unlocked)
</p></div><div class="refsect1" lang="en"><a name="id3052324"></a><h2>Details</h2><div class="refsect2" lang="en"><a name="id3052330"></a><h3><a name="GAsyncQueue"></a>struct GAsyncQueue</h3><a class="indexterm" name="id3052340"></a><pre class="programlisting">struct GAsyncQueue;</pre><p>
The <a href="glib-Asynchronous-Queues.html#GAsyncQueue"><span class="type">GAsyncQueue</span></a> struct is an opaque data structure, which represents
an asynchronous queue. It should only be accessed through the
<tt class="function">g_async_queue_*</tt> functions.
</p></div><hr><div class="refsect2" lang="en"><a name="id3052372"></a><h3><a name="g-async-queue-new"></a>g_async_queue_new ()</h3><a class="indexterm" name="id3052383"></a><pre class="programlisting"><a href="glib-Asynchronous-Queues.html#GAsyncQueue">GAsyncQueue</a>* g_async_queue_new (void);</pre><p>
Creates a new asynchronous queue with the initial reference count of 1.</p><div class="variablelist"><table border="0"><col align="left" valign="top"><tbody><tr><td><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></td><td> the new <a href="glib-Asynchronous-Queues.html#GAsyncQueue"><span class="type">GAsyncQueue</span></a>.
</td></tr></tbody></table></div></div><hr><div class="refsect2" lang="en"><a name="id3052428"></a><h3><a name="g-async-queue-ref"></a>g_async_queue_ref ()</h3><a class="indexterm" name="id3052440"></a><pre class="programlisting">void g_async_queue_ref (<a href="glib-Asynchronous-Queues.html#GAsyncQueue">GAsyncQueue</a> *queue);</pre><p>
Increases the reference count of the asynchronous <i class="parameter"><tt>queue</tt></i> by 1. You
do not need to hold the lock to call this function.</p><div class="variablelist"><table border="0"><col align="left" valign="top"><tbody><tr><td><span class="term"><i class="parameter"><tt>queue</tt></i> :</span></td><td> a <a href="glib-Asynchronous-Queues.html#GAsyncQueue"><span class="type">GAsyncQueue</span></a>.
</td></tr></tbody></table></div></div><hr><div class="refsect2" lang="en"><a name="id3052502"></a><h3><a name="g-async-queue-unref"></a>g_async_queue_unref ()</h3><a class="indexterm" name="id3052513"></a><pre class="programlisting">void g_async_queue_unref (<a href="glib-Asynchronous-Queues.html#GAsyncQueue">GAsyncQueue</a> *queue);</pre><p>
Decreases the reference count of the asynchronous <i class="parameter"><tt>queue</tt></i> by 1. If
the reference count went to 0, the <i class="parameter"><tt>queue</tt></i> will be destroyed and the
memory allocated will be freed. So you are not allowed to use the
<i class="parameter"><tt>queue</tt></i> afterwards, as it might have disappeared. You do not need to
hold the lock to call this function.</p><div class="variablelist"><table border="0"><col align="left" valign="top"><tbody><tr><td><span class="term"><i class="parameter"><tt>queue</tt></i> :</span></td><td> a <a href="glib-Asynchronous-Queues.html#GAsyncQueue"><span class="type">GAsyncQueue</span></a>.
</td></tr></tbody></table></div></div><hr><div class="refsect2" lang="en"><a name="id3052590"></a><h3><a name="g-async-queue-push"></a>g_async_queue_push ()</h3><a class="indexterm" name="id3052601"></a><pre class="programlisting">void g_async_queue_push (<a href="glib-Asynchronous-Queues.html#GAsyncQueue">GAsyncQueue</a> *queue,
<a href="glib-Basic-Types.html#gpointer">gpointer</a> data);</pre><p>
Pushes the <i class="parameter"><tt>data</tt></i> into the <i class="parameter"><tt>queue</tt></i>. <i class="parameter"><tt>data</tt></i> must not be <tt class="literal">NULL</tt>.</p><div class="variablelist"><table border="0"><col align="left" valign="top"><tbody><tr><td><span class="term"><i class="parameter"><tt>queue</tt></i> :</span></td><td> a <a href="glib-Asynchronous-Queues.html#GAsyncQueue"><span class="type">GAsyncQueue</span></a>.
</td></tr><tr><td><span class="term"><i class="parameter"><tt>data</tt></i> :</span></td><td> <i class="parameter"><tt>data</tt></i> to push into the <i class="parameter"><tt>queue</tt></i>.
</td></tr></tbody></table></div></div><hr><div class="refsect2" lang="en"><a name="id3052712"></a><h3><a name="g-async-queue-pop"></a>g_async_queue_pop ()</h3><a class="indexterm" name="id3052724"></a><pre class="programlisting"><a href="glib-Basic-Types.html#gpointer">gpointer</a> g_async_queue_pop (<a href="glib-Asynchronous-Queues.html#GAsyncQueue">GAsyncQueue</a> *queue);</pre><p>
Pops data from the <i class="parameter"><tt>queue</tt></i>. This function blocks until data become
available.</p><div class="variablelist"><table border="0"><col align="left" valign="top"><tbody><tr><td><span class="term"><i class="parameter"><tt>queue</tt></i> :</span></td><td> a <a href="glib-Asynchronous-Queues.html#GAsyncQueue"><span class="type">GAsyncQueue</span></a>.
</td></tr><tr><td><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></td><td> data from the queue.
</td></tr></tbody></table></div></div><hr><div class="refsect2" lang="en"><a name="id3052796"></a><h3><a name="g-async-queue-try-pop"></a>g_async_queue_try_pop ()</h3><a class="indexterm" name="id3052807"></a><pre class="programlisting"><a href="glib-Basic-Types.html#gpointer">gpointer</a> g_async_queue_try_pop (<a href="glib-Asynchronous-Queues.html#GAsyncQueue">GAsyncQueue</a> *queue);</pre><p>
Tries to pop data from the <i class="parameter"><tt>queue</tt></i>. If no data is available, <tt class="literal">NULL</tt> is
returned.</p><div class="variablelist"><table border="0"><col align="left" valign="top"><tbody><tr><td><span class="term"><i class="parameter"><tt>queue</tt></i> :</span></td><td> a <a href="glib-Asynchronous-Queues.html#GAsyncQueue"><span class="type">GAsyncQueue</span></a>.
</td></tr><tr><td><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></td><td> data from the queue or <tt class="literal">NULL</tt>, when no data is
available immediately.
</td></tr></tbody></table></div></div><hr><div class="refsect2" lang="en"><a name="id3052892"></a><h3><a name="g-async-queue-timed-pop"></a>g_async_queue_timed_pop ()</h3><a class="indexterm" name="id3052903"></a><pre class="programlisting"><a href="glib-Basic-Types.html#gpointer">gpointer</a> g_async_queue_timed_pop (<a href="glib-Asynchronous-Queues.html#GAsyncQueue">GAsyncQueue</a> *queue,
<a href="glib-Date-and-Time-Functions.html#GTimeVal">GTimeVal</a> *end_time);</pre><p>
Pops data from the <i class="parameter"><tt>queue</tt></i>. If no data is received before <i class="parameter"><tt>end_time</tt></i>,
<tt class="literal">NULL</tt> is returned.
</p><p>
To easily calculate <i class="parameter"><tt>end_time</tt></i> a combination of <a href="glib-Date-and-Time-Functions.html#g-get-current-time"><tt class="function">g_get_current_time()</tt></a>
and <a href="glib-Date-and-Time-Functions.html#g-time-val-add"><tt class="function">g_time_val_add()</tt></a> can be used.</p><div class="variablelist"><table border="0"><col align="left" valign="top"><tbody><tr><td><span class="term"><i class="parameter"><tt>queue</tt></i> :</span></td><td> a <a href="glib-Asynchronous-Queues.html#GAsyncQueue"><span class="type">GAsyncQueue</span></a>.
</td></tr><tr><td><span class="term"><i class="parameter"><tt>end_time</tt></i> :</span></td><td> a <a href="glib-Date-and-Time-Functions.html#GTimeVal"><span class="type">GTimeVal</span></a>, determining the final time.
</td></tr><tr><td><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></td><td> data from the queue or <tt class="literal">NULL</tt>, when no data is
received before <i class="parameter"><tt>end_time</tt></i>.
</td></tr></tbody></table></div></div><hr><div class="refsect2" lang="en"><a name="id3053060"></a><h3><a name="g-async-queue-length"></a>g_async_queue_length ()</h3><a class="indexterm" name="id3053072"></a><pre class="programlisting"><a href="glib-Basic-Types.html#gint">gint</a> g_async_queue_length (<a href="glib-Asynchronous-Queues.html#GAsyncQueue">GAsyncQueue</a> *queue);</pre><p>
Returns the length of the queue, negative values mean waiting
threads, positive values mean available entries in the
<i class="parameter"><tt>queue</tt></i>. Actually this function returns the number of data items in
the queue minus the number of waiting threads. Thus a return value
of 0 could mean 'n' entries in the queue and 'n' thread waiting.
That can happen due to locking of the queue or due to
scheduling.</p><div class="variablelist"><table border="0"><col align="left" valign="top"><tbody><tr><td><span class="term"><i class="parameter"><tt>queue</tt></i> :</span></td><td> a <a href="glib-Asynchronous-Queues.html#GAsyncQueue"><span class="type">GAsyncQueue</span></a>.
</td></tr><tr><td><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></td><td> the length of the <i class="parameter"><tt>queue</tt></i>.
</td></tr></tbody></table></div></div><hr><div class="refsect2" lang="en"><a name="id3053155"></a><h3><a name="g-async-queue-lock"></a>g_async_queue_lock ()</h3><a class="indexterm" name="id3053166"></a><pre class="programlisting">void g_async_queue_lock (<a href="glib-Asynchronous-Queues.html#GAsyncQueue">GAsyncQueue</a> *queue);</pre><p>
Acquires the <i class="parameter"><tt>queue</tt></i>'s lock. After that you can only call the
<tt class="function">g_async_queue_*<tt class="function">_unlocked()</tt></tt> function variants on that
<i class="parameter"><tt>queue</tt></i>. Otherwise it will deadlock.</p><div class="variablelist"><table border="0"><col align="left" valign="top"><tbody><tr><td><span class="term"><i class="parameter"><tt>queue</tt></i> :</span></td><td> a <a href="glib-Asynchronous-Queues.html#GAsyncQueue"><span class="type">GAsyncQueue</span></a>.
</td></tr></tbody></table></div></div><hr><div class="refsect2" lang="en"><a name="id3053250"></a><h3><a name="g-async-queue-unlock"></a>g_async_queue_unlock ()</h3><a class="indexterm" name="id3053262"></a><pre class="programlisting">void g_async_queue_unlock (<a href="glib-Asynchronous-Queues.html#GAsyncQueue">GAsyncQueue</a> *queue);</pre><p>
Releases the queue's lock.</p><div class="variablelist"><table border="0"><col align="left" valign="top"><tbody><tr><td><span class="term"><i class="parameter"><tt>queue</tt></i> :</span></td><td> a <a href="glib-Asynchronous-Queues.html#GAsyncQueue"><span class="type">GAsyncQueue</span></a>.
</td></tr></tbody></table></div></div><hr><div class="refsect2" lang="en"><a name="id3053317"></a><h3><a name="g-async-queue-ref-unlocked"></a>g_async_queue_ref_unlocked ()</h3><a class="indexterm" name="id3053329"></a><pre class="programlisting">void g_async_queue_ref_unlocked (<a href="glib-Asynchronous-Queues.html#GAsyncQueue">GAsyncQueue</a> *queue);</pre><div class="warning" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Warning</h3><p><tt class="literal">g_async_queue_ref_unlocked</tt> is deprecated and should not be used in newly-written code.</p></div><p>
Increases the reference count of the asynchronous <i class="parameter"><tt>queue</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>queue</tt></i> :</span></td><td> a <a href="glib-Asynchronous-Queues.html#GAsyncQueue"><span class="type">GAsyncQueue</span></a>.
</td></tr></tbody></table></div></div><hr><div class="refsect2" lang="en"><a name="id3053403"></a><h3><a name="g-async-queue-unref-and-unlock"></a>g_async_queue_unref_and_unlock ()</h3><a class="indexterm" name="id3053415"></a><pre class="programlisting">void g_async_queue_unref_and_unlock (<a href="glib-Asynchronous-Queues.html#GAsyncQueue">GAsyncQueue</a> *queue);</pre><div class="warning" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Warning</h3><p><tt class="literal">g_async_queue_unref_and_unlock</tt> is deprecated and should not be used in newly-written code.</p></div><p>
Decreases the reference count of the asynchronous <i class="parameter"><tt>queue</tt></i> by 1 and
releases the lock. This function must be called while holding the
<i class="parameter"><tt>queue</tt></i>'s lock. If the reference count went to 0, the <i class="parameter"><tt>queue</tt></i> will be
destroyed and the memory allocated will be freed.</p><div class="variablelist"><table border="0"><col align="left" valign="top"><tbody><tr><td><span class="term"><i class="parameter"><tt>queue</tt></i> :</span></td><td> a <a href="glib-Asynchronous-Queues.html#GAsyncQueue"><span class="type">GAsyncQueue</span></a>.
</td></tr></tbody></table></div></div><hr><div class="refsect2" lang="en"><a name="id3053505"></a><h3><a name="g-async-queue-push-unlocked"></a>g_async_queue_push_unlocked ()</h3><a class="indexterm" name="id3053517"></a><pre class="programlisting">void g_async_queue_push_unlocked (<a href="glib-Asynchronous-Queues.html#GAsyncQueue">GAsyncQueue</a> *queue,
<a href="glib-Basic-Types.html#gpointer">gpointer</a> data);</pre><p>
Pushes the <i class="parameter"><tt>data</tt></i> into the <i class="parameter"><tt>queue</tt></i>. <i class="parameter"><tt>data</tt></i> must not be <tt class="literal">NULL</tt>. This
function must be called while holding the <i class="parameter"><tt>queue</tt></i>'s lock.</p><div class="variablelist"><table border="0"><col align="left" valign="top"><tbody><tr><td><span class="term"><i class="parameter"><tt>queue</tt></i> :</span></td><td> a <a href="glib-Asynchronous-Queues.html#GAsyncQueue"><span class="type">GAsyncQueue</span></a>.
</td></tr><tr><td><span class="term"><i class="parameter"><tt>data</tt></i> :</span></td><td> <i class="parameter"><tt>data</tt></i> to push into the <i class="parameter"><tt>queue</tt></i>.
</td></tr></tbody></table></div></div><hr><div class="refsect2" lang="en"><a name="id3053635"></a><h3><a name="g-async-queue-pop-unlocked"></a>g_async_queue_pop_unlocked ()</h3><a class="indexterm" name="id3053648"></a><pre class="programlisting"><a href="glib-Basic-Types.html#gpointer">gpointer</a> g_async_queue_pop_unlocked (<a href="glib-Asynchronous-Queues.html#GAsyncQueue">GAsyncQueue</a> *queue);</pre><p>
Pops data from the <i class="parameter"><tt>queue</tt></i>. This function blocks until data become
available. This function must be called while holding the <i class="parameter"><tt>queue</tt></i>'s
lock.</p><div class="variablelist"><table border="0"><col align="left" valign="top"><tbody><tr><td><span class="term"><i class="parameter"><tt>queue</tt></i> :</span></td><td> a <a href="glib-Asynchronous-Queues.html#GAsyncQueue"><span class="type">GAsyncQueue</span></a>.
</td></tr><tr><td><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></td><td> data from the queue.
</td></tr></tbody></table></div></div><hr><div class="refsect2" lang="en"><a name="id3053726"></a><h3><a name="g-async-queue-try-pop-unlocked"></a>g_async_queue_try_pop_unlocked ()</h3><a class="indexterm" name="id3053738"></a><pre class="programlisting"><a href="glib-Basic-Types.html#gpointer">gpointer</a> g_async_queue_try_pop_unlocked (<a href="glib-Asynchronous-Queues.html#GAsyncQueue">GAsyncQueue</a> *queue);</pre><p>
Tries to pop data from the <i class="parameter"><tt>queue</tt></i>. If no data is available, <tt class="literal">NULL</tt> is
returned. This function must be called while holding the <i class="parameter"><tt>queue</tt></i>'s
lock.</p><div class="variablelist"><table border="0"><col align="left" valign="top"><tbody><tr><td><span class="term"><i class="parameter"><tt>queue</tt></i> :</span></td><td> a <a href="glib-Asynchronous-Queues.html#GAsyncQueue"><span class="type">GAsyncQueue</span></a>.
</td></tr><tr><td><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></td><td> data from the queue or <tt class="literal">NULL</tt>, when no data is
available immediately.
</td></tr></tbody></table></div></div><hr><div class="refsect2" lang="en"><a name="id3053830"></a><h3><a name="g-async-queue-timed-pop-unlocked"></a>g_async_queue_timed_pop_unlocked ()</h3><a class="indexterm" name="id3053842"></a><pre class="programlisting"><a href="glib-Basic-Types.html#gpointer">gpointer</a> g_async_queue_timed_pop_unlocked
(<a href="glib-Asynchronous-Queues.html#GAsyncQueue">GAsyncQueue</a> *queue,
<a href="glib-Date-and-Time-Functions.html#GTimeVal">GTimeVal</a> *end_time);</pre><p>
Pops data from the <i class="parameter"><tt>queue</tt></i>. If no data is received before <i class="parameter"><tt>end_time</tt></i>,
<tt class="literal">NULL</tt> is returned. This function must be called while holding the
<i class="parameter"><tt>queue</tt></i>'s lock.
</p><p>
To easily calculate <i class="parameter"><tt>end_time</tt></i> a combination of <a href="glib-Date-and-Time-Functions.html#g-get-current-time"><tt class="function">g_get_current_time()</tt></a>
and <a href="glib-Date-and-Time-Functions.html#g-time-val-add"><tt class="function">g_time_val_add()</tt></a> can be used.</p><div class="variablelist"><table border="0"><col align="left" valign="top"><tbody><tr><td><span class="term"><i class="parameter"><tt>queue</tt></i> :</span></td><td> a <a href="glib-Asynchronous-Queues.html#GAsyncQueue"><span class="type">GAsyncQueue</span></a>.
</td></tr><tr><td><span class="term"><i class="parameter"><tt>end_time</tt></i> :</span></td><td> a <a href="glib-Date-and-Time-Functions.html#GTimeVal"><span class="type">GTimeVal</span></a>, determining the final time.
</td></tr><tr><td><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></td><td> data from the queue or <tt class="literal">NULL</tt>, when no data is
received before <i class="parameter"><tt>end_time</tt></i>.
</td></tr></tbody></table></div></div><hr><div class="refsect2" lang="en"><a name="id3054007"></a><h3><a name="g-async-queue-length-unlocked"></a>g_async_queue_length_unlocked ()</h3><a class="indexterm" name="id3054019"></a><pre class="programlisting"><a href="glib-Basic-Types.html#gint">gint</a> g_async_queue_length_unlocked (<a href="glib-Asynchronous-Queues.html#GAsyncQueue">GAsyncQueue</a> *queue);</pre><p>
Returns the length of the queue, negative values mean waiting
threads, positive values mean available entries in the
<i class="parameter"><tt>queue</tt></i>. Actually this function returns the number of data items in
the queue minus the number of waiting threads. Thus a return value
of 0 could mean 'n' entries in the queue and 'n' thread waiting.
That can happen due to locking of the queue or due to
scheduling. This function must be called while holding the <i class="parameter"><tt>queue</tt></i>'s
lock.</p><div class="variablelist"><table border="0"><col align="left" valign="top"><tbody><tr><td><span class="term"><i class="parameter"><tt>queue</tt></i> :</span></td><td> a <a href="glib-Asynchronous-Queues.html#GAsyncQueue"><span class="type">GAsyncQueue</span></a>.
</td></tr><tr><td><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></td><td> the length of the <i class="parameter"><tt>queue</tt></i>.
</td></tr></tbody></table></div></div></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-Thread-Pools.html"><b><< Thread Pools</b></a></td><td align="right"><a accesskey="n" href="glib-Dynamic-Loading-of-Modules.html"><b>Dynamic Loading of Modules >></b></a></td></tr></table></body></html>