Move GAsyncQueue docs inline

This commit is contained in:
Matthias Clasen 2010-07-10 21:26:28 -04:00
parent db0c58062d
commit e8503fddee
2 changed files with 55 additions and 53 deletions

View File

@ -2,60 +2,11 @@
Asynchronous Queues
<!-- ##### SECTION Short_Description ##### -->
asynchronous communication between threads
<!-- ##### SECTION Long_Description ##### -->
<para>
Often you need to communicate between different threads. In general
it's safer not to do this by shared memory, but by explicit message
passing. These messages only make sense asynchronously for
multi-threaded applications though, as a synchronous operation could as
well be done in the same thread.
</para>
<para>
Asynchronous queues are an exception from most other GLib data
structures, as they can be used simultaneously from multiple threads
without explicit locking and they bring their own builtin reference
counting. This is because the nature of an asynchronous queue is that
it will always be used by at least 2 concurrent threads.
</para>
<para>
For using an asynchronous queue you first have to create one with
g_async_queue_new(). A newly-created queue will get the reference
count 1. Whenever another thread is creating a new reference of (that
is, pointer to) the queue, it has to increase the reference count
(using g_async_queue_ref()). Also, before removing this reference, the
reference count has to be decreased (using
g_async_queue_unref()). After that the queue might no longer exist so
you must not access it after that point.
</para>
<para>
A thread, which wants to send a message to that queue simply calls
g_async_queue_push() to push the message to the queue.
</para>
<para>
A thread, which is expecting messages from an asynchronous queue
simply calls g_async_queue_pop() for that queue. If no message is
available in the queue at that point, the thread is now put to sleep
until a message arrives. The message will be removed from the queue
and returned. The functions g_async_queue_try_pop() and
g_async_queue_timed_pop() can be used to only check for the presence
of messages or to only wait a certain time for messages respectively.
</para>
<para>
For almost every function there exist two variants, one that locks the
queue and one that doesn't. That way you can hold the queue lock
(acquire it with g_async_queue_lock() and release it with
g_async_queue_unlock()) over multiple queue accessing
instructions. This can be necessary to ensure the integrity of the
queue, but should only be used when really necessary, as it can make
your life harder if used unwisely. Normally you should only use the
locking function variants (those without the suffix _unlocked)
</para>
<!-- ##### SECTION See_Also ##### -->
@ -71,9 +22,7 @@ locking function variants (those without the suffix _unlocked)
<!-- ##### STRUCT GAsyncQueue ##### -->
<para>
The #GAsyncQueue struct is an opaque data structure, which represents
an asynchronous queue. It should only be accessed through the
<function>g_async_queue_*</function> functions.
</para>

View File

@ -34,7 +34,60 @@
#include "gthread.h"
/**
* SECTION: async_queues
* @title: Asynchronous Queues
* @short_description: asynchronous communication between threads
*
* Often you need to communicate between different threads. In general
* it's safer not to do this by shared memory, but by explicit message
* passing. These messages only make sense asynchronously for
* multi-threaded applications though, as a synchronous operation could
* as well be done in the same thread.
*
* Asynchronous queues are an exception from most other GLib data
* structures, as they can be used simultaneously from multiple threads
* without explicit locking and they bring their own builtin reference
* counting. This is because the nature of an asynchronous queue is that
* it will always be used by at least 2 concurrent threads.
*
* For using an asynchronous queue you first have to create one with
* g_async_queue_new(). A newly-created queue will get the reference
* count 1. Whenever another thread is creating a new reference of (that
* is, pointer to) the queue, it has to increase the reference count
* (using g_async_queue_ref()). Also, before removing this reference,
* the reference count has to be decreased (using g_async_queue_unref()).
* After that the queue might no longer exist so you must not access
* it after that point.
*
* A thread, which wants to send a message to that queue simply calls
* g_async_queue_push() to push the message to the queue.
*
* A thread, which is expecting messages from an asynchronous queue
* simply calls g_async_queue_pop() for that queue. If no message is
* available in the queue at that point, the thread is now put to sleep
* until a message arrives. The message will be removed from the queue
* and returned. The functions g_async_queue_try_pop() and
* g_async_queue_timed_pop() can be used to only check for the presence
* of messages or to only wait a certain time for messages respectively.
*
* For almost every function there exist two variants, one that locks
* the queue and one that doesn't. That way you can hold the queue lock
* (acquire it with g_async_queue_lock() and release it with
* g_async_queue_unlock()) over multiple queue accessing instructions.
* This can be necessary to ensure the integrity of the queue, but should
* only be used when really necessary, as it can make your life harder
* if used unwisely. Normally you should only use the locking function
* variants (those without the suffix _unlocked)
*/
/**
* GAsyncQueue:
*
* The GAsyncQueue struct is an opaque data structure, which represents
* an asynchronous queue. It should only be accessed through the
* <function>g_async_queue_*</function> functions.
*/
struct _GAsyncQueue
{
GMutex *mutex;