From e8503fddee2c5426a98d066c5a24afd9ae7ade50 Mon Sep 17 00:00:00 2001 From: Matthias Clasen Date: Sat, 10 Jul 2010 21:26:28 -0400 Subject: [PATCH] Move GAsyncQueue docs inline --- docs/reference/glib/tmpl/async_queues.sgml | 55 ++---------------------------- glib/gasyncqueue.c | 53 ++++++++++++++++++++++++++++ 2 files changed, 55 insertions(+), 53 deletions(-) diff --git a/docs/reference/glib/tmpl/async_queues.sgml b/docs/reference/glib/tmpl/async_queues.sgml index 7a58f3e..2292472 100644 --- a/docs/reference/glib/tmpl/async_queues.sgml +++ b/docs/reference/glib/tmpl/async_queues.sgml @@ -2,60 +2,11 @@ Asynchronous Queues -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) @@ -71,9 +22,7 @@ locking function variants (those without the suffix _unlocked) -The #GAsyncQueue struct is an opaque data structure, which represents -an asynchronous queue. It should only be accessed through the -g_async_queue_* functions. + diff --git a/glib/gasyncqueue.c b/glib/gasyncqueue.c index 312bf8a..222ef06 100644 --- a/glib/gasyncqueue.c +++ b/glib/gasyncqueue.c @@ -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 + * g_async_queue_* functions. + */ struct _GAsyncQueue { GMutex *mutex; -- 2.7.4