docs/reference/glib/html/glib-Asynchronous-Queues.html

   1 <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
   2 <html>
   3 <head>
   4 <meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
   5 <title>Asynchronous Queues</title>
   6 <meta name="generator" content="DocBook XSL Stylesheets V1.76.1">
   7 <link rel="home" href="index.html" title="GLib Reference Manual">
   8 <link rel="up" href="glib-core.html" title="GLib Core Application Support">
   9 <link rel="prev" href="glib-Thread-Pools.html" title="Thread Pools">
  10 <link rel="next" href="glib-Dynamic-Loading-of-Modules.html" title="Dynamic Loading of Modules">
  11 <meta name="generator" content="GTK-Doc V1.18 (XML mode)">
  12 <link rel="stylesheet" href="style.css" type="text/css">
  13 </head>
  14 <body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
  15 <table class="navigation" id="top" width="100%" summary="Navigation header" cellpadding="2" cellspacing="2">
  16 <tr valign="middle">
  17 <td><a accesskey="p" href="glib-Thread-Pools.html"><img src="left.png" width="24" height="24" border="0" alt="Prev"></a></td>
  18 <td><a accesskey="u" href="glib-core.html"><img src="up.png" width="24" height="24" border="0" alt="Up"></a></td>
  19 <td><a accesskey="h" href="index.html"><img src="home.png" width="24" height="24" border="0" alt="Home"></a></td>
  20 <th width="100%" align="center">GLib Reference Manual</th>
  21 <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>
  22 </tr>
  23 <tr><td colspan="5" class="shortcuts">
  24 <a href="#glib-Asynchronous-Queues.synopsis" class="shortcut">Top</a>
  25                    |
  26                   <a href="#glib-Asynchronous-Queues.description" class="shortcut">Description</a>
  27 </td></tr>
  28 </table>
  29 <div class="refentry">
  30 <a name="glib-Asynchronous-Queues"></a><div class="titlepage"></div>
  31 <div class="refnamediv"><table width="100%"><tr>
  32 <td valign="top">
  33 <h2><span class="refentrytitle"><a name="glib-Asynchronous-Queues.top_of_page"></a>Asynchronous Queues</span></h2>
  34 <p>Asynchronous Queues — asynchronous communication between threads</p>
  35 </td>
  36 <td valign="top" align="right"></td>
  37 </tr></table></div>
  38 <div class="refsynopsisdiv">
  39 <a name="glib-Asynchronous-Queues.synopsis"></a><h2>Synopsis</h2>
  40 <pre class="synopsis">
  41 #include &lt;glib.h&gt;
  42
  43                     <a class="link" href="glib-Asynchronous-Queues.html#GAsyncQueue" title="GAsyncQueue">GAsyncQueue</a>;
  44 <a class="link" href="glib-Asynchronous-Queues.html#GAsyncQueue" title="GAsyncQueue"><span class="returnvalue">GAsyncQueue</span></a> *       <a class="link" href="glib-Asynchronous-Queues.html#g-async-queue-new" title="g_async_queue_new ()">g_async_queue_new</a>                   (<em class="parameter"><code><span class="type">void</span></code></em>);
  45 <a class="link" href="glib-Asynchronous-Queues.html#GAsyncQueue" title="GAsyncQueue"><span class="returnvalue">GAsyncQueue</span></a> *       <a class="link" href="glib-Asynchronous-Queues.html#g-async-queue-new-full" title="g_async_queue_new_full ()">g_async_queue_new_full</a>              (<em class="parameter"><code><a class="link" href="glib-Datasets.html#GDestroyNotify" title="GDestroyNotify ()"><span class="type">GDestroyNotify</span></a> item_free_func</code></em>);
  46 <a class="link" href="glib-Asynchronous-Queues.html#GAsyncQueue" title="GAsyncQueue"><span class="returnvalue">GAsyncQueue</span></a> *       <a class="link" href="glib-Asynchronous-Queues.html#g-async-queue-ref" title="g_async_queue_ref ()">g_async_queue_ref</a>                   (<em class="parameter"><code><a class="link" href="glib-Asynchronous-Queues.html#GAsyncQueue" title="GAsyncQueue"><span class="type">GAsyncQueue</span></a> *queue</code></em>);
  47 <span class="returnvalue">void</span>                <a class="link" href="glib-Asynchronous-Queues.html#g-async-queue-unref" title="g_async_queue_unref ()">g_async_queue_unref</a>                 (<em class="parameter"><code><a class="link" href="glib-Asynchronous-Queues.html#GAsyncQueue" title="GAsyncQueue"><span class="type">GAsyncQueue</span></a> *queue</code></em>);
  48 <span class="returnvalue">void</span>                <a class="link" href="glib-Asynchronous-Queues.html#g-async-queue-push" title="g_async_queue_push ()">g_async_queue_push</a>                  (<em class="parameter"><code><a class="link" href="glib-Asynchronous-Queues.html#GAsyncQueue" title="GAsyncQueue"><span class="type">GAsyncQueue</span></a> *queue</code></em>,
  49                                                          <em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gpointer" title="gpointer"><span class="type">gpointer</span></a> data</code></em>);
  50 <span class="returnvalue">void</span>                <a class="link" href="glib-Asynchronous-Queues.html#g-async-queue-push-sorted" title="g_async_queue_push_sorted ()">g_async_queue_push_sorted</a>           (<em class="parameter"><code><a class="link" href="glib-Asynchronous-Queues.html#GAsyncQueue" title="GAsyncQueue"><span class="type">GAsyncQueue</span></a> *queue</code></em>,
  51                                                          <em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gpointer" title="gpointer"><span class="type">gpointer</span></a> data</code></em>,
  52                                                          <em class="parameter"><code><a class="link" href="glib-Doubly-Linked-Lists.html#GCompareDataFunc" title="GCompareDataFunc ()"><span class="type">GCompareDataFunc</span></a> func</code></em>,
  53                                                          <em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gpointer" title="gpointer"><span class="type">gpointer</span></a> user_data</code></em>);
  54 <a class="link" href="glib-Basic-Types.html#gpointer" title="gpointer"><span class="returnvalue">gpointer</span></a>            <a class="link" href="glib-Asynchronous-Queues.html#g-async-queue-pop" title="g_async_queue_pop ()">g_async_queue_pop</a>                   (<em class="parameter"><code><a class="link" href="glib-Asynchronous-Queues.html#GAsyncQueue" title="GAsyncQueue"><span class="type">GAsyncQueue</span></a> *queue</code></em>);
  55 <a class="link" href="glib-Basic-Types.html#gpointer" title="gpointer"><span class="returnvalue">gpointer</span></a>            <a class="link" href="glib-Asynchronous-Queues.html#g-async-queue-try-pop" title="g_async_queue_try_pop ()">g_async_queue_try_pop</a>               (<em class="parameter"><code><a class="link" href="glib-Asynchronous-Queues.html#GAsyncQueue" title="GAsyncQueue"><span class="type">GAsyncQueue</span></a> *queue</code></em>);
  56 <a class="link" href="glib-Basic-Types.html#gpointer" title="gpointer"><span class="returnvalue">gpointer</span></a>            <a class="link" href="glib-Asynchronous-Queues.html#g-async-queue-timeout-pop" title="g_async_queue_timeout_pop ()">g_async_queue_timeout_pop</a>           (<em class="parameter"><code><a class="link" href="glib-Asynchronous-Queues.html#GAsyncQueue" title="GAsyncQueue"><span class="type">GAsyncQueue</span></a> *queue</code></em>,
  57                                                          <em class="parameter"><code><a class="link" href="glib-Basic-Types.html#guint64" title="guint64"><span class="type">guint64</span></a> timeout</code></em>);
  58 <a class="link" href="glib-Basic-Types.html#gint" title="gint"><span class="returnvalue">gint</span></a>                <a class="link" href="glib-Asynchronous-Queues.html#g-async-queue-length" title="g_async_queue_length ()">g_async_queue_length</a>                (<em class="parameter"><code><a class="link" href="glib-Asynchronous-Queues.html#GAsyncQueue" title="GAsyncQueue"><span class="type">GAsyncQueue</span></a> *queue</code></em>);
  59 <span class="returnvalue">void</span>                <a class="link" href="glib-Asynchronous-Queues.html#g-async-queue-sort" title="g_async_queue_sort ()">g_async_queue_sort</a>                  (<em class="parameter"><code><a class="link" href="glib-Asynchronous-Queues.html#GAsyncQueue" title="GAsyncQueue"><span class="type">GAsyncQueue</span></a> *queue</code></em>,
  60                                                          <em class="parameter"><code><a class="link" href="glib-Doubly-Linked-Lists.html#GCompareDataFunc" title="GCompareDataFunc ()"><span class="type">GCompareDataFunc</span></a> func</code></em>,
  61                                                          <em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gpointer" title="gpointer"><span class="type">gpointer</span></a> user_data</code></em>);
  62
  63 <span class="returnvalue">void</span>                <a class="link" href="glib-Asynchronous-Queues.html#g-async-queue-lock" title="g_async_queue_lock ()">g_async_queue_lock</a>                  (<em class="parameter"><code><a class="link" href="glib-Asynchronous-Queues.html#GAsyncQueue" title="GAsyncQueue"><span class="type">GAsyncQueue</span></a> *queue</code></em>);
  64 <span class="returnvalue">void</span>                <a class="link" href="glib-Asynchronous-Queues.html#g-async-queue-unlock" title="g_async_queue_unlock ()">g_async_queue_unlock</a>                (<em class="parameter"><code><a class="link" href="glib-Asynchronous-Queues.html#GAsyncQueue" title="GAsyncQueue"><span class="type">GAsyncQueue</span></a> *queue</code></em>);
  65 <span class="returnvalue">void</span>                <a class="link" href="glib-Asynchronous-Queues.html#g-async-queue-ref-unlocked" title="g_async_queue_ref_unlocked ()">g_async_queue_ref_unlocked</a>          (<em class="parameter"><code><a class="link" href="glib-Asynchronous-Queues.html#GAsyncQueue" title="GAsyncQueue"><span class="type">GAsyncQueue</span></a> *queue</code></em>);
  66 <span class="returnvalue">void</span>                <a class="link" href="glib-Asynchronous-Queues.html#g-async-queue-unref-and-unlock" title="g_async_queue_unref_and_unlock ()">g_async_queue_unref_and_unlock</a>      (<em class="parameter"><code><a class="link" href="glib-Asynchronous-Queues.html#GAsyncQueue" title="GAsyncQueue"><span class="type">GAsyncQueue</span></a> *queue</code></em>);
  67 <span class="returnvalue">void</span>                <a class="link" href="glib-Asynchronous-Queues.html#g-async-queue-push-unlocked" title="g_async_queue_push_unlocked ()">g_async_queue_push_unlocked</a>         (<em class="parameter"><code><a class="link" href="glib-Asynchronous-Queues.html#GAsyncQueue" title="GAsyncQueue"><span class="type">GAsyncQueue</span></a> *queue</code></em>,
  68                                                          <em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gpointer" title="gpointer"><span class="type">gpointer</span></a> data</code></em>);
  69 <span class="returnvalue">void</span>                <a class="link" href="glib-Asynchronous-Queues.html#g-async-queue-push-sorted-unlocked" title="g_async_queue_push_sorted_unlocked ()">g_async_queue_push_sorted_unlocked</a>  (<em class="parameter"><code><a class="link" href="glib-Asynchronous-Queues.html#GAsyncQueue" title="GAsyncQueue"><span class="type">GAsyncQueue</span></a> *queue</code></em>,
  70                                                          <em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gpointer" title="gpointer"><span class="type">gpointer</span></a> data</code></em>,
  71                                                          <em class="parameter"><code><a class="link" href="glib-Doubly-Linked-Lists.html#GCompareDataFunc" title="GCompareDataFunc ()"><span class="type">GCompareDataFunc</span></a> func</code></em>,
  72                                                          <em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gpointer" title="gpointer"><span class="type">gpointer</span></a> user_data</code></em>);
  73 <a class="link" href="glib-Basic-Types.html#gpointer" title="gpointer"><span class="returnvalue">gpointer</span></a>            <a class="link" href="glib-Asynchronous-Queues.html#g-async-queue-pop-unlocked" title="g_async_queue_pop_unlocked ()">g_async_queue_pop_unlocked</a>          (<em class="parameter"><code><a class="link" href="glib-Asynchronous-Queues.html#GAsyncQueue" title="GAsyncQueue"><span class="type">GAsyncQueue</span></a> *queue</code></em>);
  74 <a class="link" href="glib-Basic-Types.html#gpointer" title="gpointer"><span class="returnvalue">gpointer</span></a>            <a class="link" href="glib-Asynchronous-Queues.html#g-async-queue-try-pop-unlocked" title="g_async_queue_try_pop_unlocked ()">g_async_queue_try_pop_unlocked</a>      (<em class="parameter"><code><a class="link" href="glib-Asynchronous-Queues.html#GAsyncQueue" title="GAsyncQueue"><span class="type">GAsyncQueue</span></a> *queue</code></em>);
  75 <a class="link" href="glib-Basic-Types.html#gpointer" title="gpointer"><span class="returnvalue">gpointer</span></a>            <a class="link" href="glib-Asynchronous-Queues.html#g-async-queue-timeout-pop-unlocked" title="g_async_queue_timeout_pop_unlocked ()">g_async_queue_timeout_pop_unlocked</a>  (<em class="parameter"><code><a class="link" href="glib-Asynchronous-Queues.html#GAsyncQueue" title="GAsyncQueue"><span class="type">GAsyncQueue</span></a> *queue</code></em>,
  76                                                          <em class="parameter"><code><a class="link" href="glib-Basic-Types.html#guint64" title="guint64"><span class="type">guint64</span></a> timeout</code></em>);
  77 <a class="link" href="glib-Basic-Types.html#gint" title="gint"><span class="returnvalue">gint</span></a>                <a class="link" href="glib-Asynchronous-Queues.html#g-async-queue-length-unlocked" title="g_async_queue_length_unlocked ()">g_async_queue_length_unlocked</a>       (<em class="parameter"><code><a class="link" href="glib-Asynchronous-Queues.html#GAsyncQueue" title="GAsyncQueue"><span class="type">GAsyncQueue</span></a> *queue</code></em>);
  78 <span class="returnvalue">void</span>                <a class="link" href="glib-Asynchronous-Queues.html#g-async-queue-sort-unlocked" title="g_async_queue_sort_unlocked ()">g_async_queue_sort_unlocked</a>         (<em class="parameter"><code><a class="link" href="glib-Asynchronous-Queues.html#GAsyncQueue" title="GAsyncQueue"><span class="type">GAsyncQueue</span></a> *queue</code></em>,
  79                                                          <em class="parameter"><code><a class="link" href="glib-Doubly-Linked-Lists.html#GCompareDataFunc" title="GCompareDataFunc ()"><span class="type">GCompareDataFunc</span></a> func</code></em>,
  80                                                          <em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gpointer" title="gpointer"><span class="type">gpointer</span></a> user_data</code></em>);
  81
  82 <a class="link" href="glib-Basic-Types.html#gpointer" title="gpointer"><span class="returnvalue">gpointer</span></a>            <a class="link" href="glib-Asynchronous-Queues.html#g-async-queue-timed-pop" title="g_async_queue_timed_pop ()">g_async_queue_timed_pop</a>             (<em class="parameter"><code><a class="link" href="glib-Asynchronous-Queues.html#GAsyncQueue" title="GAsyncQueue"><span class="type">GAsyncQueue</span></a> *queue</code></em>,
  83                                                          <em class="parameter"><code><a class="link" href="glib-Date-and-Time-Functions.html#GTimeVal" title="struct GTimeVal"><span class="type">GTimeVal</span></a> *end_time</code></em>);
  84 <a class="link" href="glib-Basic-Types.html#gpointer" title="gpointer"><span class="returnvalue">gpointer</span></a>            <a class="link" href="glib-Asynchronous-Queues.html#g-async-queue-timed-pop-unlocked" title="g_async_queue_timed_pop_unlocked ()">g_async_queue_timed_pop_unlocked</a>    (<em class="parameter"><code><a class="link" href="glib-Asynchronous-Queues.html#GAsyncQueue" title="GAsyncQueue"><span class="type">GAsyncQueue</span></a> *queue</code></em>,
  85                                                          <em class="parameter"><code><a class="link" href="glib-Date-and-Time-Functions.html#GTimeVal" title="struct GTimeVal"><span class="type">GTimeVal</span></a> *end_time</code></em>);
  86 </pre>
  87 </div>
  88 <div class="refsect1">
  89 <a name="glib-Asynchronous-Queues.description"></a><h2>Description</h2>
  90 <p>
  91 Often you need to communicate between different threads. In general
  92 it's safer not to do this by shared memory, but by explicit message
  93 passing. These messages only make sense asynchronously for
  94 multi-threaded applications though, as a synchronous operation could
  95 as well be done in the same thread.
  96 </p>
  97 <p>
  98 Asynchronous queues are an exception from most other GLib data
  99 structures, as they can be used simultaneously from multiple threads
 100 without explicit locking and they bring their own builtin reference
 101 counting. This is because the nature of an asynchronous queue is that
 102 it will always be used by at least 2 concurrent threads.
 103 </p>
 104 <p>
 105 For using an asynchronous queue you first have to create one with
 106 <a class="link" href="glib-Asynchronous-Queues.html#g-async-queue-new" title="g_async_queue_new ()"><code class="function">g_async_queue_new()</code></a>. <a class="link" href="glib-Asynchronous-Queues.html#GAsyncQueue" title="GAsyncQueue"><span class="type">GAsyncQueue</span></a> structs are reference counted,
 107 use <a class="link" href="glib-Asynchronous-Queues.html#g-async-queue-ref" title="g_async_queue_ref ()"><code class="function">g_async_queue_ref()</code></a> and <a class="link" href="glib-Asynchronous-Queues.html#g-async-queue-unref" title="g_async_queue_unref ()"><code class="function">g_async_queue_unref()</code></a> to manage your
 108 references.
 109 </p>
 110 <p>
 111 A thread which wants to send a message to that queue simply calls
 112 <a class="link" href="glib-Asynchronous-Queues.html#g-async-queue-push" title="g_async_queue_push ()"><code class="function">g_async_queue_push()</code></a> to push the message to the queue.
 113 </p>
 114 <p>
 115 A thread which is expecting messages from an asynchronous queue
 116 simply calls <a class="link" href="glib-Asynchronous-Queues.html#g-async-queue-pop" title="g_async_queue_pop ()"><code class="function">g_async_queue_pop()</code></a> for that queue. If no message is
 117 available in the queue at that point, the thread is now put to sleep
 118 until a message arrives. The message will be removed from the queue
 119 and returned. The functions <a class="link" href="glib-Asynchronous-Queues.html#g-async-queue-try-pop" title="g_async_queue_try_pop ()"><code class="function">g_async_queue_try_pop()</code></a> and
 120 <a class="link" href="glib-Asynchronous-Queues.html#g-async-queue-timeout-pop" title="g_async_queue_timeout_pop ()"><code class="function">g_async_queue_timeout_pop()</code></a> can be used to only check for the presence
 121 of messages or to only wait a certain time for messages respectively.
 122 </p>
 123 <p>
 124 For almost every function there exist two variants, one that locks
 125 the queue and one that doesn't. That way you can hold the queue lock
 126 (acquire it with <a class="link" href="glib-Asynchronous-Queues.html#g-async-queue-lock" title="g_async_queue_lock ()"><code class="function">g_async_queue_lock()</code></a> and release it with
 127 <a class="link" href="glib-Asynchronous-Queues.html#g-async-queue-unlock" title="g_async_queue_unlock ()"><code class="function">g_async_queue_unlock()</code></a>) over multiple queue accessing instructions.
 128 This can be necessary to ensure the integrity of the queue, but should
 129 only be used when really necessary, as it can make your life harder
 130 if used unwisely. Normally you should only use the locking function
 131 variants (those without the _unlocked suffix).
 132 </p>
 133 <p>
 134 In many cases, it may be more convenient to use <a class="link" href="glib-Thread-Pools.html#GThreadPool" title="struct GThreadPool"><span class="type">GThreadPool</span></a> when
 135 you need to distribute work to a set of worker threads instead of
 136 using <a class="link" href="glib-Asynchronous-Queues.html#GAsyncQueue" title="GAsyncQueue"><span class="type">GAsyncQueue</span></a> manually. <a class="link" href="glib-Thread-Pools.html#GThreadPool" title="struct GThreadPool"><span class="type">GThreadPool</span></a> uses a GAsyncQueue
 137 internally.
 138 </p>
 139 </div>
 140 <div class="refsect1">
 141 <a name="glib-Asynchronous-Queues.details"></a><h2>Details</h2>
 142 <div class="refsect2">
 143 <a name="GAsyncQueue"></a><h3>GAsyncQueue</h3>
 144 <pre class="programlisting">typedef struct _GAsyncQueue GAsyncQueue;</pre>
 145 <p>
 146 The GAsyncQueue struct is an opaque data structure which represents
 147 an asynchronous queue. It should only be accessed through the
 148 <code class="function">g_async_queue_*</code> functions.
 149 </p>
 150 </div>
 151 <hr>
 152 <div class="refsect2">
 153 <a name="g-async-queue-new"></a><h3>g_async_queue_new ()</h3>
 154 <pre class="programlisting"><a class="link" href="glib-Asynchronous-Queues.html#GAsyncQueue" title="GAsyncQueue"><span class="returnvalue">GAsyncQueue</span></a> *       g_async_queue_new                   (<em class="parameter"><code><span class="type">void</span></code></em>);</pre>
 155 <p>
 156 Creates a new asynchronous queue.
 157 </p>
 158 <div class="variablelist"><table border="0">
 159 <col align="left" valign="top">
 160 <tbody><tr>
 161 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
 162 <td>a new <a class="link" href="glib-Asynchronous-Queues.html#GAsyncQueue" title="GAsyncQueue"><span class="type">GAsyncQueue</span></a>. Free with <a class="link" href="glib-Asynchronous-Queues.html#g-async-queue-unref" title="g_async_queue_unref ()"><code class="function">g_async_queue_unref()</code></a>
 163 </td>
 164 </tr></tbody>
 165 </table></div>
 166 </div>
 167 <hr>
 168 <div class="refsect2">
 169 <a name="g-async-queue-new-full"></a><h3>g_async_queue_new_full ()</h3>
 170 <pre class="programlisting"><a class="link" href="glib-Asynchronous-Queues.html#GAsyncQueue" title="GAsyncQueue"><span class="returnvalue">GAsyncQueue</span></a> *       g_async_queue_new_full              (<em class="parameter"><code><a class="link" href="glib-Datasets.html#GDestroyNotify" title="GDestroyNotify ()"><span class="type">GDestroyNotify</span></a> item_free_func</code></em>);</pre>
 171 <p>
 172 Creates a new asynchronous queue and sets up a destroy notify
 173 function that is used to free any remaining queue items when
 174 the queue is destroyed after the final unref.
 175 </p>
 176 <div class="variablelist"><table border="0">
 177 <col align="left" valign="top">
 178 <tbody>
 179 <tr>
 180 <td><p><span class="term"><em class="parameter"><code>item_free_func</code></em> :</span></p></td>
 181 <td>function to free queue elements</td>
 182 </tr>
 183 <tr>
 184 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
 185 <td>a new <a class="link" href="glib-Asynchronous-Queues.html#GAsyncQueue" title="GAsyncQueue"><span class="type">GAsyncQueue</span></a>. Free with <a class="link" href="glib-Asynchronous-Queues.html#g-async-queue-unref" title="g_async_queue_unref ()"><code class="function">g_async_queue_unref()</code></a>
 186 </td>
 187 </tr>
 188 </tbody>
 189 </table></div>
 190 <p class="since">Since 2.16</p>
 191 </div>
 192 <hr>
 193 <div class="refsect2">
 194 <a name="g-async-queue-ref"></a><h3>g_async_queue_ref ()</h3>
 195 <pre class="programlisting"><a class="link" href="glib-Asynchronous-Queues.html#GAsyncQueue" title="GAsyncQueue"><span class="returnvalue">GAsyncQueue</span></a> *       g_async_queue_ref                   (<em class="parameter"><code><a class="link" href="glib-Asynchronous-Queues.html#GAsyncQueue" title="GAsyncQueue"><span class="type">GAsyncQueue</span></a> *queue</code></em>);</pre>
 196 <p>
 197 Increases the reference count of the asynchronous <em class="parameter"><code>queue</code></em> by 1.
 198 You do not need to hold the lock to call this function.
 199 </p>
 200 <div class="variablelist"><table border="0">
 201 <col align="left" valign="top">
 202 <tbody>
 203 <tr>
 204 <td><p><span class="term"><em class="parameter"><code>queue</code></em> :</span></p></td>
 205 <td>a <a class="link" href="glib-Asynchronous-Queues.html#GAsyncQueue" title="GAsyncQueue"><span class="type">GAsyncQueue</span></a>
 206 </td>
 207 </tr>
 208 <tr>
 209 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
 210 <td>the <em class="parameter"><code>queue</code></em> that was passed in (since 2.6)</td>
 211 </tr>
 212 </tbody>
 213 </table></div>
 214 </div>
 215 <hr>
 216 <div class="refsect2">
 217 <a name="g-async-queue-unref"></a><h3>g_async_queue_unref ()</h3>
 218 <pre class="programlisting"><span class="returnvalue">void</span>                g_async_queue_unref                 (<em class="parameter"><code><a class="link" href="glib-Asynchronous-Queues.html#GAsyncQueue" title="GAsyncQueue"><span class="type">GAsyncQueue</span></a> *queue</code></em>);</pre>
 219 <p>
 220 Decreases the reference count of the asynchronous <em class="parameter"><code>queue</code></em> by 1.
 221 </p>
 222 <p>
 223 If the reference count went to 0, the <em class="parameter"><code>queue</code></em> will be destroyed
 224 and the memory allocated will be freed. So you are not allowed
 225 to use the <em class="parameter"><code>queue</code></em> afterwards, as it might have disappeared.
 226 You do not need to hold the lock to call this function.
 227 </p>
 228 <div class="variablelist"><table border="0">
 229 <col align="left" valign="top">
 230 <tbody><tr>
 231 <td><p><span class="term"><em class="parameter"><code>queue</code></em> :</span></p></td>
 232 <td>a <a class="link" href="glib-Asynchronous-Queues.html#GAsyncQueue" title="GAsyncQueue"><span class="type">GAsyncQueue</span></a>.</td>
 233 </tr></tbody>
 234 </table></div>
 235 </div>
 236 <hr>
 237 <div class="refsect2">
 238 <a name="g-async-queue-push"></a><h3>g_async_queue_push ()</h3>
 239 <pre class="programlisting"><span class="returnvalue">void</span>                g_async_queue_push                  (<em class="parameter"><code><a class="link" href="glib-Asynchronous-Queues.html#GAsyncQueue" title="GAsyncQueue"><span class="type">GAsyncQueue</span></a> *queue</code></em>,
 240                                                          <em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gpointer" title="gpointer"><span class="type">gpointer</span></a> data</code></em>);</pre>
 241 <p>
 242 Pushes the <em class="parameter"><code>data</code></em> into the <em class="parameter"><code>queue</code></em>. <em class="parameter"><code>data</code></em> must not be <a class="link" href="glib-Standard-Macros.html#NULL:CAPS" title="NULL"><code class="literal">NULL</code></a>.
 243 </p>
 244 <div class="variablelist"><table border="0">
 245 <col align="left" valign="top">
 246 <tbody>
 247 <tr>
 248 <td><p><span class="term"><em class="parameter"><code>queue</code></em> :</span></p></td>
 249 <td>a <a class="link" href="glib-Asynchronous-Queues.html#GAsyncQueue" title="GAsyncQueue"><span class="type">GAsyncQueue</span></a>
 250 </td>
 251 </tr>
 252 <tr>
 253 <td><p><span class="term"><em class="parameter"><code>data</code></em> :</span></p></td>
 254 <td>
 255 <em class="parameter"><code>data</code></em> to push into the <em class="parameter"><code>queue</code></em>
 256 </td>
 257 </tr>
 258 </tbody>
 259 </table></div>
 260 </div>
 261 <hr>
 262 <div class="refsect2">
 263 <a name="g-async-queue-push-sorted"></a><h3>g_async_queue_push_sorted ()</h3>
 264 <pre class="programlisting"><span class="returnvalue">void</span>                g_async_queue_push_sorted           (<em class="parameter"><code><a class="link" href="glib-Asynchronous-Queues.html#GAsyncQueue" title="GAsyncQueue"><span class="type">GAsyncQueue</span></a> *queue</code></em>,
 265                                                          <em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gpointer" title="gpointer"><span class="type">gpointer</span></a> data</code></em>,
 266                                                          <em class="parameter"><code><a class="link" href="glib-Doubly-Linked-Lists.html#GCompareDataFunc" title="GCompareDataFunc ()"><span class="type">GCompareDataFunc</span></a> func</code></em>,
 267                                                          <em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gpointer" title="gpointer"><span class="type">gpointer</span></a> user_data</code></em>);</pre>
 268 <p>
 269 Inserts <em class="parameter"><code>data</code></em> into <em class="parameter"><code>queue</code></em> using <em class="parameter"><code>func</code></em> to determine the new
 270 position.
 271 </p>
 272 <p>
 273 This function requires that the <em class="parameter"><code>queue</code></em> is sorted before pushing on
 274 new elements, see <a class="link" href="glib-Asynchronous-Queues.html#g-async-queue-sort" title="g_async_queue_sort ()"><code class="function">g_async_queue_sort()</code></a>.
 275 </p>
 276 <p>
 277 This function will lock <em class="parameter"><code>queue</code></em> before it sorts the queue and unlock
 278 it when it is finished.
 279 </p>
 280 <p>
 281 For an example of <em class="parameter"><code>func</code></em> see <a class="link" href="glib-Asynchronous-Queues.html#g-async-queue-sort" title="g_async_queue_sort ()"><code class="function">g_async_queue_sort()</code></a>.
 282 </p>
 283 <div class="variablelist"><table border="0">
 284 <col align="left" valign="top">
 285 <tbody>
 286 <tr>
 287 <td><p><span class="term"><em class="parameter"><code>queue</code></em> :</span></p></td>
 288 <td>a <a class="link" href="glib-Asynchronous-Queues.html#GAsyncQueue" title="GAsyncQueue"><span class="type">GAsyncQueue</span></a>
 289 </td>
 290 </tr>
 291 <tr>
 292 <td><p><span class="term"><em class="parameter"><code>data</code></em> :</span></p></td>
 293 <td>the <em class="parameter"><code>data</code></em> to push into the <em class="parameter"><code>queue</code></em>
 294 </td>
 295 </tr>
 296 <tr>
 297 <td><p><span class="term"><em class="parameter"><code>func</code></em> :</span></p></td>
 298 <td>the <a class="link" href="glib-Doubly-Linked-Lists.html#GCompareDataFunc" title="GCompareDataFunc ()"><span class="type">GCompareDataFunc</span></a> is used to sort <em class="parameter"><code>queue</code></em>
 299 </td>
 300 </tr>
 301 <tr>
 302 <td><p><span class="term"><em class="parameter"><code>user_data</code></em> :</span></p></td>
 303 <td>user data passed to <em class="parameter"><code>func</code></em>.</td>
 304 </tr>
 305 </tbody>
 306 </table></div>
 307 <p class="since">Since 2.10</p>
 308 </div>
 309 <hr>
 310 <div class="refsect2">
 311 <a name="g-async-queue-pop"></a><h3>g_async_queue_pop ()</h3>
 312 <pre class="programlisting"><a class="link" href="glib-Basic-Types.html#gpointer" title="gpointer"><span class="returnvalue">gpointer</span></a>            g_async_queue_pop                   (<em class="parameter"><code><a class="link" href="glib-Asynchronous-Queues.html#GAsyncQueue" title="GAsyncQueue"><span class="type">GAsyncQueue</span></a> *queue</code></em>);</pre>
 313 <p>
 314 Pops data from the <em class="parameter"><code>queue</code></em>. If <em class="parameter"><code>queue</code></em> is empty, this function
 315 blocks until data becomes available.
 316 </p>
 317 <div class="variablelist"><table border="0">
 318 <col align="left" valign="top">
 319 <tbody>
 320 <tr>
 321 <td><p><span class="term"><em class="parameter"><code>queue</code></em> :</span></p></td>
 322 <td>a <a class="link" href="glib-Asynchronous-Queues.html#GAsyncQueue" title="GAsyncQueue"><span class="type">GAsyncQueue</span></a>
 323 </td>
 324 </tr>
 325 <tr>
 326 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
 327 <td>data from the queue</td>
 328 </tr>
 329 </tbody>
 330 </table></div>
 331 </div>
 332 <hr>
 333 <div class="refsect2">
 334 <a name="g-async-queue-try-pop"></a><h3>g_async_queue_try_pop ()</h3>
 335 <pre class="programlisting"><a class="link" href="glib-Basic-Types.html#gpointer" title="gpointer"><span class="returnvalue">gpointer</span></a>            g_async_queue_try_pop               (<em class="parameter"><code><a class="link" href="glib-Asynchronous-Queues.html#GAsyncQueue" title="GAsyncQueue"><span class="type">GAsyncQueue</span></a> *queue</code></em>);</pre>
 336 <p>
 337 Tries to pop data from the <em class="parameter"><code>queue</code></em>. If no data is available,
 338 <a class="link" href="glib-Standard-Macros.html#NULL:CAPS" title="NULL"><code class="literal">NULL</code></a> is returned.
 339 </p>
 340 <div class="variablelist"><table border="0">
 341 <col align="left" valign="top">
 342 <tbody>
 343 <tr>
 344 <td><p><span class="term"><em class="parameter"><code>queue</code></em> :</span></p></td>
 345 <td>a <a class="link" href="glib-Asynchronous-Queues.html#GAsyncQueue" title="GAsyncQueue"><span class="type">GAsyncQueue</span></a>
 346 </td>
 347 </tr>
 348 <tr>
 349 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
 350 <td>data from the queue or <a class="link" href="glib-Standard-Macros.html#NULL:CAPS" title="NULL"><code class="literal">NULL</code></a>, when no data is
 351 available immediately.</td>
 352 </tr>
 353 </tbody>
 354 </table></div>
 355 </div>
 356 <hr>
 357 <div class="refsect2">
 358 <a name="g-async-queue-timeout-pop"></a><h3>g_async_queue_timeout_pop ()</h3>
 359 <pre class="programlisting"><a class="link" href="glib-Basic-Types.html#gpointer" title="gpointer"><span class="returnvalue">gpointer</span></a>            g_async_queue_timeout_pop           (<em class="parameter"><code><a class="link" href="glib-Asynchronous-Queues.html#GAsyncQueue" title="GAsyncQueue"><span class="type">GAsyncQueue</span></a> *queue</code></em>,
 360                                                          <em class="parameter"><code><a class="link" href="glib-Basic-Types.html#guint64" title="guint64"><span class="type">guint64</span></a> timeout</code></em>);</pre>
 361 <p>
 362 Pops data from the <em class="parameter"><code>queue</code></em>. If the queue is empty, blocks for
 363 <em class="parameter"><code>timeout</code></em> microseconds, or until data becomes available.
 364 </p>
 365 <p>
 366 If no data is received before the timeout, <a class="link" href="glib-Standard-Macros.html#NULL:CAPS" title="NULL"><code class="literal">NULL</code></a> is returned.
 367 </p>
 368 <div class="variablelist"><table border="0">
 369 <col align="left" valign="top">
 370 <tbody>
 371 <tr>
 372 <td><p><span class="term"><em class="parameter"><code>queue</code></em> :</span></p></td>
 373 <td>a <a class="link" href="glib-Asynchronous-Queues.html#GAsyncQueue" title="GAsyncQueue"><span class="type">GAsyncQueue</span></a>
 374 </td>
 375 </tr>
 376 <tr>
 377 <td><p><span class="term"><em class="parameter"><code>timeout</code></em> :</span></p></td>
 378 <td>the number of microseconds to wait</td>
 379 </tr>
 380 <tr>
 381 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
 382 <td>data from the queue or <a class="link" href="glib-Standard-Macros.html#NULL:CAPS" title="NULL"><code class="literal">NULL</code></a>, when no data is
 383 received before the timeout.</td>
 384 </tr>
 385 </tbody>
 386 </table></div>
 387 </div>
 388 <hr>
 389 <div class="refsect2">
 390 <a name="g-async-queue-length"></a><h3>g_async_queue_length ()</h3>
 391 <pre class="programlisting"><a class="link" href="glib-Basic-Types.html#gint" title="gint"><span class="returnvalue">gint</span></a>                g_async_queue_length                (<em class="parameter"><code><a class="link" href="glib-Asynchronous-Queues.html#GAsyncQueue" title="GAsyncQueue"><span class="type">GAsyncQueue</span></a> *queue</code></em>);</pre>
 392 <p>
 393 Returns the length of the queue.
 394 </p>
 395 <p>
 396 Actually this function returns the number of data items in
 397 the queue minus the number of waiting threads, so a negative
 398 value means waiting threads, and a positive value means available
 399 entries in the <em class="parameter"><code>queue</code></em>. A return value of 0 could mean n entries
 400 in the queue and n threads waiting. This can happen due to locking
 401 of the queue or due to scheduling.
 402 </p>
 403 <div class="variablelist"><table border="0">
 404 <col align="left" valign="top">
 405 <tbody>
 406 <tr>
 407 <td><p><span class="term"><em class="parameter"><code>queue</code></em> :</span></p></td>
 408 <td>a <a class="link" href="glib-Asynchronous-Queues.html#GAsyncQueue" title="GAsyncQueue"><span class="type">GAsyncQueue</span></a>.</td>
 409 </tr>
 410 <tr>
 411 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
 412 <td>the length of the <em class="parameter"><code>queue</code></em>
 413 </td>
 414 </tr>
 415 </tbody>
 416 </table></div>
 417 </div>
 418 <hr>
 419 <div class="refsect2">
 420 <a name="g-async-queue-sort"></a><h3>g_async_queue_sort ()</h3>
 421 <pre class="programlisting"><span class="returnvalue">void</span>                g_async_queue_sort                  (<em class="parameter"><code><a class="link" href="glib-Asynchronous-Queues.html#GAsyncQueue" title="GAsyncQueue"><span class="type">GAsyncQueue</span></a> *queue</code></em>,
 422                                                          <em class="parameter"><code><a class="link" href="glib-Doubly-Linked-Lists.html#GCompareDataFunc" title="GCompareDataFunc ()"><span class="type">GCompareDataFunc</span></a> func</code></em>,
 423                                                          <em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gpointer" title="gpointer"><span class="type">gpointer</span></a> user_data</code></em>);</pre>
 424 <p>
 425 Sorts <em class="parameter"><code>queue</code></em> using <em class="parameter"><code>func</code></em>.
 426 </p>
 427 <p>
 428 The sort function <em class="parameter"><code>func</code></em> is passed two elements of the <em class="parameter"><code>queue</code></em>.
 429 It should return 0 if they are equal, a negative value if the
 430 first element should be higher in the <em class="parameter"><code>queue</code></em> or a positive value
 431 if the first element should be lower in the <em class="parameter"><code>queue</code></em> than the second
 432 element.
 433 </p>
 434 <p>
 435 This function will lock <em class="parameter"><code>queue</code></em> before it sorts the queue and unlock
 436 it when it is finished.
 437 </p>
 438 <p>
 439 If you were sorting a list of priority numbers to make sure the
 440 lowest priority would be at the top of the queue, you could use:
 441 </p>
 442 <div class="informalexample"><pre class="programlisting">
 443  gint32 id1;
 444  gint32 id2;
 445
 446  id1 = GPOINTER_TO_INT (element1);
 447  id2 = GPOINTER_TO_INT (element2);
 448
 449  return (id1 &gt; id2 ? +1 : id1 == id2 ? 0 : -1);
 450 </pre></div>
 451 <p>
 452 </p>
 453 <div class="variablelist"><table border="0">
 454 <col align="left" valign="top">
 455 <tbody>
 456 <tr>
 457 <td><p><span class="term"><em class="parameter"><code>queue</code></em> :</span></p></td>
 458 <td>a <a class="link" href="glib-Asynchronous-Queues.html#GAsyncQueue" title="GAsyncQueue"><span class="type">GAsyncQueue</span></a>
 459 </td>
 460 </tr>
 461 <tr>
 462 <td><p><span class="term"><em class="parameter"><code>func</code></em> :</span></p></td>
 463 <td>the <a class="link" href="glib-Doubly-Linked-Lists.html#GCompareDataFunc" title="GCompareDataFunc ()"><span class="type">GCompareDataFunc</span></a> is used to sort <em class="parameter"><code>queue</code></em>
 464 </td>
 465 </tr>
 466 <tr>
 467 <td><p><span class="term"><em class="parameter"><code>user_data</code></em> :</span></p></td>
 468 <td>user data passed to <em class="parameter"><code>func</code></em>
 469 </td>
 470 </tr>
 471 </tbody>
 472 </table></div>
 473 <p class="since">Since 2.10</p>
 474 </div>
 475 <hr>
 476 <div class="refsect2">
 477 <a name="g-async-queue-lock"></a><h3>g_async_queue_lock ()</h3>
 478 <pre class="programlisting"><span class="returnvalue">void</span>                g_async_queue_lock                  (<em class="parameter"><code><a class="link" href="glib-Asynchronous-Queues.html#GAsyncQueue" title="GAsyncQueue"><span class="type">GAsyncQueue</span></a> *queue</code></em>);</pre>
 479 <p>
 480 Acquires the <em class="parameter"><code>queue</code></em>'s lock. If another thread is already
 481 holding the lock, this call will block until the lock
 482 becomes available.
 483 </p>
 484 <p>
 485 Call <a class="link" href="glib-Asynchronous-Queues.html#g-async-queue-unlock" title="g_async_queue_unlock ()"><code class="function">g_async_queue_unlock()</code></a> to drop the lock again.
 486 </p>
 487 <p>
 488 While holding the lock, you can only call the
 489 <code class="function">g_async_queue_*_unlocked()</code> functions
 490 on <em class="parameter"><code>queue</code></em>. Otherwise, deadlock may occur.
 491 </p>
 492 <div class="variablelist"><table border="0">
 493 <col align="left" valign="top">
 494 <tbody><tr>
 495 <td><p><span class="term"><em class="parameter"><code>queue</code></em> :</span></p></td>
 496 <td>a <a class="link" href="glib-Asynchronous-Queues.html#GAsyncQueue" title="GAsyncQueue"><span class="type">GAsyncQueue</span></a>
 497 </td>
 498 </tr></tbody>
 499 </table></div>
 500 </div>
 501 <hr>
 502 <div class="refsect2">
 503 <a name="g-async-queue-unlock"></a><h3>g_async_queue_unlock ()</h3>
 504 <pre class="programlisting"><span class="returnvalue">void</span>                g_async_queue_unlock                (<em class="parameter"><code><a class="link" href="glib-Asynchronous-Queues.html#GAsyncQueue" title="GAsyncQueue"><span class="type">GAsyncQueue</span></a> *queue</code></em>);</pre>
 505 <p>
 506 Releases the queue's lock.
 507 </p>
 508 <p>
 509 Calling this function when you have not acquired
 510 the with <a class="link" href="glib-Asynchronous-Queues.html#g-async-queue-lock" title="g_async_queue_lock ()"><code class="function">g_async_queue_lock()</code></a> leads to undefined
 511 behaviour.
 512 </p>
 513 <div class="variablelist"><table border="0">
 514 <col align="left" valign="top">
 515 <tbody><tr>
 516 <td><p><span class="term"><em class="parameter"><code>queue</code></em> :</span></p></td>
 517 <td>a <a class="link" href="glib-Asynchronous-Queues.html#GAsyncQueue" title="GAsyncQueue"><span class="type">GAsyncQueue</span></a>
 518 </td>
 519 </tr></tbody>
 520 </table></div>
 521 </div>
 522 <hr>
 523 <div class="refsect2">
 524 <a name="g-async-queue-ref-unlocked"></a><h3>g_async_queue_ref_unlocked ()</h3>
 525 <pre class="programlisting"><span class="returnvalue">void</span>                g_async_queue_ref_unlocked          (<em class="parameter"><code><a class="link" href="glib-Asynchronous-Queues.html#GAsyncQueue" title="GAsyncQueue"><span class="type">GAsyncQueue</span></a> *queue</code></em>);</pre>
 526 <div class="warning" style="margin-left: 0.5in; margin-right: 0.5in;">
 527 <h3 class="title">Warning</h3>
 528 <p><code class="literal">g_async_queue_ref_unlocked</code> has been deprecated since version 2.8 and should not be used in newly-written code. Reference counting is done atomically.
 529 so <a class="link" href="glib-Asynchronous-Queues.html#g-async-queue-ref" title="g_async_queue_ref ()"><code class="function">g_async_queue_ref()</code></a> can be used regardless of the <em class="parameter"><code>queue</code></em>'s
 530 lock.</p>
 531 </div>
 532 <p>
 533 Increases the reference count of the asynchronous <em class="parameter"><code>queue</code></em> by 1.
 534 </p>
 535 <div class="variablelist"><table border="0">
 536 <col align="left" valign="top">
 537 <tbody><tr>
 538 <td><p><span class="term"><em class="parameter"><code>queue</code></em> :</span></p></td>
 539 <td>a <a class="link" href="glib-Asynchronous-Queues.html#GAsyncQueue" title="GAsyncQueue"><span class="type">GAsyncQueue</span></a>
 540 </td>
 541 </tr></tbody>
 542 </table></div>
 543 </div>
 544 <hr>
 545 <div class="refsect2">
 546 <a name="g-async-queue-unref-and-unlock"></a><h3>g_async_queue_unref_and_unlock ()</h3>
 547 <pre class="programlisting"><span class="returnvalue">void</span>                g_async_queue_unref_and_unlock      (<em class="parameter"><code><a class="link" href="glib-Asynchronous-Queues.html#GAsyncQueue" title="GAsyncQueue"><span class="type">GAsyncQueue</span></a> *queue</code></em>);</pre>
 548 <div class="warning" style="margin-left: 0.5in; margin-right: 0.5in;">
 549 <h3 class="title">Warning</h3>
 550 <p><code class="literal">g_async_queue_unref_and_unlock</code> has been deprecated since version 2.8 and should not be used in newly-written code. Reference counting is done atomically.
 551 so <a class="link" href="glib-Asynchronous-Queues.html#g-async-queue-unref" title="g_async_queue_unref ()"><code class="function">g_async_queue_unref()</code></a> can be used regardless of the <em class="parameter"><code>queue</code></em>'s
 552 lock.</p>
 553 </div>
 554 <p>
 555 Decreases the reference count of the asynchronous <em class="parameter"><code>queue</code></em> by 1
 556 and releases the lock. This function must be called while holding
 557 the <em class="parameter"><code>queue</code></em>'s lock. If the reference count went to 0, the <em class="parameter"><code>queue</code></em>
 558 will be destroyed and the memory allocated will be freed.
 559 </p>
 560 <div class="variablelist"><table border="0">
 561 <col align="left" valign="top">
 562 <tbody><tr>
 563 <td><p><span class="term"><em class="parameter"><code>queue</code></em> :</span></p></td>
 564 <td>a <a class="link" href="glib-Asynchronous-Queues.html#GAsyncQueue" title="GAsyncQueue"><span class="type">GAsyncQueue</span></a>
 565 </td>
 566 </tr></tbody>
 567 </table></div>
 568 </div>
 569 <hr>
 570 <div class="refsect2">
 571 <a name="g-async-queue-push-unlocked"></a><h3>g_async_queue_push_unlocked ()</h3>
 572 <pre class="programlisting"><span class="returnvalue">void</span>                g_async_queue_push_unlocked         (<em class="parameter"><code><a class="link" href="glib-Asynchronous-Queues.html#GAsyncQueue" title="GAsyncQueue"><span class="type">GAsyncQueue</span></a> *queue</code></em>,
 573                                                          <em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gpointer" title="gpointer"><span class="type">gpointer</span></a> data</code></em>);</pre>
 574 <p>
 575 Pushes the <em class="parameter"><code>data</code></em> into the <em class="parameter"><code>queue</code></em>. <em class="parameter"><code>data</code></em> must not be <a class="link" href="glib-Standard-Macros.html#NULL:CAPS" title="NULL"><code class="literal">NULL</code></a>.
 576 </p>
 577 <p>
 578 This function must be called while holding the <em class="parameter"><code>queue</code></em>'s lock.
 579 </p>
 580 <div class="variablelist"><table border="0">
 581 <col align="left" valign="top">
 582 <tbody>
 583 <tr>
 584 <td><p><span class="term"><em class="parameter"><code>queue</code></em> :</span></p></td>
 585 <td>a <a class="link" href="glib-Asynchronous-Queues.html#GAsyncQueue" title="GAsyncQueue"><span class="type">GAsyncQueue</span></a>
 586 </td>
 587 </tr>
 588 <tr>
 589 <td><p><span class="term"><em class="parameter"><code>data</code></em> :</span></p></td>
 590 <td>
 591 <em class="parameter"><code>data</code></em> to push into the <em class="parameter"><code>queue</code></em>
 592 </td>
 593 </tr>
 594 </tbody>
 595 </table></div>
 596 </div>
 597 <hr>
 598 <div class="refsect2">
 599 <a name="g-async-queue-push-sorted-unlocked"></a><h3>g_async_queue_push_sorted_unlocked ()</h3>
 600 <pre class="programlisting"><span class="returnvalue">void</span>                g_async_queue_push_sorted_unlocked  (<em class="parameter"><code><a class="link" href="glib-Asynchronous-Queues.html#GAsyncQueue" title="GAsyncQueue"><span class="type">GAsyncQueue</span></a> *queue</code></em>,
 601                                                          <em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gpointer" title="gpointer"><span class="type">gpointer</span></a> data</code></em>,
 602                                                          <em class="parameter"><code><a class="link" href="glib-Doubly-Linked-Lists.html#GCompareDataFunc" title="GCompareDataFunc ()"><span class="type">GCompareDataFunc</span></a> func</code></em>,
 603                                                          <em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gpointer" title="gpointer"><span class="type">gpointer</span></a> user_data</code></em>);</pre>
 604 <p>
 605 Inserts <em class="parameter"><code>data</code></em> into <em class="parameter"><code>queue</code></em> using <em class="parameter"><code>func</code></em> to determine the new
 606 position.
 607 </p>
 608 <p>
 609 The sort function <em class="parameter"><code>func</code></em> is passed two elements of the <em class="parameter"><code>queue</code></em>.
 610 It should return 0 if they are equal, a negative value if the
 611 first element should be higher in the <em class="parameter"><code>queue</code></em> or a positive value
 612 if the first element should be lower in the <em class="parameter"><code>queue</code></em> than the second
 613 element.
 614 </p>
 615 <p>
 616 This function requires that the <em class="parameter"><code>queue</code></em> is sorted before pushing on
 617 new elements, see <a class="link" href="glib-Asynchronous-Queues.html#g-async-queue-sort" title="g_async_queue_sort ()"><code class="function">g_async_queue_sort()</code></a>.
 618 </p>
 619 <p>
 620 This function must be called while holding the <em class="parameter"><code>queue</code></em>'s lock.
 621 </p>
 622 <p>
 623 For an example of <em class="parameter"><code>func</code></em> see <a class="link" href="glib-Asynchronous-Queues.html#g-async-queue-sort" title="g_async_queue_sort ()"><code class="function">g_async_queue_sort()</code></a>.
 624 </p>
 625 <div class="variablelist"><table border="0">
 626 <col align="left" valign="top">
 627 <tbody>
 628 <tr>
 629 <td><p><span class="term"><em class="parameter"><code>queue</code></em> :</span></p></td>
 630 <td>a <a class="link" href="glib-Asynchronous-Queues.html#GAsyncQueue" title="GAsyncQueue"><span class="type">GAsyncQueue</span></a>
 631 </td>
 632 </tr>
 633 <tr>
 634 <td><p><span class="term"><em class="parameter"><code>data</code></em> :</span></p></td>
 635 <td>the <em class="parameter"><code>data</code></em> to push into the <em class="parameter"><code>queue</code></em>
 636 </td>
 637 </tr>
 638 <tr>
 639 <td><p><span class="term"><em class="parameter"><code>func</code></em> :</span></p></td>
 640 <td>the <a class="link" href="glib-Doubly-Linked-Lists.html#GCompareDataFunc" title="GCompareDataFunc ()"><span class="type">GCompareDataFunc</span></a> is used to sort <em class="parameter"><code>queue</code></em>
 641 </td>
 642 </tr>
 643 <tr>
 644 <td><p><span class="term"><em class="parameter"><code>user_data</code></em> :</span></p></td>
 645 <td>user data passed to <em class="parameter"><code>func</code></em>.</td>
 646 </tr>
 647 </tbody>
 648 </table></div>
 649 <p class="since">Since 2.10</p>
 650 </div>
 651 <hr>
 652 <div class="refsect2">
 653 <a name="g-async-queue-pop-unlocked"></a><h3>g_async_queue_pop_unlocked ()</h3>
 654 <pre class="programlisting"><a class="link" href="glib-Basic-Types.html#gpointer" title="gpointer"><span class="returnvalue">gpointer</span></a>            g_async_queue_pop_unlocked          (<em class="parameter"><code><a class="link" href="glib-Asynchronous-Queues.html#GAsyncQueue" title="GAsyncQueue"><span class="type">GAsyncQueue</span></a> *queue</code></em>);</pre>
 655 <p>
 656 Pops data from the <em class="parameter"><code>queue</code></em>. If <em class="parameter"><code>queue</code></em> is empty, this function
 657 blocks until data becomes available.
 658 </p>
 659 <p>
 660 This function must be called while holding the <em class="parameter"><code>queue</code></em>'s lock.
 661 </p>
 662 <div class="variablelist"><table border="0">
 663 <col align="left" valign="top">
 664 <tbody>
 665 <tr>
 666 <td><p><span class="term"><em class="parameter"><code>queue</code></em> :</span></p></td>
 667 <td>a <a class="link" href="glib-Asynchronous-Queues.html#GAsyncQueue" title="GAsyncQueue"><span class="type">GAsyncQueue</span></a>
 668 </td>
 669 </tr>
 670 <tr>
 671 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
 672 <td>data from the queue.</td>
 673 </tr>
 674 </tbody>
 675 </table></div>
 676 </div>
 677 <hr>
 678 <div class="refsect2">
 679 <a name="g-async-queue-try-pop-unlocked"></a><h3>g_async_queue_try_pop_unlocked ()</h3>
 680 <pre class="programlisting"><a class="link" href="glib-Basic-Types.html#gpointer" title="gpointer"><span class="returnvalue">gpointer</span></a>            g_async_queue_try_pop_unlocked      (<em class="parameter"><code><a class="link" href="glib-Asynchronous-Queues.html#GAsyncQueue" title="GAsyncQueue"><span class="type">GAsyncQueue</span></a> *queue</code></em>);</pre>
 681 <p>
 682 Tries to pop data from the <em class="parameter"><code>queue</code></em>. If no data is available,
 683 <a class="link" href="glib-Standard-Macros.html#NULL:CAPS" title="NULL"><code class="literal">NULL</code></a> is returned.
 684 </p>
 685 <p>
 686 This function must be called while holding the <em class="parameter"><code>queue</code></em>'s lock.
 687 </p>
 688 <div class="variablelist"><table border="0">
 689 <col align="left" valign="top">
 690 <tbody>
 691 <tr>
 692 <td><p><span class="term"><em class="parameter"><code>queue</code></em> :</span></p></td>
 693 <td>a <a class="link" href="glib-Asynchronous-Queues.html#GAsyncQueue" title="GAsyncQueue"><span class="type">GAsyncQueue</span></a>
 694 </td>
 695 </tr>
 696 <tr>
 697 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
 698 <td>data from the queue or <a class="link" href="glib-Standard-Macros.html#NULL:CAPS" title="NULL"><code class="literal">NULL</code></a>, when no data is
 699 available immediately.</td>
 700 </tr>
 701 </tbody>
 702 </table></div>
 703 </div>
 704 <hr>
 705 <div class="refsect2">
 706 <a name="g-async-queue-timeout-pop-unlocked"></a><h3>g_async_queue_timeout_pop_unlocked ()</h3>
 707 <pre class="programlisting"><a class="link" href="glib-Basic-Types.html#gpointer" title="gpointer"><span class="returnvalue">gpointer</span></a>            g_async_queue_timeout_pop_unlocked  (<em class="parameter"><code><a class="link" href="glib-Asynchronous-Queues.html#GAsyncQueue" title="GAsyncQueue"><span class="type">GAsyncQueue</span></a> *queue</code></em>,
 708                                                          <em class="parameter"><code><a class="link" href="glib-Basic-Types.html#guint64" title="guint64"><span class="type">guint64</span></a> timeout</code></em>);</pre>
 709 <p>
 710 Pops data from the <em class="parameter"><code>queue</code></em>. If the queue is empty, blocks for
 711 <em class="parameter"><code>timeout</code></em> microseconds, or until data becomes available.
 712 </p>
 713 <p>
 714 If no data is received before the timeout, <a class="link" href="glib-Standard-Macros.html#NULL:CAPS" title="NULL"><code class="literal">NULL</code></a> is returned.
 715 </p>
 716 <p>
 717 This function must be called while holding the <em class="parameter"><code>queue</code></em>'s lock.
 718 </p>
 719 <div class="variablelist"><table border="0">
 720 <col align="left" valign="top">
 721 <tbody>
 722 <tr>
 723 <td><p><span class="term"><em class="parameter"><code>queue</code></em> :</span></p></td>
 724 <td>a <a class="link" href="glib-Asynchronous-Queues.html#GAsyncQueue" title="GAsyncQueue"><span class="type">GAsyncQueue</span></a>
 725 </td>
 726 </tr>
 727 <tr>
 728 <td><p><span class="term"><em class="parameter"><code>timeout</code></em> :</span></p></td>
 729 <td>the number of microseconds to wait</td>
 730 </tr>
 731 <tr>
 732 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
 733 <td>data from the queue or <a class="link" href="glib-Standard-Macros.html#NULL:CAPS" title="NULL"><code class="literal">NULL</code></a>, when no data is
 734 received before the timeout.</td>
 735 </tr>
 736 </tbody>
 737 </table></div>
 738 </div>
 739 <hr>
 740 <div class="refsect2">
 741 <a name="g-async-queue-length-unlocked"></a><h3>g_async_queue_length_unlocked ()</h3>
 742 <pre class="programlisting"><a class="link" href="glib-Basic-Types.html#gint" title="gint"><span class="returnvalue">gint</span></a>                g_async_queue_length_unlocked       (<em class="parameter"><code><a class="link" href="glib-Asynchronous-Queues.html#GAsyncQueue" title="GAsyncQueue"><span class="type">GAsyncQueue</span></a> *queue</code></em>);</pre>
 743 <p>
 744 Returns the length of the queue.
 745 </p>
 746 <p>
 747 Actually this function returns the number of data items in
 748 the queue minus the number of waiting threads, so a negative
 749 value means waiting threads, and a positive value means available
 750 entries in the <em class="parameter"><code>queue</code></em>. A return value of 0 could mean n entries
 751 in the queue and n threads waiting. This can happen due to locking
 752 of the queue or due to scheduling.
 753 </p>
 754 <p>
 755 This function must be called while holding the <em class="parameter"><code>queue</code></em>'s lock.
 756 </p>
 757 <div class="variablelist"><table border="0">
 758 <col align="left" valign="top">
 759 <tbody>
 760 <tr>
 761 <td><p><span class="term"><em class="parameter"><code>queue</code></em> :</span></p></td>
 762 <td>a <a class="link" href="glib-Asynchronous-Queues.html#GAsyncQueue" title="GAsyncQueue"><span class="type">GAsyncQueue</span></a>
 763 </td>
 764 </tr>
 765 <tr>
 766 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
 767 <td>the length of the <em class="parameter"><code>queue</code></em>.</td>
 768 </tr>
 769 </tbody>
 770 </table></div>
 771 </div>
 772 <hr>
 773 <div class="refsect2">
 774 <a name="g-async-queue-sort-unlocked"></a><h3>g_async_queue_sort_unlocked ()</h3>
 775 <pre class="programlisting"><span class="returnvalue">void</span>                g_async_queue_sort_unlocked         (<em class="parameter"><code><a class="link" href="glib-Asynchronous-Queues.html#GAsyncQueue" title="GAsyncQueue"><span class="type">GAsyncQueue</span></a> *queue</code></em>,
 776                                                          <em class="parameter"><code><a class="link" href="glib-Doubly-Linked-Lists.html#GCompareDataFunc" title="GCompareDataFunc ()"><span class="type">GCompareDataFunc</span></a> func</code></em>,
 777                                                          <em class="parameter"><code><a class="link" href="glib-Basic-Types.html#gpointer" title="gpointer"><span class="type">gpointer</span></a> user_data</code></em>);</pre>
 778 <p>
 779 Sorts <em class="parameter"><code>queue</code></em> using <em class="parameter"><code>func</code></em>.
 780 </p>
 781 <p>
 782 The sort function <em class="parameter"><code>func</code></em> is passed two elements of the <em class="parameter"><code>queue</code></em>.
 783 It should return 0 if they are equal, a negative value if the
 784 first element should be higher in the <em class="parameter"><code>queue</code></em> or a positive value
 785 if the first element should be lower in the <em class="parameter"><code>queue</code></em> than the second
 786 element.
 787 </p>
 788 <p>
 789 This function must be called while holding the <em class="parameter"><code>queue</code></em>'s lock.
 790 </p>
 791 <div class="variablelist"><table border="0">
 792 <col align="left" valign="top">
 793 <tbody>
 794 <tr>
 795 <td><p><span class="term"><em class="parameter"><code>queue</code></em> :</span></p></td>
 796 <td>a <a class="link" href="glib-Asynchronous-Queues.html#GAsyncQueue" title="GAsyncQueue"><span class="type">GAsyncQueue</span></a>
 797 </td>
 798 </tr>
 799 <tr>
 800 <td><p><span class="term"><em class="parameter"><code>func</code></em> :</span></p></td>
 801 <td>the <a class="link" href="glib-Doubly-Linked-Lists.html#GCompareDataFunc" title="GCompareDataFunc ()"><span class="type">GCompareDataFunc</span></a> is used to sort <em class="parameter"><code>queue</code></em>
 802 </td>
 803 </tr>
 804 <tr>
 805 <td><p><span class="term"><em class="parameter"><code>user_data</code></em> :</span></p></td>
 806 <td>user data passed to <em class="parameter"><code>func</code></em>
 807 </td>
 808 </tr>
 809 </tbody>
 810 </table></div>
 811 <p class="since">Since 2.10</p>
 812 </div>
 813 <hr>
 814 <div class="refsect2">
 815 <a name="g-async-queue-timed-pop"></a><h3>g_async_queue_timed_pop ()</h3>
 816 <pre class="programlisting"><a class="link" href="glib-Basic-Types.html#gpointer" title="gpointer"><span class="returnvalue">gpointer</span></a>            g_async_queue_timed_pop             (<em class="parameter"><code><a class="link" href="glib-Asynchronous-Queues.html#GAsyncQueue" title="GAsyncQueue"><span class="type">GAsyncQueue</span></a> *queue</code></em>,
 817                                                          <em class="parameter"><code><a class="link" href="glib-Date-and-Time-Functions.html#GTimeVal" title="struct GTimeVal"><span class="type">GTimeVal</span></a> *end_time</code></em>);</pre>
 818 <div class="warning" style="margin-left: 0.5in; margin-right: 0.5in;">
 819 <h3 class="title">Warning</h3>
 820 <p><code class="literal">g_async_queue_timed_pop</code> is deprecated and should not be used in newly-written code. use <a class="link" href="glib-Asynchronous-Queues.html#g-async-queue-timeout-pop" title="g_async_queue_timeout_pop ()"><code class="function">g_async_queue_timeout_pop()</code></a>.</p>
 821 </div>
 822 <p>
 823 Pops data from the <em class="parameter"><code>queue</code></em>. If the queue is empty, blocks until
 824 <em class="parameter"><code>end_time</code></em> or until data becomes available.
 825 </p>
 826 <p>
 827 If no data is received before <em class="parameter"><code>end_time</code></em>, <a class="link" href="glib-Standard-Macros.html#NULL:CAPS" title="NULL"><code class="literal">NULL</code></a> is returned.
 828 </p>
 829 <p>
 830 To easily calculate <em class="parameter"><code>end_time</code></em>, a combination of <a class="link" href="glib-Date-and-Time-Functions.html#g-get-current-time" title="g_get_current_time ()"><code class="function">g_get_current_time()</code></a>
 831 and <a class="link" href="glib-Date-and-Time-Functions.html#g-time-val-add" title="g_time_val_add ()"><code class="function">g_time_val_add()</code></a> can be used.
 832 </p>
 833 <div class="variablelist"><table border="0">
 834 <col align="left" valign="top">
 835 <tbody>
 836 <tr>
 837 <td><p><span class="term"><em class="parameter"><code>queue</code></em> :</span></p></td>
 838 <td>a <a class="link" href="glib-Asynchronous-Queues.html#GAsyncQueue" title="GAsyncQueue"><span class="type">GAsyncQueue</span></a>
 839 </td>
 840 </tr>
 841 <tr>
 842 <td><p><span class="term"><em class="parameter"><code>end_time</code></em> :</span></p></td>
 843 <td>a <a class="link" href="glib-Date-and-Time-Functions.html#GTimeVal" title="struct GTimeVal"><span class="type">GTimeVal</span></a>, determining the final time</td>
 844 </tr>
 845 <tr>
 846 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
 847 <td>data from the queue or <a class="link" href="glib-Standard-Macros.html#NULL:CAPS" title="NULL"><code class="literal">NULL</code></a>, when no data is
 848 received before <em class="parameter"><code>end_time</code></em>.</td>
 849 </tr>
 850 </tbody>
 851 </table></div>
 852 </div>
 853 <hr>
 854 <div class="refsect2">
 855 <a name="g-async-queue-timed-pop-unlocked"></a><h3>g_async_queue_timed_pop_unlocked ()</h3>
 856 <pre class="programlisting"><a class="link" href="glib-Basic-Types.html#gpointer" title="gpointer"><span class="returnvalue">gpointer</span></a>            g_async_queue_timed_pop_unlocked    (<em class="parameter"><code><a class="link" href="glib-Asynchronous-Queues.html#GAsyncQueue" title="GAsyncQueue"><span class="type">GAsyncQueue</span></a> *queue</code></em>,
 857                                                          <em class="parameter"><code><a class="link" href="glib-Date-and-Time-Functions.html#GTimeVal" title="struct GTimeVal"><span class="type">GTimeVal</span></a> *end_time</code></em>);</pre>
 858 <div class="warning" style="margin-left: 0.5in; margin-right: 0.5in;">
 859 <h3 class="title">Warning</h3>
 860 <p><code class="literal">g_async_queue_timed_pop_unlocked</code> is deprecated and should not be used in newly-written code. use <a class="link" href="glib-Asynchronous-Queues.html#g-async-queue-timeout-pop-unlocked" title="g_async_queue_timeout_pop_unlocked ()"><code class="function">g_async_queue_timeout_pop_unlocked()</code></a>.</p>
 861 </div>
 862 <p>
 863 Pops data from the <em class="parameter"><code>queue</code></em>. If the queue is empty, blocks until
 864 <em class="parameter"><code>end_time</code></em> or until data becomes available.
 865 </p>
 866 <p>
 867 If no data is received before <em class="parameter"><code>end_time</code></em>, <a class="link" href="glib-Standard-Macros.html#NULL:CAPS" title="NULL"><code class="literal">NULL</code></a> is returned.
 868 </p>
 869 <p>
 870 To easily calculate <em class="parameter"><code>end_time</code></em>, a combination of <a class="link" href="glib-Date-and-Time-Functions.html#g-get-current-time" title="g_get_current_time ()"><code class="function">g_get_current_time()</code></a>
 871 and <a class="link" href="glib-Date-and-Time-Functions.html#g-time-val-add" title="g_time_val_add ()"><code class="function">g_time_val_add()</code></a> can be used.
 872 </p>
 873 <p>
 874 This function must be called while holding the <em class="parameter"><code>queue</code></em>'s lock.
 875 </p>
 876 <div class="variablelist"><table border="0">
 877 <col align="left" valign="top">
 878 <tbody>
 879 <tr>
 880 <td><p><span class="term"><em class="parameter"><code>queue</code></em> :</span></p></td>
 881 <td>a <a class="link" href="glib-Asynchronous-Queues.html#GAsyncQueue" title="GAsyncQueue"><span class="type">GAsyncQueue</span></a>
 882 </td>
 883 </tr>
 884 <tr>
 885 <td><p><span class="term"><em class="parameter"><code>end_time</code></em> :</span></p></td>
 886 <td>a <a class="link" href="glib-Date-and-Time-Functions.html#GTimeVal" title="struct GTimeVal"><span class="type">GTimeVal</span></a>, determining the final time</td>
 887 </tr>
 888 <tr>
 889 <td><p><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></p></td>
 890 <td>data from the queue or <a class="link" href="glib-Standard-Macros.html#NULL:CAPS" title="NULL"><code class="literal">NULL</code></a>, when no data is
 891 received before <em class="parameter"><code>end_time</code></em>.</td>
 892 </tr>
 893 </tbody>
 894 </table></div>
 895 </div>
 896 </div>
 897 <div class="refsect1">
 898 <a name="glib-Asynchronous-Queues.see-also"></a><h2>See Also</h2>
 899 <a class="link" href="glib-Thread-Pools.html#GThreadPool" title="struct GThreadPool"><span class="type">GThreadPool</span></a>
 900 </div>
 901 </div>
 902 <div class="footer">
 903 <hr>
 904           Generated by GTK-Doc V1.18</div>
 905 </body>
 906 </html>