Synopsis#include <glib.h> GAsyncQueue; GAsyncQueue* g_async_queue_new (void); GAsyncQueue* g_async_queue_new_full (GDestroyNotify item_free_func); GAsyncQueue* g_async_queue_ref (GAsyncQueue *queue); void g_async_queue_unref (GAsyncQueue *queue); void g_async_queue_push (GAsyncQueue *queue, gpointer data); void g_async_queue_push_sorted (GAsyncQueue *queue, gpointer data, GCompareDataFunc func, gpointer user_data); gpointer g_async_queue_pop (GAsyncQueue *queue); gpointer g_async_queue_try_pop (GAsyncQueue *queue); gpointer g_async_queue_timed_pop (GAsyncQueue *queue, GTimeVal *end_time); gint g_async_queue_length (GAsyncQueue *queue); void g_async_queue_sort (GAsyncQueue *queue, GCompareDataFunc func, gpointer user_data); void g_async_queue_lock (GAsyncQueue *queue); void g_async_queue_unlock (GAsyncQueue *queue); void g_async_queue_ref_unlocked (GAsyncQueue *queue); void g_async_queue_unref_and_unlock (GAsyncQueue *queue); void g_async_queue_push_unlocked (GAsyncQueue *queue, gpointer data); void g_async_queue_push_sorted_unlocked (GAsyncQueue *queue, gpointer data, GCompareDataFunc func, gpointer user_data); gpointer g_async_queue_pop_unlocked (GAsyncQueue *queue); gpointer g_async_queue_try_pop_unlocked (GAsyncQueue *queue); gpointer g_async_queue_timed_pop_unlocked (GAsyncQueue *queue, GTimeVal *end_time); gint g_async_queue_length_unlocked (GAsyncQueue *queue); void g_async_queue_sort_unlocked (GAsyncQueue *queue, GCompareDataFunc func, gpointer user_data); DescriptionOften 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
A thread, which wants to send a message to that queue simply calls
A thread, which is expecting messages from an asynchronous queue
simply calls
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 DetailsGAsyncQueuetypedef struct _GAsyncQueue GAsyncQueue;
The GAsyncQueue struct is an opaque data structure, which represents
an asynchronous queue. It should only be accessed through the
g_async_queue_new ()GAsyncQueue* g_async_queue_new (void); Creates a new asynchronous queue with the initial reference count of 1.
g_async_queue_new_full ()GAsyncQueue* g_async_queue_new_full (GDestroyNotify item_free_func); Creates a new asynchronous queue with an initial reference count of 1 and sets up a destroy notify function that is used to free any remaining queue items when the queue is destroyed after the final unref.
Since 2.16 g_async_queue_ref ()GAsyncQueue* g_async_queue_ref (GAsyncQueue *queue);
Increases the reference count of the asynchronous
g_async_queue_unref ()void g_async_queue_unref (GAsyncQueue *queue);
Decreases the reference count of the asynchronous
g_async_queue_push ()void g_async_queue_push (GAsyncQueue *queue, gpointer data);
Pushes the
g_async_queue_push_sorted ()void g_async_queue_push_sorted (GAsyncQueue *queue, gpointer data, GCompareDataFunc func, gpointer user_data);
Inserts
This function requires that the
This function will lock
For an example of
Since 2.10 g_async_queue_pop ()gpointer g_async_queue_pop (GAsyncQueue *queue);
Pops data from the
g_async_queue_try_pop ()gpointer g_async_queue_try_pop (GAsyncQueue *queue);
Tries to pop data from the
g_async_queue_timed_pop ()gpointer g_async_queue_timed_pop (GAsyncQueue *queue, GTimeVal *end_time);
Pops data from the
To easily calculate
g_async_queue_length ()gint g_async_queue_length (GAsyncQueue *queue);
Returns the length of the queue, negative values mean waiting
threads, positive values mean available entries in the
g_async_queue_sort ()void g_async_queue_sort (GAsyncQueue *queue, GCompareDataFunc func, gpointer user_data);
Sorts
This function will lock If you were sorting a list of priority numbers to make sure the lowest priority would be at the top of the queue, you could use: gint32 id1; gint32 id2; id1 = GPOINTER_TO_INT (element1); id2 = GPOINTER_TO_INT (element2); return (id1 > id2 ? +1 : id1 == id2 ? 0 : -1);
Since 2.10 g_async_queue_lock ()void g_async_queue_lock (GAsyncQueue *queue);
Acquires the
g_async_queue_unlock ()void g_async_queue_unlock (GAsyncQueue *queue); Releases the queue's lock.
g_async_queue_ref_unlocked ()void g_async_queue_ref_unlocked (GAsyncQueue *queue); Warning
Increases the reference count of the asynchronous
g_async_queue_unref_and_unlock ()void g_async_queue_unref_and_unlock (GAsyncQueue *queue); Warning
Decreases the reference count of the asynchronous
g_async_queue_push_unlocked ()void g_async_queue_push_unlocked (GAsyncQueue *queue, gpointer data);
Pushes the
g_async_queue_push_sorted_unlocked ()void g_async_queue_push_sorted_unlocked (GAsyncQueue *queue, gpointer data, GCompareDataFunc func, gpointer user_data);
Inserts
This function requires that the
This function is called while holding the
For an example of
Since 2.10 g_async_queue_pop_unlocked ()gpointer g_async_queue_pop_unlocked (GAsyncQueue *queue);
Pops data from the
g_async_queue_try_pop_unlocked ()gpointer g_async_queue_try_pop_unlocked (GAsyncQueue *queue);
Tries to pop data from the
g_async_queue_timed_pop_unlocked ()gpointer g_async_queue_timed_pop_unlocked (GAsyncQueue *queue, GTimeVal *end_time);
Pops data from the
To easily calculate
g_async_queue_length_unlocked ()gint g_async_queue_length_unlocked (GAsyncQueue *queue);
Returns the length of the queue, negative values mean waiting
threads, positive values mean available entries in the
g_async_queue_sort_unlocked ()void g_async_queue_sort_unlocked (GAsyncQueue *queue, GCompareDataFunc func, gpointer user_data);
Sorts
This function is called while holding the
Since 2.10 |