luc14n0/glib
1
0
Fork 0
mirror of https://gitlab.gnome.org/GNOME/glib.git synced 2025-06-05 20:30:07 +02:00
Code Issues Packages Projects Releases Wiki Activity

GAsyncQueue: Cosmetic fixes

Browse Source 
Mostly doc formatting and whitespace fixes.
This commit is contained in:
Matthias Clasen 2011-10-01 19:24:24 -04:00
parent 93abf20d3b
commit ef08aa786b
2 changed files with 280 additions and 284 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

408
glib/gasyncqueue.c
View File

@ -1,7 +1,7 @@
/* GLIB - Library of useful routines for C programming /* GLIB - Library of useful routines for C programming
* Copyright (C) 1995-1997 Peter Mattis, Spencer Kimball and Josh MacDonald * Copyright (C) 1995-1997 Peter Mattis, Spencer Kimball and Josh MacDonald
* *
* GAsyncQueue: asynchronous queue implementation, based on Gqueue. * GAsyncQueue: asynchronous queue implementation, based on GQueue.
* Copyright (C) 2000 Sebastian Wilhelmi; University of Karlsruhe * Copyright (C) 2000 Sebastian Wilhelmi; University of Karlsruhe
* *
* This library is free software; you can redistribute it and/or * This library is free software; you can redistribute it and/or
@ -39,6 +39,7 @@
* SECTION:async_queues * SECTION:async_queues
* @title: Asynchronous Queues * @title: Asynchronous Queues
* @short_description: asynchronous communication between threads * @short_description: asynchronous communication between threads
* @see_also: #GThreadPool
* *
* Often you need to communicate between different threads. In general * Often you need to communicate between different threads. In general
* it's safer not to do this by shared memory, but by explicit message * it's safer not to do this by shared memory, but by explicit message
@ -53,18 +54,14 @@
* it will always be used by at least 2 concurrent threads. * it will always be used by at least 2 concurrent threads.
* *
* For using an asynchronous queue you first have to create one with * For using an asynchronous queue you first have to create one with
* g_async_queue_new(). A newly-created queue will get the reference * g_async_queue_new(). #GAsyncQueue structs are reference counted,
* count 1. Whenever another thread is creating a new reference of (that * use g_async_queue_ref() and g_async_queue_unref() to manage your
* is, pointer to) the queue, it has to increase the reference count * references.
* (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 * A thread which wants to send a message to that queue simply calls
* g_async_queue_push() to push the message to the queue. * g_async_queue_push() to push the message to the queue.
* *
* A thread, which is expecting messages from an asynchronous queue * A thread which is expecting messages from an asynchronous queue
* simply calls g_async_queue_pop() for that queue. If no message is * 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 * 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 * until a message arrives. The message will be removed from the queue
@ -79,13 +76,18 @@
* This can be necessary to ensure the integrity of the queue, but should * 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 * only be used when really necessary, as it can make your life harder
* if used unwisely. Normally you should only use the locking function * if used unwisely. Normally you should only use the locking function
* variants (those without the suffix _unlocked) * variants (those without the _unlocked suffix).
*
* In many cases, it may be more convenient to use #GThreadPool when
* you need to distribute work to a set of worker threads instead of
* using #GAsyncQueue manually. #GThreadPool uses a GAsyncQueue
* internally.
*/ */
/** /**
* GAsyncQueue: * GAsyncQueue:
* *
* The GAsyncQueue struct is an opaque data structure, which represents * The GAsyncQueue struct is an opaque data structure which represents
* an asynchronous queue. It should only be accessed through the * an asynchronous queue. It should only be accessed through the
* <function>g_async_queue_*</function> functions. * <function>g_async_queue_*</function> functions.
*/ */
@ -99,7 +101,8 @@ struct _GAsyncQueue
gint ref_count; gint ref_count;
}; };
typedef struct { typedef struct
{
GCompareDataFunc func; GCompareDataFunc func;
gpointer user_data; gpointer user_data;
} SortData; } SortData;
@ -107,52 +110,53 @@ typedef struct {
/** /**
* g_async_queue_new: * g_async_queue_new:
* *
* Creates a new asynchronous queue with the initial reference count of 1. * Creates a new asynchronous queue.
* *
* Return value: the new #GAsyncQueue. * Return value: a new #GAsyncQueue. Free with g_async_queue_unref()
**/ */
GAsyncQueue* GAsyncQueue *
g_async_queue_new (void) g_async_queue_new (void)
{ {
GAsyncQueue* retval = g_new (GAsyncQueue, 1); return g_async_queue_new_full (NULL);
g_mutex_init (&retval->mutex);
retval->cond = NULL;
g_queue_init (&retval->queue);
retval->waiting_threads = 0;
retval->ref_count = 1;
retval->item_free_func = NULL;
return retval;
} }
/** /**
* g_async_queue_new_full: * g_async_queue_new_full:
* @item_free_func: function to free queue elements * @item_free_func: function to free queue elements
* *
* Creates a new asynchronous queue with an initial reference count of 1 and * Creates a new asynchronous queue and sets up a destroy notify
* sets up a destroy notify function that is used to free any remaining * function that is used to free any remaining queue items when
* queue items when the queue is destroyed after the final unref. * the queue is destroyed after the final unref.
* *
* Return value: the new #GAsyncQueue. * Return value: a new #GAsyncQueue. Free with g_async_queue_unref()
* *
* Since: 2.16 * Since: 2.16
**/ */
GAsyncQueue* GAsyncQueue *
g_async_queue_new_full (GDestroyNotify item_free_func) g_async_queue_new_full (GDestroyNotify item_free_func)
{ {
GAsyncQueue *async_queue = g_async_queue_new (); GAsyncQueue *queue;
async_queue->item_free_func = item_free_func;
return async_queue; queue = g_new (GAsyncQueue, 1);
g_mutex_init (&queue->mutex);
queue->cond = NULL;
g_queue_init (&queue->queue);
queue->waiting_threads = 0;
queue->ref_count = 1;
queue->item_free_func = NULL;
return queue;
} }
/** /**
* g_async_queue_ref: * g_async_queue_ref:
* @queue: a #GAsyncQueue. * @queue: a #GAsyncQueue
* *
* Increases the reference count of the asynchronous @queue by 1. You * Increases the reference count of the asynchronous @queue by 1.
* do not need to hold the lock to call this function. * You do not need to hold the lock to call this function.
* *
* Returns: the @queue that was passed in (since 2.6) * Returns: the @queue that was passed in (since 2.6)
**/ */
GAsyncQueue * GAsyncQueue *
g_async_queue_ref (GAsyncQueue *queue) g_async_queue_ref (GAsyncQueue *queue)
{ {
@ -165,14 +169,14 @@ g_async_queue_ref (GAsyncQueue *queue)
/** /**
* g_async_queue_ref_unlocked: * g_async_queue_ref_unlocked:
* @queue: a #GAsyncQueue. * @queue: a #GAsyncQueue
* *
* Increases the reference count of the asynchronous @queue by 1. * Increases the reference count of the asynchronous @queue by 1.
* *
* @Deprecated: Since 2.8, reference counting is done atomically * @Deprecated: Since 2.8, reference counting is done atomically
* so g_async_queue_ref() can be used regardless of the @queue's * so g_async_queue_ref() can be used regardless of the @queue's
* lock. * lock.
**/ */
void void
g_async_queue_ref_unlocked (GAsyncQueue *queue) g_async_queue_ref_unlocked (GAsyncQueue *queue)
{ {
@ -183,17 +187,17 @@ g_async_queue_ref_unlocked (GAsyncQueue *queue)
/** /**
* g_async_queue_unref_and_unlock: * g_async_queue_unref_and_unlock:
* @queue: a #GAsyncQueue. * @queue: a #GAsyncQueue
* *
* Decreases the reference count of the asynchronous @queue by 1 and * Decreases the reference count of the asynchronous @queue by 1
* releases the lock. This function must be called while holding the * and releases the lock. This function must be called while holding
* @queue's lock. If the reference count went to 0, the @queue will be * the @queue's lock. If the reference count went to 0, the @queue
* destroyed and the memory allocated will be freed. * will be destroyed and the memory allocated will be freed.
* *
* @Deprecated: Since 2.8, reference counting is done atomically * @Deprecated: Since 2.8, reference counting is done atomically
* so g_async_queue_unref() can be used regardless of the @queue's * so g_async_queue_unref() can be used regardless of the @queue's
* lock. * lock.
**/ */
void void
g_async_queue_unref_and_unlock (GAsyncQueue *queue) g_async_queue_unref_and_unlock (GAsyncQueue *queue)
{ {
@ -207,12 +211,13 @@ g_async_queue_unref_and_unlock (GAsyncQueue *queue)
* g_async_queue_unref: * g_async_queue_unref:
* @queue: a #GAsyncQueue. * @queue: a #GAsyncQueue.
* *
* Decreases the reference count of the asynchronous @queue by 1. If * Decreases the reference count of the asynchronous @queue by 1.
* the reference count went to 0, the @queue will be destroyed and the *
* memory allocated will be freed. So you are not allowed to use the * If the reference count went to 0, the @queue will be destroyed
* @queue afterwards, as it might have disappeared. You do not need to * and the memory allocated will be freed. So you are not allowed
* hold the lock to call this function. * to use the @queue afterwards, as it might have disappeared.
**/ * You do not need to hold the lock to call this function.
*/
void void
g_async_queue_unref (GAsyncQueue *queue) g_async_queue_unref (GAsyncQueue *queue)
{ {
@ -223,7 +228,7 @@ g_async_queue_unref (GAsyncQueue *queue)
g_return_if_fail (queue->waiting_threads == 0); g_return_if_fail (queue->waiting_threads == 0);
g_mutex_clear (&queue->mutex); g_mutex_clear (&queue->mutex);
if (queue->cond) if (queue->cond)
g_cond_free (queue->cond); g_cond_free (queue->cond);
if (queue->item_free_func) if (queue->item_free_func)
g_queue_foreach (&queue->queue, (GFunc) queue->item_free_func, NULL); g_queue_foreach (&queue->queue, (GFunc) queue->item_free_func, NULL);
g_queue_clear (&queue->queue); g_queue_clear (&queue->queue);
@ -233,12 +238,18 @@ g_async_queue_unref (GAsyncQueue *queue)
/** /**
* g_async_queue_lock: * g_async_queue_lock:
* @queue: a #GAsyncQueue. * @queue: a #GAsyncQueue
* *
* Acquires the @queue's lock. After that you can only call the * Acquires the @queue's lock. If another thread is already
* <function>g_async_queue_*_unlocked()</function> function variants on that * holding the lock, this call will block until the lock
* @queue. Otherwise it will deadlock. * becomes available.
**/ *
* Call g_async_queue_unlock() to drop the lock again.
*
* While holding the lock, you can only call the
* <function>g_async_queue_*_unlocked()</function> functions
* on @queue. Otherwise, deadlock may occur.
*/
void void
g_async_queue_lock (GAsyncQueue *queue) g_async_queue_lock (GAsyncQueue *queue)
{ {
@ -249,10 +260,14 @@ g_async_queue_lock (GAsyncQueue *queue)
/** /**
* g_async_queue_unlock: * g_async_queue_unlock:
* @queue: a #GAsyncQueue. * @queue: a #GAsyncQueue
* *
* Releases the queue's lock. * Releases the queue's lock.
**/ *
* Calling this function when you have not acquired
* the with g_async_queue_lock() leads to undefined
* behaviour.
*/
void void
g_async_queue_unlock (GAsyncQueue *queue) g_async_queue_unlock (GAsyncQueue *queue)
{ {
@ -263,13 +278,14 @@ g_async_queue_unlock (GAsyncQueue *queue)
/** /**
* g_async_queue_push: * g_async_queue_push:
* @queue: a #GAsyncQueue. * @queue: a #GAsyncQueue
* @data: @data to push into the @queue. * @data: @data to push into the @queue
* *
* Pushes the @data into the @queue. @data must not be %NULL. * Pushes the @data into the @queue. @data must not be %NULL.
**/ */
void void
g_async_queue_push (GAsyncQueue* queue, gpointer data) g_async_queue_push (GAsyncQueue *queue,
gpointer data)
{ {
g_return_if_fail (queue); g_return_if_fail (queue);
g_return_if_fail (data); g_return_if_fail (data);
@ -281,14 +297,16 @@ g_async_queue_push (GAsyncQueue* queue, gpointer data)
/** /**
* g_async_queue_push_unlocked: * g_async_queue_push_unlocked:
* @queue: a #GAsyncQueue. * @queue: a #GAsyncQueue
* @data: @data to push into the @queue. * @data: @data to push into the @queue
* *
* Pushes the @data into the @queue. @data must not be %NULL. This * Pushes the @data into the @queue. @data must not be %NULL.
* function must be called while holding the @queue's lock. *
**/ * This function must be called while holding the @queue's lock.
*/
void void
g_async_queue_push_unlocked (GAsyncQueue* queue, gpointer data) g_async_queue_push_unlocked (GAsyncQueue *queue,
gpointer data)
{ {
g_return_if_fail (queue); g_return_if_fail (queue);
g_return_if_fail (data); g_return_if_fail (data);
@ -302,18 +320,14 @@ g_async_queue_push_unlocked (GAsyncQueue* queue, gpointer data)
* g_async_queue_push_sorted: * g_async_queue_push_sorted:
* @queue: a #GAsyncQueue * @queue: a #GAsyncQueue
* @data: the @data to push into the @queue * @data: the @data to push into the @queue
* @func: the #GCompareDataFunc is used to sort @queue. This function * @func: the #GCompareDataFunc is used to sort @queue
* is passed two elements of the @queue. The function should return
* 0 if they are equal, a negative value if the first element
* should be higher in the @queue or a positive value if the first
* element should be lower in the @queue than the second element.
* @user_data: user data passed to @func. * @user_data: user data passed to @func.
* *
* Inserts @data into @queue using @func to determine the new * Inserts @data into @queue using @func to determine the new
* position. * position.
* *
* This function requires that the @queue is sorted before pushing on * This function requires that the @queue is sorted before pushing on
* new elements. * new elements, see g_async_queue_sort().
* *
* This function will lock @queue before it sorts the queue and unlock * This function will lock @queue before it sorts the queue and unlock
* it when it is finished. * it when it is finished.
@ -321,12 +335,12 @@ g_async_queue_push_unlocked (GAsyncQueue* queue, gpointer data)
* For an example of @func see g_async_queue_sort(). * For an example of @func see g_async_queue_sort().
* *
* Since: 2.10 * Since: 2.10
**/ */
void void
g_async_queue_push_sorted (GAsyncQueue *queue, g_async_queue_push_sorted (GAsyncQueue *queue,
gpointer data, gpointer data,
GCompareDataFunc func, GCompareDataFunc func,
gpointer user_data) gpointer user_data)
{ {
g_return_if_fail (queue != NULL); g_return_if_fail (queue != NULL);
@ -337,8 +351,8 @@ g_async_queue_push_sorted (GAsyncQueue *queue,
static gint static gint
g_async_queue_invert_compare (gpointer v1, g_async_queue_invert_compare (gpointer v1,
gpointer v2, gpointer v2,
SortData *sd) SortData *sd)
{ {
return -sd->func (v1, v2, sd->user_data); return -sd->func (v1, v2, sd->user_data);
} }
@ -347,30 +361,32 @@ g_async_queue_invert_compare (gpointer v1,
* g_async_queue_push_sorted_unlocked: * g_async_queue_push_sorted_unlocked:
* @queue: a #GAsyncQueue * @queue: a #GAsyncQueue
* @data: the @data to push into the @queue * @data: the @data to push into the @queue
* @func: the #GCompareDataFunc is used to sort @queue. This function * @func: the #GCompareDataFunc is used to sort @queue
* is passed two elements of the @queue. The function should return
* 0 if they are equal, a negative value if the first element
* should be higher in the @queue or a positive value if the first
* element should be lower in the @queue than the second element.
* @user_data: user data passed to @func. * @user_data: user data passed to @func.
* *
* Inserts @data into @queue using @func to determine the new * Inserts @data into @queue using @func to determine the new
* position. * position.
* *
* This function requires that the @queue is sorted before pushing on * The sort function @func is passed two elements of the @queue.
* new elements. * It should return 0 if they are equal, a negative value if the
* first element should be higher in the @queue or a positive value
* if the first element should be lower in the @queue than the second
* element.
* *
* This function is called while holding the @queue's lock. * This function requires that the @queue is sorted before pushing on
* new elements, see g_async_queue_sort().
*
* This function must be called while holding the @queue's lock.
* *
* For an example of @func see g_async_queue_sort(). * For an example of @func see g_async_queue_sort().
* *
* Since: 2.10 * Since: 2.10
**/ */
void void
g_async_queue_push_sorted_unlocked (GAsyncQueue *queue, g_async_queue_push_sorted_unlocked (GAsyncQueue *queue,
gpointer data, gpointer data,
GCompareDataFunc func, GCompareDataFunc func,
gpointer user_data) gpointer user_data)
{ {
SortData sd; SortData sd;
@ -380,32 +396,32 @@ g_async_queue_push_sorted_unlocked (GAsyncQueue *queue,
sd.user_data = user_data; sd.user_data = user_data;
g_queue_insert_sorted (&queue->queue, g_queue_insert_sorted (&queue->queue,
data, data,
(GCompareDataFunc)g_async_queue_invert_compare, (GCompareDataFunc)g_async_queue_invert_compare,
&sd); &sd);
if (queue->waiting_threads > 0) if (queue->waiting_threads > 0)
g_cond_signal (queue->cond); g_cond_signal (queue->cond);
} }
static gpointer static gpointer
g_async_queue_pop_intern_unlocked (GAsyncQueue *queue, g_async_queue_pop_intern_unlocked (GAsyncQueue *queue,
gboolean try, gboolean try,
GTimeVal *end_time) GTimeVal *end_time)
{ {
gpointer retval; gpointer retval;
if (!g_queue_peek_tail_link (&queue->queue)) if (!g_queue_peek_tail_link (&queue->queue))
{ {
if (try) if (try)
return NULL; return NULL;
if (!queue->cond) if (!queue->cond)
queue->cond = g_cond_new (); queue->cond = g_cond_new ();
if (!end_time) if (!end_time)
{ {
queue->waiting_threads++; queue->waiting_threads++;
while (!g_queue_peek_tail_link (&queue->queue)) while (!g_queue_peek_tail_link (&queue->queue))
g_cond_wait (queue->cond, &queue->mutex); g_cond_wait (queue->cond, &queue->mutex);
queue->waiting_threads--; queue->waiting_threads--;
} }
@ -417,7 +433,7 @@ g_async_queue_pop_intern_unlocked (GAsyncQueue *queue,
break; break;
queue->waiting_threads--; queue->waiting_threads--;
if (!g_queue_peek_tail_link (&queue->queue)) if (!g_queue_peek_tail_link (&queue->queue))
return NULL; return NULL;
} }
} }
@ -430,15 +446,15 @@ g_async_queue_pop_intern_unlocked (GAsyncQueue *queue,
/** /**
* g_async_queue_pop: * g_async_queue_pop:
* @queue: a #GAsyncQueue. * @queue: a #GAsyncQueue
* *
* Pops data from the @queue. This function blocks until data become * Pops data from the @queue. If @queue is empty, this function
* available. * blocks until data becomes available.
* *
* Return value: data from the queue. * Return value: data from the queue
**/ */
gpointer gpointer
g_async_queue_pop (GAsyncQueue* queue) g_async_queue_pop (GAsyncQueue *queue)
{ {
gpointer retval; gpointer retval;
@ -453,16 +469,17 @@ g_async_queue_pop (GAsyncQueue* queue)
/** /**
* g_async_queue_pop_unlocked: * g_async_queue_pop_unlocked:
* @queue: a #GAsyncQueue. * @queue: a #GAsyncQueue
* *
* Pops data from the @queue. This function blocks until data become * Pops data from the @queue. If @queue is empty, this function
* available. This function must be called while holding the @queue's * blocks until data becomes available.
* lock. *
* This function must be called while holding the @queue's lock.
* *
* Return value: data from the queue. * Return value: data from the queue.
**/ */
gpointer gpointer
g_async_queue_pop_unlocked (GAsyncQueue* queue) g_async_queue_pop_unlocked (GAsyncQueue *queue)
{ {
g_return_val_if_fail (queue, NULL); g_return_val_if_fail (queue, NULL);
@ -471,16 +488,16 @@ g_async_queue_pop_unlocked (GAsyncQueue* queue)
/** /**
* g_async_queue_try_pop: * g_async_queue_try_pop:
* @queue: a #GAsyncQueue. * @queue: a #GAsyncQueue
* *
* Tries to pop data from the @queue. If no data is available, %NULL is * Tries to pop data from the @queue. If no data is available,
* returned. * %NULL is returned.
* *
* Return value: data from the queue or %NULL, when no data is * Return value: data from the queue or %NULL, when no data is
* available immediately. * available immediately.
**/ */
gpointer gpointer
g_async_queue_try_pop (GAsyncQueue* queue) g_async_queue_try_pop (GAsyncQueue *queue)
{ {
gpointer retval; gpointer retval;
@ -495,17 +512,18 @@ g_async_queue_try_pop (GAsyncQueue* queue)
/** /**
* g_async_queue_try_pop_unlocked: * g_async_queue_try_pop_unlocked:
* @queue: a #GAsyncQueue. * @queue: a #GAsyncQueue
* *
* Tries to pop data from the @queue. If no data is available, %NULL is * Tries to pop data from the @queue. If no data is available,
* returned. This function must be called while holding the @queue's * %NULL is returned.
* lock. *
* This function must be called while holding the @queue's lock.
* *
* Return value: data from the queue or %NULL, when no data is * Return value: data from the queue or %NULL, when no data is
* available immediately. * available immediately.
**/ */
gpointer gpointer
g_async_queue_try_pop_unlocked (GAsyncQueue* queue) g_async_queue_try_pop_unlocked (GAsyncQueue *queue)
{ {
g_return_val_if_fail (queue, NULL); g_return_val_if_fail (queue, NULL);
@ -514,20 +532,23 @@ g_async_queue_try_pop_unlocked (GAsyncQueue* queue)
/** /**
* g_async_queue_timed_pop: * g_async_queue_timed_pop:
* @queue: a #GAsyncQueue. * @queue: a #GAsyncQueue
* @end_time: a #GTimeVal, determining the final time. * @end_time: a #GTimeVal, determining the final time
* *
* Pops data from the @queue. If no data is received before @end_time, * Pops data from the @queue. If the queue is empty, blocks until
* %NULL is returned. * @end_time or until data becomes available.
* *
* To easily calculate @end_time a combination of g_get_current_time() * If no data is received before @end_time, %NULL is returned.
*
* To easily calculate @end_time, a combination of g_get_current_time()
* and g_time_val_add() can be used. * and g_time_val_add() can be used.
* *
* Return value: data from the queue or %NULL, when no data is * Return value: data from the queue or %NULL, when no data is
* received before @end_time. * received before @end_time.
**/ */
gpointer gpointer
g_async_queue_timed_pop (GAsyncQueue* queue, GTimeVal *end_time) g_async_queue_timed_pop (GAsyncQueue *queue,
GTimeVal *end_time)
{ {
gpointer retval; gpointer retval;
@ -542,21 +563,25 @@ g_async_queue_timed_pop (GAsyncQueue* queue, GTimeVal *end_time)
/** /**
* g_async_queue_timed_pop_unlocked: * g_async_queue_timed_pop_unlocked:
* @queue: a #GAsyncQueue. * @queue: a #GAsyncQueue
* @end_time: a #GTimeVal, determining the final time. * @end_time: a #GTimeVal, determining the final time
* *
* Pops data from the @queue. If no data is received before @end_time, * Pops data from the @queue. If the queue is empty, blocks until
* %NULL is returned. This function must be called while holding the * @end_time or until data becomes available.
* @queue's lock.
* *
* To easily calculate @end_time a combination of g_get_current_time() * If no data is received before @end_time, %NULL is returned.
*
* To easily calculate @end_time, a combination of g_get_current_time()
* and g_time_val_add() can be used. * and g_time_val_add() can be used.
* *
* This function must be called while holding the @queue's lock.
*
* Return value: data from the queue or %NULL, when no data is * Return value: data from the queue or %NULL, when no data is
* received before @end_time. * received before @end_time.
**/ */
gpointer gpointer
g_async_queue_timed_pop_unlocked (GAsyncQueue* queue, GTimeVal *end_time) g_async_queue_timed_pop_unlocked (GAsyncQueue *queue,
GTimeVal *end_time)
{ {
g_return_val_if_fail (queue, NULL); g_return_val_if_fail (queue, NULL);
@ -567,18 +592,19 @@ g_async_queue_timed_pop_unlocked (GAsyncQueue* queue, GTimeVal *end_time)
* g_async_queue_length: * g_async_queue_length:
* @queue: a #GAsyncQueue. * @queue: a #GAsyncQueue.
* *
* Returns the length of the queue, negative values mean waiting * Returns the length of the queue.
* threads, positive values mean available entries in the
* @queue. Actually this function returns the number of data items in
* the queue minus the number of waiting threads. Thus a return value
* of 0 could mean 'n' entries in the queue and 'n' thread waiting.
* That can happen due to locking of the queue or due to
* scheduling.
* *
* Return value: the length of the @queue. * Actually this function returns the number of data items in
**/ * the queue minus the number of waiting threads, so a negative
* value means waiting threads, and a positive value means available
* entries in the @queue. A return value of 0 could mean n entries
* in the queue and n threads waiting. This can happen due to locking
* of the queue or due to scheduling.
*
* Return value: the length of the @queue
*/
gint gint
g_async_queue_length (GAsyncQueue* queue) g_async_queue_length (GAsyncQueue *queue)
{ {
gint retval; gint retval;
@ -593,21 +619,23 @@ g_async_queue_length (GAsyncQueue* queue)
/** /**
* g_async_queue_length_unlocked: * g_async_queue_length_unlocked:
* @queue: a #GAsyncQueue. * @queue: a #GAsyncQueue
* *
* Returns the length of the queue, negative values mean waiting * Returns the length of the queue.
* threads, positive values mean available entries in the *
* @queue. Actually this function returns the number of data items in * Actually this function returns the number of data items in
* the queue minus the number of waiting threads. Thus a return value * the queue minus the number of waiting threads, so a negative
* of 0 could mean 'n' entries in the queue and 'n' thread waiting. * value means waiting threads, and a positive value means available
* That can happen due to locking of the queue or due to * entries in the @queue. A return value of 0 could mean n entries
* scheduling. This function must be called while holding the @queue's * in the queue and n threads waiting. This can happen due to locking
* lock. * of the queue or due to scheduling.
*
* This function must be called while holding the @queue's lock.
* *
* Return value: the length of the @queue. * Return value: the length of the @queue.
**/ */
gint gint
g_async_queue_length_unlocked (GAsyncQueue* queue) g_async_queue_length_unlocked (GAsyncQueue *queue)
{ {
g_return_val_if_fail (queue, 0); g_return_val_if_fail (queue, 0);
@ -617,16 +645,17 @@ g_async_queue_length_unlocked (GAsyncQueue* queue)
/** /**
* g_async_queue_sort: * g_async_queue_sort:
* @queue: a #GAsyncQueue * @queue: a #GAsyncQueue
* @func: the #GCompareDataFunc is used to sort @queue. This * @func: the #GCompareDataFunc is used to sort @queue
* function is passed two elements of the @queue. The function
* should return 0 if they are equal, a negative value if the
* first element should be higher in the @queue or a positive
* value if the first element should be lower in the @queue than
* the second element.
* @user_data: user data passed to @func * @user_data: user data passed to @func
* *
* Sorts @queue using @func. * Sorts @queue using @func.
* *
* The sort function @func is passed two elements of the @queue.
* It should return 0 if they are equal, a negative value if the
* first element should be higher in the @queue or a positive value
* if the first element should be lower in the @queue than the second
* element.
*
* This function will lock @queue before it sorts the queue and unlock * This function will lock @queue before it sorts the queue and unlock
* it when it is finished. * it when it is finished.
* *
@ -643,11 +672,11 @@ g_async_queue_length_unlocked (GAsyncQueue* queue)
* ]| * ]|
* *
* Since: 2.10 * Since: 2.10
**/ */
void void
g_async_queue_sort (GAsyncQueue *queue, g_async_queue_sort (GAsyncQueue *queue,
GCompareDataFunc func, GCompareDataFunc func,
gpointer user_data) gpointer user_data)
{ {
g_return_if_fail (queue != NULL); g_return_if_fail (queue != NULL);
g_return_if_fail (func != NULL); g_return_if_fail (func != NULL);
@ -660,24 +689,25 @@ g_async_queue_sort (GAsyncQueue *queue,
/** /**
* g_async_queue_sort_unlocked: * g_async_queue_sort_unlocked:
* @queue: a #GAsyncQueue * @queue: a #GAsyncQueue
* @func: the #GCompareDataFunc is used to sort @queue. This * @func: the #GCompareDataFunc is used to sort @queue
* function is passed two elements of the @queue. The function
* should return 0 if they are equal, a negative value if the
* first element should be higher in the @queue or a positive
* value if the first element should be lower in the @queue than
* the second element.
* @user_data: user data passed to @func * @user_data: user data passed to @func
* *
* Sorts @queue using @func. * Sorts @queue using @func.
* *
* This function is called while holding the @queue's lock. * The sort function @func is passed two elements of the @queue.
* It should return 0 if they are equal, a negative value if the
* first element should be higher in the @queue or a positive value
* if the first element should be lower in the @queue than the second
* element.
*
* This function must be called while holding the @queue's lock.
* *
* Since: 2.10 * Since: 2.10
**/ */
void void
g_async_queue_sort_unlocked (GAsyncQueue *queue, g_async_queue_sort_unlocked (GAsyncQueue *queue,
GCompareDataFunc func, GCompareDataFunc func,
gpointer user_data) gpointer user_data)
{ {
SortData sd; SortData sd;
@ -688,16 +718,16 @@ g_async_queue_sort_unlocked (GAsyncQueue *queue,
sd.user_data = user_data; sd.user_data = user_data;
g_queue_sort (&queue->queue, g_queue_sort (&queue->queue,
(GCompareDataFunc)g_async_queue_invert_compare, (GCompareDataFunc)g_async_queue_invert_compare,
&sd); &sd);
} }
/* /*
* Private API * Private API
*/ */
GMutex* GMutex *
_g_async_queue_get_mutex (GAsyncQueue* queue) _g_async_queue_get_mutex (GAsyncQueue *queue)
{ {
g_return_val_if_fail (queue, NULL); g_return_val_if_fail (queue, NULL);

70
glib/gasyncqueue.h
View File

@ -8,7 +8,7 @@
* *
* This library is distributed in the hope that it will be useful, * This library is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of * but WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
* Lesser General Public License for more details. * Lesser General Public License for more details.
* *
* You should have received a copy of the GNU Lesser General Public * You should have received a copy of the GNU Lesser General Public
@ -37,80 +37,46 @@ G_BEGIN_DECLS
typedef struct _GAsyncQueue GAsyncQueue; typedef struct _GAsyncQueue GAsyncQueue;
/* Asyncronous Queues, can be used to communicate between threads */ GAsyncQueue *g_async_queue_new (void);
GAsyncQueue *g_async_queue_new_full (GDestroyNotify item_free_func);
/* Get a new GAsyncQueue with the ref_count 1 */
GAsyncQueue* g_async_queue_new (void);
GAsyncQueue* g_async_queue_new_full (GDestroyNotify item_free_func);
/* Lock and unlock a GAsyncQueue. All functions lock the queue for
* themselves, but in certain cirumstances you want to hold the lock longer,
* thus you lock the queue, call the *_unlocked functions and unlock it again.
*/
void g_async_queue_lock (GAsyncQueue *queue); void g_async_queue_lock (GAsyncQueue *queue);
void g_async_queue_unlock (GAsyncQueue *queue); void g_async_queue_unlock (GAsyncQueue *queue);
GAsyncQueue *g_async_queue_ref (GAsyncQueue *queue);
/* Ref and unref the GAsyncQueue. */
GAsyncQueue* g_async_queue_ref (GAsyncQueue *queue);
void g_async_queue_unref (GAsyncQueue *queue); void g_async_queue_unref (GAsyncQueue *queue);
#ifndef G_DISABLE_DEPRECATED #ifndef G_DISABLE_DEPRECATED
/* You don't have to hold the lock for calling *_ref and *_unref anymore. */
void g_async_queue_ref_unlocked (GAsyncQueue *queue); void g_async_queue_ref_unlocked (GAsyncQueue *queue);
void g_async_queue_unref_and_unlock (GAsyncQueue *queue); void g_async_queue_unref_and_unlock (GAsyncQueue *queue);
#endif /* !G_DISABLE_DEPRECATED */ #endif /* !G_DISABLE_DEPRECATED */
/* Push data into the async queue. Must not be NULL. */
void g_async_queue_push (GAsyncQueue *queue, void g_async_queue_push (GAsyncQueue *queue,
gpointer data); gpointer data);
void g_async_queue_push_unlocked (GAsyncQueue *queue, void g_async_queue_push_unlocked (GAsyncQueue *queue,
gpointer data); gpointer data);
void g_async_queue_push_sorted (GAsyncQueue *queue, void g_async_queue_push_sorted (GAsyncQueue *queue,
gpointer data, gpointer data,
GCompareDataFunc func, GCompareDataFunc func,
gpointer user_data); gpointer user_data);
void g_async_queue_push_sorted_unlocked (GAsyncQueue *queue, void g_async_queue_push_sorted_unlocked (GAsyncQueue *queue,
gpointer data, gpointer data,
GCompareDataFunc func, GCompareDataFunc func,
gpointer user_data); gpointer user_data);
/* Pop data from the async queue. When no data is there, the thread is blocked
* until data arrives.
*/
gpointer g_async_queue_pop (GAsyncQueue *queue); gpointer g_async_queue_pop (GAsyncQueue *queue);
gpointer g_async_queue_pop_unlocked (GAsyncQueue *queue); gpointer g_async_queue_pop_unlocked (GAsyncQueue *queue);
/* Try to pop data. NULL is returned in case of empty queue. */
gpointer g_async_queue_try_pop (GAsyncQueue *queue); gpointer g_async_queue_try_pop (GAsyncQueue *queue);
gpointer g_async_queue_try_pop_unlocked (GAsyncQueue *queue); gpointer g_async_queue_try_pop_unlocked (GAsyncQueue *queue);
/* Wait for data until at maximum until end_time is reached. NULL is returned
* in case of empty queue.
*/
gpointer g_async_queue_timed_pop (GAsyncQueue *queue, gpointer g_async_queue_timed_pop (GAsyncQueue *queue,
GTimeVal *end_time); GTimeVal *end_time);
gpointer g_async_queue_timed_pop_unlocked (GAsyncQueue *queue, gpointer g_async_queue_timed_pop_unlocked (GAsyncQueue *queue,
GTimeVal *end_time); GTimeVal *end_time);
/* Return the length of the queue. Negative values mean that threads
* are waiting, positve values mean that there are entries in the
* queue. Actually this function returns the length of the queue minus
* the number of waiting threads, g_async_queue_length == 0 could also
* mean 'n' entries in the queue and 'n' thread waiting. Such can
* happen due to locking of the queue or due to scheduling.
*/
gint g_async_queue_length (GAsyncQueue *queue); gint g_async_queue_length (GAsyncQueue *queue);
gint g_async_queue_length_unlocked (GAsyncQueue *queue); gint g_async_queue_length_unlocked (GAsyncQueue *queue);
void g_async_queue_sort (GAsyncQueue *queue, void g_async_queue_sort (GAsyncQueue *queue,
GCompareDataFunc func, GCompareDataFunc func,
gpointer user_data); gpointer user_data);
void g_async_queue_sort_unlocked (GAsyncQueue *queue, void g_async_queue_sort_unlocked (GAsyncQueue *queue,
GCompareDataFunc func, GCompareDataFunc func,
gpointer user_data); gpointer user_data);
G_END_DECLS G_END_DECLS