?? glib-asynchronous-queues.html
字號:
<html xmlns:cf="http://docbook.sourceforge.net/xmlns/chunkfast/1.0"><head><meta http-equiv="Content-Type" content="text/html; charset=US-ASCII"><title>Asynchronous Queues</title><meta name="generator" content="DocBook XSL Stylesheets V1.69.0"><link rel="start" href="index.html" title="GLib Reference Manual"><link rel="up" href="glib-core.html" title="GLib Core Application Support"><link rel="prev" href="glib-Thread-Pools.html" title="Thread Pools"><link rel="next" href="glib-Dynamic-Loading-of-Modules.html" title="Dynamic Loading of Modules"><meta name="generator" content="GTK-Doc V1.4 (XML mode)"><link rel="stylesheet" href="style.css" type="text/css"><link rel="chapter" href="glib.html" title="GLib Overview"><link rel="chapter" href="glib-fundamentals.html" title="GLib Fundamentals"><link rel="chapter" href="glib-core.html" title="GLib Core Application Support"><link rel="chapter" href="glib-utilities.html" title="GLib Utilities"><link rel="chapter" href="glib-data-types.html" title="GLib Data Types"><link rel="chapter" href="tools.html" title="GLib Tools"><link rel="index" href="ix01.html" title="Index"><link rel="index" href="ix02.html" title="Index of deprecated symbols"><link rel="index" href="ix03.html" title="Index of new symbols in 2.2"><link rel="index" href="ix04.html" title="Index of new symbols in 2.4"><link rel="index" href="ix05.html" title="Index of new symbols in 2.6"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><table class="navigation" width="100%" summary="Navigation header" cellpadding="2" cellspacing="2"><tr valign="middle"><td><a accesskey="p" href="glib-Thread-Pools.html"><img src="left.png" width="24" height="24" border="0" alt="Prev"></a></td><td><a accesskey="u" href="glib-core.html"><img src="up.png" width="24" height="24" border="0" alt="Up"></a></td><td><a accesskey="h" href="index.html"><img src="home.png" width="24" height="24" border="0" alt="Home"></a></td><th width="100%" align="center">GLib Reference Manual</th><td><a accesskey="n" href="glib-Dynamic-Loading-of-Modules.html"><img src="right.png" width="24" height="24" border="0" alt="Next"></a></td></tr></table><div class="refentry" lang="en"><a name="glib-Asynchronous-Queues"></a><div class="titlepage"></div><div class="refnamediv"><table width="100%"><tr><td valign="top"><h2><span class="refentrytitle">Asynchronous Queues</span></h2><p>Asynchronous Queues — asynchronous communication between threads.</p></td><td valign="top" align="right"></td></tr></table></div><div class="refsynopsisdiv"><h2>Synopsis</h2><pre class="synopsis">#include <glib.h> <a href="glib-Asynchronous-Queues.html#GAsyncQueue">GAsyncQueue</a>;<a href="glib-Asynchronous-Queues.html#GAsyncQueue">GAsyncQueue</a>* <a href="glib-Asynchronous-Queues.html#g-async-queue-new">g_async_queue_new</a> (void);<a href="glib-Asynchronous-Queues.html#GAsyncQueue">GAsyncQueue</a>* <a href="glib-Asynchronous-Queues.html#g-async-queue-ref">g_async_queue_ref</a> (<a href="glib-Asynchronous-Queues.html#GAsyncQueue">GAsyncQueue</a> *queue);void <a href="glib-Asynchronous-Queues.html#g-async-queue-unref">g_async_queue_unref</a> (<a href="glib-Asynchronous-Queues.html#GAsyncQueue">GAsyncQueue</a> *queue);void <a href="glib-Asynchronous-Queues.html#g-async-queue-push">g_async_queue_push</a> (<a href="glib-Asynchronous-Queues.html#GAsyncQueue">GAsyncQueue</a> *queue, <a href="glib-Basic-Types.html#gpointer">gpointer</a> data);<a href="glib-Basic-Types.html#gpointer">gpointer</a> <a href="glib-Asynchronous-Queues.html#g-async-queue-pop">g_async_queue_pop</a> (<a href="glib-Asynchronous-Queues.html#GAsyncQueue">GAsyncQueue</a> *queue);<a href="glib-Basic-Types.html#gpointer">gpointer</a> <a href="glib-Asynchronous-Queues.html#g-async-queue-try-pop">g_async_queue_try_pop</a> (<a href="glib-Asynchronous-Queues.html#GAsyncQueue">GAsyncQueue</a> *queue);<a href="glib-Basic-Types.html#gpointer">gpointer</a> <a href="glib-Asynchronous-Queues.html#g-async-queue-timed-pop">g_async_queue_timed_pop</a> (<a href="glib-Asynchronous-Queues.html#GAsyncQueue">GAsyncQueue</a> *queue, <a href="glib-Date-and-Time-Functions.html#GTimeVal">GTimeVal</a> *end_time);<a href="glib-Basic-Types.html#gint">gint</a> <a href="glib-Asynchronous-Queues.html#g-async-queue-length">g_async_queue_length</a> (<a href="glib-Asynchronous-Queues.html#GAsyncQueue">GAsyncQueue</a> *queue);void <a href="glib-Asynchronous-Queues.html#g-async-queue-lock">g_async_queue_lock</a> (<a href="glib-Asynchronous-Queues.html#GAsyncQueue">GAsyncQueue</a> *queue);void <a href="glib-Asynchronous-Queues.html#g-async-queue-unlock">g_async_queue_unlock</a> (<a href="glib-Asynchronous-Queues.html#GAsyncQueue">GAsyncQueue</a> *queue);void <a href="glib-Asynchronous-Queues.html#g-async-queue-ref-unlocked">g_async_queue_ref_unlocked</a> (<a href="glib-Asynchronous-Queues.html#GAsyncQueue">GAsyncQueue</a> *queue);void <a href="glib-Asynchronous-Queues.html#g-async-queue-unref-and-unlock">g_async_queue_unref_and_unlock</a> (<a href="glib-Asynchronous-Queues.html#GAsyncQueue">GAsyncQueue</a> *queue);void <a href="glib-Asynchronous-Queues.html#g-async-queue-push-unlocked">g_async_queue_push_unlocked</a> (<a href="glib-Asynchronous-Queues.html#GAsyncQueue">GAsyncQueue</a> *queue, <a href="glib-Basic-Types.html#gpointer">gpointer</a> data);<a href="glib-Basic-Types.html#gpointer">gpointer</a> <a href="glib-Asynchronous-Queues.html#g-async-queue-pop-unlocked">g_async_queue_pop_unlocked</a> (<a href="glib-Asynchronous-Queues.html#GAsyncQueue">GAsyncQueue</a> *queue);<a href="glib-Basic-Types.html#gpointer">gpointer</a> <a href="glib-Asynchronous-Queues.html#g-async-queue-try-pop-unlocked">g_async_queue_try_pop_unlocked</a> (<a href="glib-Asynchronous-Queues.html#GAsyncQueue">GAsyncQueue</a> *queue);<a href="glib-Basic-Types.html#gpointer">gpointer</a> <a href="glib-Asynchronous-Queues.html#g-async-queue-timed-pop-unlocked">g_async_queue_timed_pop_unlocked</a> (<a href="glib-Asynchronous-Queues.html#GAsyncQueue">GAsyncQueue</a> *queue, <a href="glib-Date-and-Time-Functions.html#GTimeVal">GTimeVal</a> *end_time);<a href="glib-Basic-Types.html#gint">gint</a> <a href="glib-Asynchronous-Queues.html#g-async-queue-length-unlocked">g_async_queue_length_unlocked</a> (<a href="glib-Asynchronous-Queues.html#GAsyncQueue">GAsyncQueue</a> *queue);</pre></div><div class="refsect1" lang="en"><a name="id2894440"></a><h2>Description</h2><p>Often you need to communicate between different threads. In generalit's safer not to do this by shared memory, but by explicit messagepassing. These messages only make sense asynchronously formulti-threaded applications though, as a synchronous operation could aswell be done in the same thread.</p><p>Asynchronous queues are an exception from most other GLib datastructures, as they can be used simultaneously from multiple threadswithout explicit locking and they bring their own builtin referencecounting. This is because the nature of an asynchronous queue is thatit will always be used by at least 2 concurrent threads.</p><p>For using an asynchronous queue you first have to create one with<a href="glib-Asynchronous-Queues.html#g-async-queue-new"><code class="function">g_async_queue_new()</code></a>. A newly-created queue will get the referencecount 1. Whenever another thread is creating a new reference of (thatis, pointer to) the queue, it has to increase the reference count(using <a href="glib-Asynchronous-Queues.html#g-async-queue-ref"><code class="function">g_async_queue_ref()</code></a>). Also, before removing this reference, thereference count has to be decreased (using<a href="glib-Asynchronous-Queues.html#g-async-queue-unref"><code class="function">g_async_queue_unref()</code></a>). After that the queue might no longer exist soyou must not access it after that point.</p><p>A thread, which wants to send a message to that queue simply calls<a href="glib-Asynchronous-Queues.html#g-async-queue-push"><code class="function">g_async_queue_push()</code></a> to push the message to the queue.</p><p>A thread, which is expecting messages from an asynchronous queuesimply calls <a href="glib-Asynchronous-Queues.html#g-async-queue-pop"><code class="function">g_async_queue_pop()</code></a> for that queue. If no message isavailable in the queue at that point, the thread is now put to sleepuntil a message arrives. The message will be removed from the queueand returned. The functions <a href="glib-Asynchronous-Queues.html#g-async-queue-try-pop"><code class="function">g_async_queue_try_pop()</code></a> and<a href="glib-Asynchronous-Queues.html#g-async-queue-timed-pop"><code class="function">g_async_queue_timed_pop()</code></a> can be used to only check for the presenceof messages or to only wait a certain time for messages respectively.</p><p>For almost every function there exist two variants, one that locks thequeue and one that doesn't. That way you can hold the queue lock(acquire it with <a href="glib-Asynchronous-Queues.html#g-async-queue-lock"><code class="function">g_async_queue_lock()</code></a> and release it with<a href="glib-Asynchronous-Queues.html#g-async-queue-unlock"><code class="function">g_async_queue_unlock()</code></a>) over multiple queue accessinginstructions. This can be necessary to ensure the integrity of thequeue, but should only be used when really necessary, as it can makeyour life harder if used unwisely. Normally you should only use thelocking function variants (those without the suffix _unlocked)</p></div><div class="refsect1" lang="en"><a name="id2894597"></a><h2>Details</h2><div class="refsect2" lang="en"><a name="id2894603"></a><h3><a name="GAsyncQueue"></a>GAsyncQueue</h3><a class="indexterm" name="id2894612"></a><pre class="programlisting">typedef struct _GAsyncQueue GAsyncQueue;</pre><p>The <a href="glib-Asynchronous-Queues.html#GAsyncQueue"><span class="type">GAsyncQueue</span></a> struct is an opaque data structure, which representsan asynchronous queue. It should only be accessed through the<code class="function">g_async_queue_*</code> functions.</p></div><hr><div class="refsect2" lang="en"><a name="id2894644"></a><h3><a name="g-async-queue-new"></a>g_async_queue_new ()</h3><a class="indexterm" name="id2894655"></a><pre class="programlisting"><a href="glib-Asynchronous-Queues.html#GAsyncQueue">GAsyncQueue</a>* g_async_queue_new (void);</pre><p>Creates a new asynchronous queue with the initial reference count of 1.</p><div class="variablelist"><table border="0"><col align="left" valign="top"><tbody><tr><td><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></td><td> the new <a href="glib-Asynchronous-Queues.html#GAsyncQueue"><span class="type">GAsyncQueue</span></a>.</td></tr></tbody></table></div></div><hr><div class="refsect2" lang="en"><a name="id2894701"></a><h3><a name="g-async-queue-ref"></a>g_async_queue_ref ()</h3><a class="indexterm" name="id2894712"></a><pre class="programlisting"><a href="glib-Asynchronous-Queues.html#GAsyncQueue">GAsyncQueue</a>* g_async_queue_ref (<a href="glib-Asynchronous-Queues.html#GAsyncQueue">GAsyncQueue</a> *queue);</pre><p>Increases the reference count of the asynchronous <em class="parameter"><code>queue</code></em> by 1. Youdo not need to hold the lock to call this function.</p><div class="variablelist"><table border="0"><col align="left" valign="top"><tbody><tr><td><span class="term"><em class="parameter"><code>queue</code></em> :</span></td><td> a <a href="glib-Asynchronous-Queues.html#GAsyncQueue"><span class="type">GAsyncQueue</span></a>.</td></tr><tr><td><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></td><td> the <em class="parameter"><code>queue</code></em> that was passed in (since 2.6)</td></tr></tbody></table></div></div><hr><div class="refsect2" lang="en"><a name="id2894790"></a><h3><a name="g-async-queue-unref"></a>g_async_queue_unref ()</h3><a class="indexterm" name="id2894802"></a><pre class="programlisting">void g_async_queue_unref (<a href="glib-Asynchronous-Queues.html#GAsyncQueue">GAsyncQueue</a> *queue);</pre><p>Decreases the reference count of the asynchronous <em class="parameter"><code>queue</code></em> by 1. Ifthe reference count went to 0, the <em class="parameter"><code>queue</code></em> will be destroyed and thememory allocated will be freed. So you are not allowed to use the<em class="parameter"><code>queue</code></em> afterwards, as it might have disappeared. You do not need tohold the lock to call this function.</p><div class="variablelist"><table border="0"><col align="left" valign="top"><tbody><tr><td><span class="term"><em class="parameter"><code>queue</code></em> :</span></td><td> a <a href="glib-Asynchronous-Queues.html#GAsyncQueue"><span class="type">GAsyncQueue</span></a>.</td></tr></tbody>?? 快捷鍵說明
復制代碼
Ctrl + C
搜索代碼
Ctrl + F
全屏模式
F11
切換主題
Ctrl + Shift + D
顯示快捷鍵
?
增大字號
Ctrl + =
減小字號
Ctrl + -