docs/reference/glib/tmpl/async_queues.sgml

<!-- ##### SECTION Title ##### -->
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 ##### -->
<para>

</para>

<!-- ##### SECTION Stability_Level ##### -->


<!-- ##### 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>


<!-- ##### FUNCTION g_async_queue_new ##### -->


@Returns: 


<!-- ##### FUNCTION g_async_queue_ref ##### -->


@queue: 
@Returns: 


<!-- ##### FUNCTION g_async_queue_unref ##### -->


@queue: 


<!-- ##### FUNCTION g_async_queue_push ##### -->


@queue: 
@data: 


<!-- ##### FUNCTION g_async_queue_push_sorted ##### -->
<para>

</para>

@queue: 
@data: 
@func: 
@user_data: 


<!-- ##### FUNCTION g_async_queue_pop ##### -->


@queue: 
@Returns: 


<!-- ##### FUNCTION g_async_queue_try_pop ##### -->


@queue: 
@Returns: 


<!-- ##### FUNCTION g_async_queue_timed_pop ##### -->


@queue: 
@end_time: 
@Returns: 


<!-- ##### FUNCTION g_async_queue_length ##### -->


@queue: 
@Returns: 


<!-- ##### FUNCTION g_async_queue_sort ##### -->
<para>

</para>

@queue: 
@func: 
@user_data: 


<!-- ##### FUNCTION g_async_queue_lock ##### -->


@queue: 


<!-- ##### FUNCTION g_async_queue_unlock ##### -->


@queue: 


<!-- ##### FUNCTION g_async_queue_ref_unlocked ##### -->


@queue: 


<!-- ##### FUNCTION g_async_queue_unref_and_unlock ##### -->


@queue: 


<!-- ##### FUNCTION g_async_queue_push_unlocked ##### -->


@queue: 
@data: 


<!-- ##### FUNCTION g_async_queue_push_sorted_unlocked ##### -->
<para>

</para>

@queue: 
@data: 
@func: 
@user_data: 


<!-- ##### FUNCTION g_async_queue_pop_unlocked ##### -->


@queue: 
@Returns: 


<!-- ##### FUNCTION g_async_queue_try_pop_unlocked ##### -->


@queue: 
@Returns: 


<!-- ##### FUNCTION g_async_queue_timed_pop_unlocked ##### -->


@queue: 
@end_time: 
@Returns: 


<!-- ##### FUNCTION g_async_queue_length_unlocked ##### -->


@queue: 
@Returns: 


<!-- ##### FUNCTION g_async_queue_sort_unlocked ##### -->
<para>

</para>

@queue: 
@func: 
@user_data: