<refentry id="glib-Asynchronous-Queues">
<refmeta>
<refentrytitle role="top_of_page" id="glib-Asynchronous-Queues.top_of_page">Asynchronous Queues</refentrytitle>
<manvolnum>3</manvolnum>
<refmiscinfo>GLIB Library</refmiscinfo>
</refmeta>

<refnamediv>
<refname>Asynchronous Queues</refname>
<refpurpose>asynchronous communication between threads</refpurpose>
</refnamediv>

<refsynopsisdiv id="glib-Asynchronous-Queues.synopsis" role="synopsis">
<title role="synopsis.title">Synopsis</title>

<synopsis>

#include &lt;glib.h&gt;

                    <link linkend="GAsyncQueue">GAsyncQueue</link>;
<link linkend="GAsyncQueue">GAsyncQueue</link>*        <link linkend="g-async-queue-new">g_async_queue_new</link>                   (void);
<link linkend="GAsyncQueue">GAsyncQueue</link>*        <link linkend="g-async-queue-new-full">g_async_queue_new_full</link>              (<link linkend="GDestroyNotify">GDestroyNotify</link> item_free_func);
<link linkend="GAsyncQueue">GAsyncQueue</link>*        <link linkend="g-async-queue-ref">g_async_queue_ref</link>                   (<link linkend="GAsyncQueue">GAsyncQueue</link> *queue);
<link linkend="void">void</link>                <link linkend="g-async-queue-unref">g_async_queue_unref</link>                 (<link linkend="GAsyncQueue">GAsyncQueue</link> *queue);
<link linkend="void">void</link>                <link linkend="g-async-queue-push">g_async_queue_push</link>                  (<link linkend="GAsyncQueue">GAsyncQueue</link> *queue,
                                                         <link linkend="gpointer">gpointer</link> data);
<link linkend="void">void</link>                <link linkend="g-async-queue-push-sorted">g_async_queue_push_sorted</link>           (<link linkend="GAsyncQueue">GAsyncQueue</link> *queue,
                                                         <link linkend="gpointer">gpointer</link> data,
                                                         <link linkend="GCompareDataFunc">GCompareDataFunc</link> func,
                                                         <link linkend="gpointer">gpointer</link> user_data);
<link linkend="gpointer">gpointer</link>            <link linkend="g-async-queue-pop">g_async_queue_pop</link>                   (<link linkend="GAsyncQueue">GAsyncQueue</link> *queue);
<link linkend="gpointer">gpointer</link>            <link linkend="g-async-queue-try-pop">g_async_queue_try_pop</link>               (<link linkend="GAsyncQueue">GAsyncQueue</link> *queue);
<link linkend="gpointer">gpointer</link>            <link linkend="g-async-queue-timed-pop">g_async_queue_timed_pop</link>             (<link linkend="GAsyncQueue">GAsyncQueue</link> *queue,
                                                         <link linkend="GTimeVal">GTimeVal</link> *end_time);
<link linkend="gint">gint</link>                <link linkend="g-async-queue-length">g_async_queue_length</link>                (<link linkend="GAsyncQueue">GAsyncQueue</link> *queue);
<link linkend="void">void</link>                <link linkend="g-async-queue-sort">g_async_queue_sort</link>                  (<link linkend="GAsyncQueue">GAsyncQueue</link> *queue,
                                                         <link linkend="GCompareDataFunc">GCompareDataFunc</link> func,
                                                         <link linkend="gpointer">gpointer</link> user_data);

<link linkend="void">void</link>                <link linkend="g-async-queue-lock">g_async_queue_lock</link>                  (<link linkend="GAsyncQueue">GAsyncQueue</link> *queue);
<link linkend="void">void</link>                <link linkend="g-async-queue-unlock">g_async_queue_unlock</link>                (<link linkend="GAsyncQueue">GAsyncQueue</link> *queue);
<link linkend="void">void</link>                <link linkend="g-async-queue-ref-unlocked">g_async_queue_ref_unlocked</link>          (<link linkend="GAsyncQueue">GAsyncQueue</link> *queue);
<link linkend="void">void</link>                <link linkend="g-async-queue-unref-and-unlock">g_async_queue_unref_and_unlock</link>      (<link linkend="GAsyncQueue">GAsyncQueue</link> *queue);
<link linkend="void">void</link>                <link linkend="g-async-queue-push-unlocked">g_async_queue_push_unlocked</link>         (<link linkend="GAsyncQueue">GAsyncQueue</link> *queue,
                                                         <link linkend="gpointer">gpointer</link> data);
<link linkend="void">void</link>                <link linkend="g-async-queue-push-sorted-unlocked">g_async_queue_push_sorted_unlocked</link>  (<link linkend="GAsyncQueue">GAsyncQueue</link> *queue,
                                                         <link linkend="gpointer">gpointer</link> data,
                                                         <link linkend="GCompareDataFunc">GCompareDataFunc</link> func,
                                                         <link linkend="gpointer">gpointer</link> user_data);
<link linkend="gpointer">gpointer</link>            <link linkend="g-async-queue-pop-unlocked">g_async_queue_pop_unlocked</link>          (<link linkend="GAsyncQueue">GAsyncQueue</link> *queue);
<link linkend="gpointer">gpointer</link>            <link linkend="g-async-queue-try-pop-unlocked">g_async_queue_try_pop_unlocked</link>      (<link linkend="GAsyncQueue">GAsyncQueue</link> *queue);
<link linkend="gpointer">gpointer</link>            <link linkend="g-async-queue-timed-pop-unlocked">g_async_queue_timed_pop_unlocked</link>    (<link linkend="GAsyncQueue">GAsyncQueue</link> *queue,
                                                         <link linkend="GTimeVal">GTimeVal</link> *end_time);
<link linkend="gint">gint</link>                <link linkend="g-async-queue-length-unlocked">g_async_queue_length_unlocked</link>       (<link linkend="GAsyncQueue">GAsyncQueue</link> *queue);
<link linkend="void">void</link>                <link linkend="g-async-queue-sort-unlocked">g_async_queue_sort_unlocked</link>         (<link linkend="GAsyncQueue">GAsyncQueue</link> *queue,
                                                         <link linkend="GCompareDataFunc">GCompareDataFunc</link> func,
                                                         <link linkend="gpointer">gpointer</link> user_data);
</synopsis>
</refsynopsisdiv>









<refsect1 id="glib-Asynchronous-Queues.description" role="desc">
<title role="desc.title">Description</title>
<para>
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.
</para>
<para>
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.
</para>
<para>
For using an asynchronous queue you first have to create one with
<link linkend="g-async-queue-new"><function>g_async_queue_new()</function></link>. 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 <link linkend="g-async-queue-ref"><function>g_async_queue_ref()</function></link>). Also, before removing this reference, the
reference count has to be decreased (using
<link linkend="g-async-queue-unref"><function>g_async_queue_unref()</function></link>). After that the queue might no longer exist so
you must not access it after that point.
</para>
<para>
A thread, which wants to send a message to that queue simply calls
<link linkend="g-async-queue-push"><function>g_async_queue_push()</function></link> to push the message to the queue.
</para>
<para>
A thread, which is expecting messages from an asynchronous queue
simply calls <link linkend="g-async-queue-pop"><function>g_async_queue_pop()</function></link> 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 <link linkend="g-async-queue-try-pop"><function>g_async_queue_try_pop()</function></link> and
<link linkend="g-async-queue-timed-pop"><function>g_async_queue_timed_pop()</function></link> can be used to only check for the presence
of messages or to only wait a certain time for messages respectively.
</para>
<para>
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 <link linkend="g-async-queue-lock"><function>g_async_queue_lock()</function></link> and release it with
<link linkend="g-async-queue-unlock"><function>g_async_queue_unlock()</function></link>) 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)
</para>
</refsect1>

<refsect1 id="glib-Asynchronous-Queues.details" role="details">
<title role="details.title">Details</title>
<refsect2 id="GAsyncQueue" role="struct">
<title>GAsyncQueue</title>
<indexterm zone="GAsyncQueue"><primary sortas="AsyncQueue">GAsyncQueue</primary></indexterm><programlisting>typedef struct _GAsyncQueue GAsyncQueue;</programlisting>
<para>
The <link linkend="GAsyncQueue"><type>GAsyncQueue</type></link> struct is an opaque data structure, which represents
an asynchronous queue. It should only be accessed through the
<function>g_async_queue_*</function> functions.
</para></refsect2>
<refsect2 id="g-async-queue-new" role="function">
<title>g_async_queue_new ()</title>
<indexterm zone="g-async-queue-new"><primary sortas="async_queue_new">g_async_queue_new</primary></indexterm><programlisting><link linkend="GAsyncQueue">GAsyncQueue</link>*        g_async_queue_new                   (void);</programlisting>
<para>
Creates a new asynchronous queue with the initial reference count of 1.</para>
<variablelist role="params">
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> the new <link linkend="GAsyncQueue"><type>GAsyncQueue</type></link>.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="g-async-queue-new-full" role="function" condition="since:2.16">
<title>g_async_queue_new_full ()</title>
<indexterm zone="g-async-queue-new-full" role="2.16"><primary sortas="async_queue_new_full">g_async_queue_new_full</primary></indexterm><programlisting><link linkend="GAsyncQueue">GAsyncQueue</link>*        g_async_queue_new_full              (<link linkend="GDestroyNotify">GDestroyNotify</link> item_free_func);</programlisting>
<para>
Creates a new asynchronous queue with an initial reference count of 1 and
sets up a destroy notify function that is used to free any remaining
queue items when the queue is destroyed after the final unref.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>item_free_func</parameter>&#160;:</term>
<listitem><simpara> function to free queue elements
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> the new <link linkend="GAsyncQueue"><type>GAsyncQueue</type></link>.

</simpara></listitem></varlistentry>
</variablelist><para role="since">Since 2.16</para></refsect2>
<refsect2 id="g-async-queue-ref" role="function">
<title>g_async_queue_ref ()</title>
<indexterm zone="g-async-queue-ref"><primary sortas="async_queue_ref">g_async_queue_ref</primary></indexterm><programlisting><link linkend="GAsyncQueue">GAsyncQueue</link>*        g_async_queue_ref                   (<link linkend="GAsyncQueue">GAsyncQueue</link> *queue);</programlisting>
<para>
Increases the reference count of the asynchronous <parameter>queue</parameter> by 1. You
do not need to hold the lock to call this function.</para>
<variablelist role="params">
<varlistentry><term><parameter>queue</parameter>&#160;:</term>
<listitem><simpara> a <link linkend="GAsyncQueue"><type>GAsyncQueue</type></link>.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> the <parameter>queue</parameter> that was passed in (since 2.6)
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="g-async-queue-unref" role="function">
<title>g_async_queue_unref ()</title>
<indexterm zone="g-async-queue-unref"><primary sortas="async_queue_unref">g_async_queue_unref</primary></indexterm><programlisting><link linkend="void">void</link>                g_async_queue_unref                 (<link linkend="GAsyncQueue">GAsyncQueue</link> *queue);</programlisting>
<para>
Decreases the reference count of the asynchronous <parameter>queue</parameter> by 1. If
the reference count went to 0, the <parameter>queue</parameter> will be destroyed and the
memory allocated will be freed. So you are not allowed to use the
<parameter>queue</parameter> afterwards, as it might have disappeared. You do not need to
hold the lock to call this function.</para>
<variablelist role="params">
<varlistentry><term><parameter>queue</parameter>&#160;:</term>
<listitem><simpara> a <link linkend="GAsyncQueue"><type>GAsyncQueue</type></link>.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="g-async-queue-push" role="function">
<title>g_async_queue_push ()</title>
<indexterm zone="g-async-queue-push"><primary sortas="async_queue_push">g_async_queue_push</primary></indexterm><programlisting><link linkend="void">void</link>                g_async_queue_push                  (<link linkend="GAsyncQueue">GAsyncQueue</link> *queue,
                                                         <link linkend="gpointer">gpointer</link> data);</programlisting>
<para>
Pushes the <parameter>data</parameter> into the <parameter>queue</parameter>. <parameter>data</parameter> must not be <link linkend="NULL--CAPS"><literal>NULL</literal></link>.</para>
<variablelist role="params">
<varlistentry><term><parameter>queue</parameter>&#160;:</term>
<listitem><simpara> a <link linkend="GAsyncQueue"><type>GAsyncQueue</type></link>.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>data</parameter>&#160;:</term>
<listitem><simpara> <parameter>data</parameter> to push into the <parameter>queue</parameter>.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="g-async-queue-push-sorted" role="function" condition="since:2.10">
<title>g_async_queue_push_sorted ()</title>
<indexterm zone="g-async-queue-push-sorted" role="2.10"><primary sortas="async_queue_push_sorted">g_async_queue_push_sorted</primary></indexterm><programlisting><link linkend="void">void</link>                g_async_queue_push_sorted           (<link linkend="GAsyncQueue">GAsyncQueue</link> *queue,
                                                         <link linkend="gpointer">gpointer</link> data,
                                                         <link linkend="GCompareDataFunc">GCompareDataFunc</link> func,
                                                         <link linkend="gpointer">gpointer</link> user_data);</programlisting>
<para>
Inserts <parameter>data</parameter> into <parameter>queue</parameter> using <parameter>func</parameter> to determine the new
position. 
</para>
<para>
This function requires that the <parameter>queue</parameter> is sorted before pushing on
new elements.
</para>
<para>
This function will lock <parameter>queue</parameter> before it sorts the queue and unlock
it when it is finished.
</para>
<para>
For an example of <parameter>func</parameter> see <link linkend="g-async-queue-sort"><function>g_async_queue_sort()</function></link>.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>queue</parameter>&#160;:</term>
<listitem><simpara> a <link linkend="GAsyncQueue"><type>GAsyncQueue</type></link>
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>data</parameter>&#160;:</term>
<listitem><simpara> the <parameter>data</parameter> to push into the <parameter>queue</parameter>
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>func</parameter>&#160;:</term>
<listitem><simpara> the <link linkend="GCompareDataFunc"><type>GCompareDataFunc</type></link> is used to sort <parameter>queue</parameter>. This function
    is passed two elements of the <parameter>queue</parameter>. The function should return
    0 if they are equal, a negative value if the first element
    should be higher in the <parameter>queue</parameter> or a positive value if the first
    element should be lower in the <parameter>queue</parameter> than the second element.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>user_data</parameter>&#160;:</term>
<listitem><simpara> user data passed to <parameter>func</parameter>.
</simpara></listitem></varlistentry>
</variablelist><para role="since">Since 2.10</para></refsect2>
<refsect2 id="g-async-queue-pop" role="function">
<title>g_async_queue_pop ()</title>
<indexterm zone="g-async-queue-pop"><primary sortas="async_queue_pop">g_async_queue_pop</primary></indexterm><programlisting><link linkend="gpointer">gpointer</link>            g_async_queue_pop                   (<link linkend="GAsyncQueue">GAsyncQueue</link> *queue);</programlisting>
<para>
Pops data from the <parameter>queue</parameter>. This function blocks until data become
available.</para>
<variablelist role="params">
<varlistentry><term><parameter>queue</parameter>&#160;:</term>
<listitem><simpara> a <link linkend="GAsyncQueue"><type>GAsyncQueue</type></link>.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> data from the queue.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="g-async-queue-try-pop" role="function">
<title>g_async_queue_try_pop ()</title>
<indexterm zone="g-async-queue-try-pop"><primary sortas="async_queue_try_pop">g_async_queue_try_pop</primary></indexterm><programlisting><link linkend="gpointer">gpointer</link>            g_async_queue_try_pop               (<link linkend="GAsyncQueue">GAsyncQueue</link> *queue);</programlisting>
<para>
Tries to pop data from the <parameter>queue</parameter>. If no data is available, <link linkend="NULL--CAPS"><literal>NULL</literal></link> is
returned.</para>
<variablelist role="params">
<varlistentry><term><parameter>queue</parameter>&#160;:</term>
<listitem><simpara> a <link linkend="GAsyncQueue"><type>GAsyncQueue</type></link>.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> data from the queue or <link linkend="NULL--CAPS"><literal>NULL</literal></link>, when no data is
available immediately.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="g-async-queue-timed-pop" role="function">
<title>g_async_queue_timed_pop ()</title>
<indexterm zone="g-async-queue-timed-pop"><primary sortas="async_queue_timed_pop">g_async_queue_timed_pop</primary></indexterm><programlisting><link linkend="gpointer">gpointer</link>            g_async_queue_timed_pop             (<link linkend="GAsyncQueue">GAsyncQueue</link> *queue,
                                                         <link linkend="GTimeVal">GTimeVal</link> *end_time);</programlisting>
<para>
Pops data from the <parameter>queue</parameter>. If no data is received before <parameter>end_time</parameter>,
<link linkend="NULL--CAPS"><literal>NULL</literal></link> is returned.
</para>
<para>
To easily calculate <parameter>end_time</parameter> a combination of <link linkend="g-get-current-time"><function>g_get_current_time()</function></link>
and <link linkend="g-time-val-add"><function>g_time_val_add()</function></link> can be used.</para>
<variablelist role="params">
<varlistentry><term><parameter>queue</parameter>&#160;:</term>
<listitem><simpara> a <link linkend="GAsyncQueue"><type>GAsyncQueue</type></link>.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>end_time</parameter>&#160;:</term>
<listitem><simpara> a <link linkend="GTimeVal"><type>GTimeVal</type></link>, determining the final time.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> data from the queue or <link linkend="NULL--CAPS"><literal>NULL</literal></link>, when no data is
received before <parameter>end_time</parameter>.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="g-async-queue-length" role="function">
<title>g_async_queue_length ()</title>
<indexterm zone="g-async-queue-length"><primary sortas="async_queue_length">g_async_queue_length</primary></indexterm><programlisting><link linkend="gint">gint</link>                g_async_queue_length                (<link linkend="GAsyncQueue">GAsyncQueue</link> *queue);</programlisting>
<para>
Returns the length of the queue, negative values mean waiting
threads, positive values mean available entries in the
<parameter>queue</parameter>. 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.</para>
<variablelist role="params">
<varlistentry><term><parameter>queue</parameter>&#160;:</term>
<listitem><simpara> a <link linkend="GAsyncQueue"><type>GAsyncQueue</type></link>.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> the length of the <parameter>queue</parameter>.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="g-async-queue-sort" role="function" condition="since:2.10">
<title>g_async_queue_sort ()</title>
<indexterm zone="g-async-queue-sort" role="2.10"><primary sortas="async_queue_sort">g_async_queue_sort</primary></indexterm><programlisting><link linkend="void">void</link>                g_async_queue_sort                  (<link linkend="GAsyncQueue">GAsyncQueue</link> *queue,
                                                         <link linkend="GCompareDataFunc">GCompareDataFunc</link> func,
                                                         <link linkend="gpointer">gpointer</link> user_data);</programlisting>
<para>
Sorts <parameter>queue</parameter> using <parameter>func</parameter>. 
</para>
<para>
This function will lock <parameter>queue</parameter> before it sorts the queue and unlock
it when it is finished.
</para>
<para>
If you were sorting a list of priority numbers to make sure the
lowest priority would be at the top of the queue, you could use:
<informalexample><programlisting>
 gint32 id1;
 gint32 id2;
  
 id1 = GPOINTER_TO_INT (element1);
 id2 = GPOINTER_TO_INT (element2);
  
 return (id1 &gt; id2 ? +1 : id1 == id2 ? 0 : -1);
</programlisting></informalexample></para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>queue</parameter>&#160;:</term>
<listitem><simpara> a <link linkend="GAsyncQueue"><type>GAsyncQueue</type></link>
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>func</parameter>&#160;:</term>
<listitem><simpara> the <link linkend="GCompareDataFunc"><type>GCompareDataFunc</type></link> is used to sort <parameter>queue</parameter>. This
    function is passed two elements of the <parameter>queue</parameter>. The function
    should return 0 if they are equal, a negative value if the
    first element should be higher in the <parameter>queue</parameter> or a positive
    value if the first element should be lower in the <parameter>queue</parameter> than
    the second element. 
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>user_data</parameter>&#160;:</term>
<listitem><simpara> user data passed to <parameter>func</parameter>
</simpara></listitem></varlistentry>
</variablelist><para role="since">Since 2.10</para></refsect2>
<refsect2 id="g-async-queue-lock" role="function">
<title>g_async_queue_lock ()</title>
<indexterm zone="g-async-queue-lock"><primary sortas="async_queue_lock">g_async_queue_lock</primary></indexterm><programlisting><link linkend="void">void</link>                g_async_queue_lock                  (<link linkend="GAsyncQueue">GAsyncQueue</link> *queue);</programlisting>
<para>
Acquires the <parameter>queue</parameter>'s lock. After that you can only call the
<function>g_async_queue_*<link linkend="unlocked"><function>_unlocked()</function></link></function> function variants on that
<parameter>queue</parameter>. Otherwise it will deadlock.</para>
<variablelist role="params">
<varlistentry><term><parameter>queue</parameter>&#160;:</term>
<listitem><simpara> a <link linkend="GAsyncQueue"><type>GAsyncQueue</type></link>.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="g-async-queue-unlock" role="function">
<title>g_async_queue_unlock ()</title>
<indexterm zone="g-async-queue-unlock"><primary sortas="async_queue_unlock">g_async_queue_unlock</primary></indexterm><programlisting><link linkend="void">void</link>                g_async_queue_unlock                (<link linkend="GAsyncQueue">GAsyncQueue</link> *queue);</programlisting>
<para>
Releases the queue's lock.</para>
<variablelist role="params">
<varlistentry><term><parameter>queue</parameter>&#160;:</term>
<listitem><simpara> a <link linkend="GAsyncQueue"><type>GAsyncQueue</type></link>.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="g-async-queue-ref-unlocked" role="function" condition="deprecated:">
<title>g_async_queue_ref_unlocked ()</title>
<indexterm zone="g-async-queue-ref-unlocked" role="deprecated"><primary sortas="async_queue_ref_unlocked">g_async_queue_ref_unlocked</primary></indexterm><programlisting><link linkend="void">void</link>                g_async_queue_ref_unlocked          (<link linkend="GAsyncQueue">GAsyncQueue</link> *queue);</programlisting>
<warning><para><literal>g_async_queue_ref_unlocked</literal> is deprecated and should not be used in newly-written code.</para></warning>
<para>
Increases the reference count of the asynchronous <parameter>queue</parameter> by 1.
</para>
<para>
<parameter>Deprecated</parameter>: Since 2.8, reference counting is done atomically
so <link linkend="g-async-queue-ref"><function>g_async_queue_ref()</function></link> can be used regardless of the <parameter>queue</parameter>'s
lock.</para>
<variablelist role="params">
<varlistentry><term><parameter>queue</parameter>&#160;:</term>
<listitem><simpara> a <link linkend="GAsyncQueue"><type>GAsyncQueue</type></link>.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="g-async-queue-unref-and-unlock" role="function" condition="deprecated:">
<title>g_async_queue_unref_and_unlock ()</title>
<indexterm zone="g-async-queue-unref-and-unlock" role="deprecated"><primary sortas="async_queue_unref_and_unlock">g_async_queue_unref_and_unlock</primary></indexterm><programlisting><link linkend="void">void</link>                g_async_queue_unref_and_unlock      (<link linkend="GAsyncQueue">GAsyncQueue</link> *queue);</programlisting>
<warning><para><literal>g_async_queue_unref_and_unlock</literal> is deprecated and should not be used in newly-written code.</para></warning>
<para>
Decreases the reference count of the asynchronous <parameter>queue</parameter> by 1 and
releases the lock. This function must be called while holding the
<parameter>queue</parameter>'s lock. If the reference count went to 0, the <parameter>queue</parameter> will be
destroyed and the memory allocated will be freed.
</para>
<para>
<parameter>Deprecated</parameter>: Since 2.8, reference counting is done atomically
so <link linkend="g-async-queue-unref"><function>g_async_queue_unref()</function></link> can be used regardless of the <parameter>queue</parameter>'s
lock.</para>
<variablelist role="params">
<varlistentry><term><parameter>queue</parameter>&#160;:</term>
<listitem><simpara> a <link linkend="GAsyncQueue"><type>GAsyncQueue</type></link>.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="g-async-queue-push-unlocked" role="function">
<title>g_async_queue_push_unlocked ()</title>
<indexterm zone="g-async-queue-push-unlocked"><primary sortas="async_queue_push_unlocked">g_async_queue_push_unlocked</primary></indexterm><programlisting><link linkend="void">void</link>                g_async_queue_push_unlocked         (<link linkend="GAsyncQueue">GAsyncQueue</link> *queue,
                                                         <link linkend="gpointer">gpointer</link> data);</programlisting>
<para>
Pushes the <parameter>data</parameter> into the <parameter>queue</parameter>. <parameter>data</parameter> must not be <link linkend="NULL--CAPS"><literal>NULL</literal></link>. This
function must be called while holding the <parameter>queue</parameter>'s lock.</para>
<variablelist role="params">
<varlistentry><term><parameter>queue</parameter>&#160;:</term>
<listitem><simpara> a <link linkend="GAsyncQueue"><type>GAsyncQueue</type></link>.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>data</parameter>&#160;:</term>
<listitem><simpara> <parameter>data</parameter> to push into the <parameter>queue</parameter>.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="g-async-queue-push-sorted-unlocked" role="function" condition="since:2.10">
<title>g_async_queue_push_sorted_unlocked ()</title>
<indexterm zone="g-async-queue-push-sorted-unlocked" role="2.10"><primary sortas="async_queue_push_sorted_unlocked">g_async_queue_push_sorted_unlocked</primary></indexterm><programlisting><link linkend="void">void</link>                g_async_queue_push_sorted_unlocked  (<link linkend="GAsyncQueue">GAsyncQueue</link> *queue,
                                                         <link linkend="gpointer">gpointer</link> data,
                                                         <link linkend="GCompareDataFunc">GCompareDataFunc</link> func,
                                                         <link linkend="gpointer">gpointer</link> user_data);</programlisting>
<para>
Inserts <parameter>data</parameter> into <parameter>queue</parameter> using <parameter>func</parameter> to determine the new
position.
</para>
<para>
This function requires that the <parameter>queue</parameter> is sorted before pushing on
new elements.
</para>
<para>
This function is called while holding the <parameter>queue</parameter>'s lock.
</para>
<para>
For an example of <parameter>func</parameter> see <link linkend="g-async-queue-sort"><function>g_async_queue_sort()</function></link>.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>queue</parameter>&#160;:</term>
<listitem><simpara> a <link linkend="GAsyncQueue"><type>GAsyncQueue</type></link>
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>data</parameter>&#160;:</term>
<listitem><simpara> the <parameter>data</parameter> to push into the <parameter>queue</parameter>
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>func</parameter>&#160;:</term>
<listitem><simpara> the <link linkend="GCompareDataFunc"><type>GCompareDataFunc</type></link> is used to sort <parameter>queue</parameter>. This function
    is passed two elements of the <parameter>queue</parameter>. The function should return
    0 if they are equal, a negative value if the first element
    should be higher in the <parameter>queue</parameter> or a positive value if the first
    element should be lower in the <parameter>queue</parameter> than the second element.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>user_data</parameter>&#160;:</term>
<listitem><simpara> user data passed to <parameter>func</parameter>.
</simpara></listitem></varlistentry>
</variablelist><para role="since">Since 2.10</para></refsect2>
<refsect2 id="g-async-queue-pop-unlocked" role="function">
<title>g_async_queue_pop_unlocked ()</title>
<indexterm zone="g-async-queue-pop-unlocked"><primary sortas="async_queue_pop_unlocked">g_async_queue_pop_unlocked</primary></indexterm><programlisting><link linkend="gpointer">gpointer</link>            g_async_queue_pop_unlocked          (<link linkend="GAsyncQueue">GAsyncQueue</link> *queue);</programlisting>
<para>
Pops data from the <parameter>queue</parameter>. This function blocks until data become
available. This function must be called while holding the <parameter>queue</parameter>'s
lock.</para>
<variablelist role="params">
<varlistentry><term><parameter>queue</parameter>&#160;:</term>
<listitem><simpara> a <link linkend="GAsyncQueue"><type>GAsyncQueue</type></link>.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> data from the queue.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="g-async-queue-try-pop-unlocked" role="function">
<title>g_async_queue_try_pop_unlocked ()</title>
<indexterm zone="g-async-queue-try-pop-unlocked"><primary sortas="async_queue_try_pop_unlocked">g_async_queue_try_pop_unlocked</primary></indexterm><programlisting><link linkend="gpointer">gpointer</link>            g_async_queue_try_pop_unlocked      (<link linkend="GAsyncQueue">GAsyncQueue</link> *queue);</programlisting>
<para>
Tries to pop data from the <parameter>queue</parameter>. If no data is available, <link linkend="NULL--CAPS"><literal>NULL</literal></link> is
returned. This function must be called while holding the <parameter>queue</parameter>'s
lock.</para>
<variablelist role="params">
<varlistentry><term><parameter>queue</parameter>&#160;:</term>
<listitem><simpara> a <link linkend="GAsyncQueue"><type>GAsyncQueue</type></link>.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> data from the queue or <link linkend="NULL--CAPS"><literal>NULL</literal></link>, when no data is
available immediately.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="g-async-queue-timed-pop-unlocked" role="function">
<title>g_async_queue_timed_pop_unlocked ()</title>
<indexterm zone="g-async-queue-timed-pop-unlocked"><primary sortas="async_queue_timed_pop_unlocked">g_async_queue_timed_pop_unlocked</primary></indexterm><programlisting><link linkend="gpointer">gpointer</link>            g_async_queue_timed_pop_unlocked    (<link linkend="GAsyncQueue">GAsyncQueue</link> *queue,
                                                         <link linkend="GTimeVal">GTimeVal</link> *end_time);</programlisting>
<para>
Pops data from the <parameter>queue</parameter>. If no data is received before <parameter>end_time</parameter>,
<link linkend="NULL--CAPS"><literal>NULL</literal></link> is returned. This function must be called while holding the
<parameter>queue</parameter>'s lock.
</para>
<para>
To easily calculate <parameter>end_time</parameter> a combination of <link linkend="g-get-current-time"><function>g_get_current_time()</function></link>
and <link linkend="g-time-val-add"><function>g_time_val_add()</function></link> can be used.</para>
<variablelist role="params">
<varlistentry><term><parameter>queue</parameter>&#160;:</term>
<listitem><simpara> a <link linkend="GAsyncQueue"><type>GAsyncQueue</type></link>.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>end_time</parameter>&#160;:</term>
<listitem><simpara> a <link linkend="GTimeVal"><type>GTimeVal</type></link>, determining the final time.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> data from the queue or <link linkend="NULL--CAPS"><literal>NULL</literal></link>, when no data is
received before <parameter>end_time</parameter>.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="g-async-queue-length-unlocked" role="function">
<title>g_async_queue_length_unlocked ()</title>
<indexterm zone="g-async-queue-length-unlocked"><primary sortas="async_queue_length_unlocked">g_async_queue_length_unlocked</primary></indexterm><programlisting><link linkend="gint">gint</link>                g_async_queue_length_unlocked       (<link linkend="GAsyncQueue">GAsyncQueue</link> *queue);</programlisting>
<para>
Returns the length of the queue, negative values mean waiting
threads, positive values mean available entries in the
<parameter>queue</parameter>. 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 <parameter>queue</parameter>'s
lock.</para>
<variablelist role="params">
<varlistentry><term><parameter>queue</parameter>&#160;:</term>
<listitem><simpara> a <link linkend="GAsyncQueue"><type>GAsyncQueue</type></link>.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara> the length of the <parameter>queue</parameter>.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2 id="g-async-queue-sort-unlocked" role="function" condition="since:2.10">
<title>g_async_queue_sort_unlocked ()</title>
<indexterm zone="g-async-queue-sort-unlocked" role="2.10"><primary sortas="async_queue_sort_unlocked">g_async_queue_sort_unlocked</primary></indexterm><programlisting><link linkend="void">void</link>                g_async_queue_sort_unlocked         (<link linkend="GAsyncQueue">GAsyncQueue</link> *queue,
                                                         <link linkend="GCompareDataFunc">GCompareDataFunc</link> func,
                                                         <link linkend="gpointer">gpointer</link> user_data);</programlisting>
<para>
Sorts <parameter>queue</parameter> using <parameter>func</parameter>. 
</para>
<para>
This function is called while holding the <parameter>queue</parameter>'s lock.</para>
<para>
</para><variablelist role="params">
<varlistentry><term><parameter>queue</parameter>&#160;:</term>
<listitem><simpara> a <link linkend="GAsyncQueue"><type>GAsyncQueue</type></link>
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>func</parameter>&#160;:</term>
<listitem><simpara> the <link linkend="GCompareDataFunc"><type>GCompareDataFunc</type></link> is used to sort <parameter>queue</parameter>. This
    function is passed two elements of the <parameter>queue</parameter>. The function
    should return 0 if they are equal, a negative value if the
    first element should be higher in the <parameter>queue</parameter> or a positive
    value if the first element should be lower in the <parameter>queue</parameter> than
    the second element. 
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>user_data</parameter>&#160;:</term>
<listitem><simpara> user data passed to <parameter>func</parameter>
</simpara></listitem></varlistentry>
</variablelist><para role="since">Since 2.10</para></refsect2>

</refsect1>




</refentry>
