async_queues.sgml

GLib是GTK+和GNOME工程的基础底层核心程序库

To easily calculate <parameter>end_time</parameter> a combination of <link linkend="g-get-current-time">g_get_current_time</link>()
and <link linkend="g-time-val-add">g_time_val_add</link>() can be used.</para>
<informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>queue</parameter>&nbsp;:</entry>
<entry> a <link linkend="GAsyncQueue">GAsyncQueue</link>.
</entry></row>
<row><entry align="right"><parameter>end_time</parameter>&nbsp;:</entry>
<entry> a <link linkend="GTimeVal">GTimeVal</link>, determining the final time.
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry> data from the queue or <literal>NULL</literal>, when no data is
received before <parameter>end_time</parameter>.
</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-async-queue-length">g_async_queue_length ()</title>
<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>
<informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>queue</parameter>&nbsp;:</entry>
<entry> a <link linkend="GAsyncQueue">GAsyncQueue</link>.
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry> the length of the <parameter>queue</parameter>.
</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-async-queue-lock">g_async_queue_lock ()</title>
<programlisting>void        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">_unlocked</link>()</function> function variants on that
<parameter>queue</parameter>. Otherwise it will deadlock.</para>
<informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>queue</parameter>&nbsp;:</entry>
<entry> a <link linkend="GAsyncQueue">GAsyncQueue</link>.
</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-async-queue-unlock">g_async_queue_unlock ()</title>
<programlisting>void        g_async_queue_unlock            (<link linkend="GAsyncQueue">GAsyncQueue</link> *queue);</programlisting>
<para>
Releases the queue's lock.</para>
<informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>queue</parameter>&nbsp;:</entry>
<entry> a <link linkend="GAsyncQueue">GAsyncQueue</link>.
</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-async-queue-ref-unlocked">g_async_queue_ref_unlocked ()</title>
<programlisting>void        g_async_queue_ref_unlocked      (<link linkend="GAsyncQueue">GAsyncQueue</link> *queue);</programlisting>
<para>
Increases the reference count of the asynchronous <parameter>queue</parameter> by 1. This
function must be called while holding the <parameter>queue</parameter>'s lock.</para>
<informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>queue</parameter>&nbsp;:</entry>
<entry> a <link linkend="GAsyncQueue">GAsyncQueue</link>.
</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-async-queue-unref-and-unlock">g_async_queue_unref_and_unlock ()</title>
<programlisting>void        g_async_queue_unref_and_unlock  (<link linkend="GAsyncQueue">GAsyncQueue</link> *queue);</programlisting>
<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. So you are not
allowed to use the <parameter>queue</parameter> afterwards, as it might have disappeared.
The obvious asymmetry (it is not named
<link linkend="g-async-queue-unref-unlocked">g_async_queue_unref_unlocked</link>()) is because the queue can't be
unlocked after unreffing it, as it might already have disappeared.</para>
<informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>queue</parameter>&nbsp;:</entry>
<entry> a <link linkend="GAsyncQueue">GAsyncQueue</link>.
</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-async-queue-push-unlocked">g_async_queue_push_unlocked ()</title>
<programlisting>void        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 <literal>NULL</literal>. This
function must be called while holding the <parameter>queue</parameter>'s lock.</para>
<informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>queue</parameter>&nbsp;:</entry>
<entry> a <link linkend="GAsyncQueue">GAsyncQueue</link>.
</entry></row>
<row><entry align="right"><parameter>data</parameter>&nbsp;:</entry>
<entry> <parameter>data</parameter> to push into the <parameter>queue</parameter>.
</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-async-queue-pop-unlocked">g_async_queue_pop_unlocked ()</title>
<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>
<informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>queue</parameter>&nbsp;:</entry>
<entry> a <link linkend="GAsyncQueue">GAsyncQueue</link>.
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry> data from the queue.
</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-async-queue-try-pop-unlocked">g_async_queue_try_pop_unlocked ()</title>
<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, <literal>NULL</literal> is
returned. This function must be called while holding the <parameter>queue</parameter>'s
lock.</para>
<informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>queue</parameter>&nbsp;:</entry>
<entry> a <link linkend="GAsyncQueue">GAsyncQueue</link>.
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry> data from the queue or <literal>NULL</literal>, when no data is
available immediately.
</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-async-queue-timed-pop-unlocked">g_async_queue_timed_pop_unlocked ()</title>
<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>,
<literal>NULL</literal> 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">g_get_current_time</link>()
and <link linkend="g-time-val-add">g_time_val_add</link>() can be used.</para>
<informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>queue</parameter>&nbsp;:</entry>
<entry> a <link linkend="GAsyncQueue">GAsyncQueue</link>.
</entry></row>
<row><entry align="right"><parameter>end_time</parameter>&nbsp;:</entry>
<entry> a <link linkend="GTimeVal">GTimeVal</link>, determining the final time.
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry> data from the queue or <literal>NULL</literal>, when no data is
received before <parameter>end_time</parameter>.
</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-async-queue-length-unlocked">g_async_queue_length_unlocked ()</title>
<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>
<informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>queue</parameter>&nbsp;:</entry>
<entry> a <link linkend="GAsyncQueue">GAsyncQueue</link>.
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry> the length of the <parameter>queue</parameter>.
</entry></row>
</tbody></tgroup></informaltable></refsect2>

</refsect1>




</refentry>