mirror of
https://gitlab.gnome.org/GNOME/glib.git
synced 2025-07-29 13:23:31 +02:00
Added documentation for asynchronous queues.
2000-11-02 Sebastian Wilhelmi <wilhelmi@ira.uka.de> * glib/tmpl/async_queues.sgml, glib/glib-sections.txt: Added documentation for asynchronous queues. * gasyncqueue.c: Added inline documentation for asyncronous queues.
This commit is contained in:
Sebastian Wilhelmi
committed by
Sebastian Wilhelmi
Sebastian Wilhelmi
parent
1d126e44f2
commit
91b9b2dd12
@@ -1,3 +1,8 @@
|
||||
2000-11-02 Sebastian Wilhelmi <wilhelmi@ira.uka.de>
|
||||
|
||||
* glib/tmpl/async_queues.sgml, glib/glib-sections.txt: Added
|
||||
documentation for asynchronous queues.
|
||||
|
||||
2000-10-31 Sebastian Wilhelmi <wilhelmi@ira.uka.de>
|
||||
|
||||
* glib/tmpl/linked_lists_single.sgml: This time the right fix.
|
||||
|
||||
@@ -513,21 +513,23 @@ g_thread_pool_stop_unused_threads
|
||||
<FILE>async_queues</FILE>
|
||||
GAsyncQueue
|
||||
g_async_queue_new
|
||||
g_async_queue_ref
|
||||
g_async_queue_unref
|
||||
g_async_queue_push
|
||||
g_async_queue_pop
|
||||
g_async_queue_try_pop
|
||||
g_async_queue_timed_pop
|
||||
g_async_queue_length
|
||||
|
||||
<SUBSECTION>
|
||||
g_async_queue_lock
|
||||
g_async_queue_unlock
|
||||
g_async_queue_ref
|
||||
g_async_queue_ref_unlocked
|
||||
g_async_queue_unref
|
||||
g_async_queue_unref_and_unlock
|
||||
g_async_queue_push
|
||||
g_async_queue_push_unlocked
|
||||
g_async_queue_pop
|
||||
g_async_queue_pop_unlocked
|
||||
g_async_queue_try_pop
|
||||
g_async_queue_try_pop_unlocked
|
||||
g_async_queue_timed_pop
|
||||
g_async_queue_timed_pop_unlocked
|
||||
g_async_queue_length
|
||||
g_async_queue_length_unlocked
|
||||
</SECTION>
|
||||
|
||||
|
||||
@@ -2,11 +2,60 @@
|
||||
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 _unlocking)
|
||||
</para>
|
||||
|
||||
<!-- ##### SECTION See_Also ##### -->
|
||||
@@ -16,134 +65,53 @@ Asynchronous Queues
|
||||
|
||||
<!-- ##### STRUCT GAsyncQueue ##### -->
|
||||
<para>
|
||||
|
||||
The #GAsyncQueue struct is an opaque data structure, which represents
|
||||
an asynchronous queue. It should only be accessed through the
|
||||
g_async_queue_* functions.
|
||||
</para>
|
||||
|
||||
|
||||
<!-- ##### FUNCTION g_async_queue_new ##### -->
|
||||
<para>
|
||||
|
||||
</para>
|
||||
|
||||
@Returns:
|
||||
|
||||
|
||||
<!-- ##### FUNCTION g_async_queue_lock ##### -->
|
||||
<para>
|
||||
|
||||
</para>
|
||||
|
||||
@queue:
|
||||
|
||||
|
||||
<!-- ##### FUNCTION g_async_queue_unlock ##### -->
|
||||
<para>
|
||||
|
||||
</para>
|
||||
|
||||
@queue:
|
||||
|
||||
|
||||
<!-- ##### FUNCTION g_async_queue_ref ##### -->
|
||||
<para>
|
||||
|
||||
</para>
|
||||
|
||||
@queue:
|
||||
|
||||
|
||||
<!-- ##### FUNCTION g_async_queue_ref_unlocked ##### -->
|
||||
<para>
|
||||
|
||||
</para>
|
||||
|
||||
@queue:
|
||||
|
||||
|
||||
<!-- ##### FUNCTION g_async_queue_unref ##### -->
|
||||
<para>
|
||||
|
||||
</para>
|
||||
|
||||
@queue:
|
||||
|
||||
|
||||
<!-- ##### FUNCTION g_async_queue_unref_and_unlock ##### -->
|
||||
<para>
|
||||
|
||||
</para>
|
||||
|
||||
@queue:
|
||||
|
||||
|
||||
<!-- ##### FUNCTION g_async_queue_push ##### -->
|
||||
<para>
|
||||
|
||||
</para>
|
||||
|
||||
@queue:
|
||||
@data:
|
||||
|
||||
|
||||
<!-- ##### FUNCTION g_async_queue_push_unlocked ##### -->
|
||||
<para>
|
||||
|
||||
</para>
|
||||
|
||||
@queue:
|
||||
@data:
|
||||
|
||||
|
||||
<!-- ##### FUNCTION g_async_queue_pop ##### -->
|
||||
<para>
|
||||
|
||||
</para>
|
||||
|
||||
@queue:
|
||||
@Returns:
|
||||
|
||||
|
||||
<!-- ##### FUNCTION g_async_queue_pop_unlocked ##### -->
|
||||
<para>
|
||||
|
||||
</para>
|
||||
|
||||
@queue:
|
||||
@Returns:
|
||||
|
||||
|
||||
<!-- ##### FUNCTION g_async_queue_try_pop ##### -->
|
||||
<para>
|
||||
|
||||
</para>
|
||||
|
||||
@queue:
|
||||
@Returns:
|
||||
|
||||
|
||||
<!-- ##### FUNCTION g_async_queue_try_pop_unlocked ##### -->
|
||||
<para>
|
||||
|
||||
</para>
|
||||
|
||||
@queue:
|
||||
@Returns:
|
||||
|
||||
|
||||
<!-- ##### FUNCTION g_async_queue_timed_pop ##### -->
|
||||
<para>
|
||||
|
||||
</para>
|
||||
|
||||
@queue:
|
||||
@end_time:
|
||||
@Returns:
|
||||
|
||||
|
||||
<!-- ##### FUNCTION g_async_queue_timed_pop_unlocked ##### -->
|
||||
<para>
|
||||
|
||||
</para>
|
||||
|
||||
@queue:
|
||||
@end_time:
|
||||
@@ -151,18 +119,67 @@ Asynchronous Queues
|
||||
|
||||
|
||||
<!-- ##### FUNCTION g_async_queue_length ##### -->
|
||||
<para>
|
||||
|
||||
</para>
|
||||
|
||||
@queue:
|
||||
@Returns:
|
||||
|
||||
|
||||
<!-- ##### 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_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 ##### -->
|
||||
<para>
|
||||
|
||||
</para>
|
||||
|
||||
@queue:
|
||||
@Returns:
|
||||
|
||||
Reference in New Issue
Block a user