g_async_queue_new ()

GAsyncQueue *
g_async_queue_new (void);

Creates a new asynchronous queue.

g_async_queue_new_full ()

GAsyncQueue *
g_async_queue_new_full (GDestroyNotify item_free_func);

Creates a new asynchronous queue 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 queue by 1. You do not need to hold the lock to call this function.

g_async_queue_unref ()

void
g_async_queue_unref (GAsyncQueue *queue);

Decreases the reference count of the asynchronous queue by 1.

If 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 queue afterwards, as it might have disappeared. You do not need to hold the lock to call this function.

g_async_queue_push ()

void
g_async_queue_push (GAsyncQueue *queue,
                    gpointer data);

Pushes the data into the queue . data must not be NULL.

g_async_queue_push_sorted ()

void
g_async_queue_push_sorted (GAsyncQueue *queue,
                           gpointer data,
                           GCompareDataFunc func,
                           gpointer user_data);

Inserts data into queue using func to determine the new position.

This function requires that the queue is sorted before pushing on new elements, see g_async_queue_sort().

This function will lock queue before it sorts the queue and unlock it when it is finished.

For an example of func see g_async_queue_sort().

Since 2.10

g_async_queue_pop ()

gpointer
g_async_queue_pop (GAsyncQueue *queue);

Pops data from the queue . If queue is empty, this function blocks until data becomes available.

g_async_queue_try_pop ()

gpointer
g_async_queue_try_pop (GAsyncQueue *queue);

Tries to pop data from the queue . If no data is available, NULL is returned.

g_async_queue_timeout_pop ()

gpointer
g_async_queue_timeout_pop (GAsyncQueue *queue,
                           guint64 timeout);

Pops data from the queue . If the queue is empty, blocks for timeout microseconds, or until data becomes available.

If no data is received before the timeout, NULL is returned.

g_async_queue_length ()

gint
g_async_queue_length (GAsyncQueue *queue);

Returns 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.

g_async_queue_sort ()

void
g_async_queue_sort (GAsyncQueue *queue,
                    GCompareDataFunc func,
                    gpointer user_data);

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 it when it is finished.

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:

1
2
3
4
5
6
7

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 queue 's lock. If another thread is already holding the lock, this call will block until the lock becomes available.

Call g_async_queue_unlock() to drop the lock again.

While holding the lock, you can only call the g_async_queue_*_unlocked() functions on queue . Otherwise, deadlock may occur.

g_async_queue_unlock ()

void
g_async_queue_unlock (GAsyncQueue *queue);

Releases the queue's lock.

Calling this function when you have not acquired the with g_async_queue_lock() leads to undefined behaviour.

g_async_queue_ref_unlocked ()

void
g_async_queue_ref_unlocked (GAsyncQueue *queue);

Increases the reference count of the asynchronous queue by 1.

g_async_queue_unref_and_unlock ()

void
g_async_queue_unref_and_unlock (GAsyncQueue *queue);

Decreases the reference count of the asynchronous queue by 1 and releases the lock. This function must be called while holding the queue 's lock. If the reference count went to 0, the queue will be destroyed and the memory allocated will be freed.

g_async_queue_push_unlocked ()

void
g_async_queue_push_unlocked (GAsyncQueue *queue,
                             gpointer data);

Pushes the data into the queue . data must not be NULL.

This function must be called while holding the queue 's lock.

g_async_queue_push_sorted_unlocked ()

void
g_async_queue_push_sorted_unlocked (GAsyncQueue *queue,
                                    gpointer data,
                                    GCompareDataFunc func,
                                    gpointer user_data);

Inserts data into queue using func to determine the new position.

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 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().

Since 2.10

g_async_queue_pop_unlocked ()

gpointer
g_async_queue_pop_unlocked (GAsyncQueue *queue);

Pops data from the queue . If queue is empty, this function blocks until data becomes available.

This function must be called while holding the queue 's lock.

g_async_queue_try_pop_unlocked ()

gpointer
g_async_queue_try_pop_unlocked (GAsyncQueue *queue);

Tries to pop data from the queue . If no data is available, NULL is returned.

This function must be called while holding the queue 's lock.

g_async_queue_timeout_pop_unlocked ()

gpointer
g_async_queue_timeout_pop_unlocked (GAsyncQueue *queue,
                                    guint64 timeout);

Pops data from the queue . If the queue is empty, blocks for timeout microseconds, or until data becomes available.

If no data is received before the timeout, NULL is returned.

This function must be called while holding the queue 's lock.

g_async_queue_length_unlocked ()

gint
g_async_queue_length_unlocked (GAsyncQueue *queue);

Returns 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.

This function must be called while holding the queue 's lock.

g_async_queue_sort_unlocked ()

void
g_async_queue_sort_unlocked (GAsyncQueue *queue,
                             GCompareDataFunc func,
                             gpointer user_data);

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 must be called while holding the queue 's lock.

Since 2.10

g_async_queue_timed_pop ()

gpointer
g_async_queue_timed_pop (GAsyncQueue *queue,
                         GTimeVal *end_time);

Pops data from the queue . If the queue is empty, blocks until end_time or until data becomes available.

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.

g_async_queue_timed_pop_unlocked ()

gpointer
g_async_queue_timed_pop_unlocked (GAsyncQueue *queue,
                                  GTimeVal *end_time);

Pops data from the queue . If the queue is empty, blocks until end_time or until data becomes available.

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.

This function must be called while holding the queue 's lock.

GAsyncQueue

typedef 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_* functions.