GLib.AsyncQueue

Fields

None

Methods

length ()

length_unlocked ()

lock ()

pop ()

pop_unlocked ()

push (data)

push_front (item)

push_front_unlocked (item)

push_sorted (data, func, *user_data)

push_sorted_unlocked (data, func, *user_data)

push_unlocked (data)

ref_unlocked ()

remove (item)

remove_unlocked (item)

sort (func, *user_data)

sort_unlocked (func, *user_data)

timed_pop (end_time)

timed_pop_unlocked (end_time)

timeout_pop (timeout)

timeout_pop_unlocked (timeout)

try_pop ()

try_pop_unlocked ()

unlock ()

unref ()

unref_and_unlock ()

Details

class GLib.AsyncQueue

An opaque data structure which represents an asynchronous queue.

It should only be accessed through the g_async_queue_* functions.

length()[source]
Returns:

the length of the self

Return type:

int

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

length_unlocked()[source]
Returns:

the length of the self.

Return type:

int

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 self. 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 self's lock.

lock()[source]

Acquires the self's lock. If another thread is already holding the lock, this call will block until the lock becomes available.

Call GLib.AsyncQueue.unlock() to drop the lock again.

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

pop()[source]
Returns:

data from the queue

Return type:

object or None

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

pop_unlocked()[source]
Returns:

data from the queue.

Return type:

object or None

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

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

push(data)[source]
Parameters:

data (object) – data to push onto the self

Pushes the data into the self.

The data parameter must not be None.

push_front(item)[source]
Parameters:

item (object) – data to push into the self

Pushes the item into the self. item must not be None. In contrast to GLib.AsyncQueue.push(), this function pushes the new item ahead of the items already in the queue, so that it will be the next one to be popped off the queue.

New in version 2.46.

push_front_unlocked(item)[source]
Parameters:

item (object) – data to push into the self

Pushes the item into the self. item must not be None. In contrast to GLib.AsyncQueue.push_unlocked(), this function pushes the new item ahead of the items already in the queue, so that it will be the next one to be popped off the queue.

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

New in version 2.46.

push_sorted(data, func, *user_data)[source]
Parameters:

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

This function requires that the self is sorted before pushing on new elements, see GLib.AsyncQueue.sort().

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

For an example of func see GLib.AsyncQueue.sort().

New in version 2.10.

push_sorted_unlocked(data, func, *user_data)[source]
Parameters:

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

The sort function func is passed two elements of the self. It should return 0 if they are equal, a negative value if the first element should be higher in the self or a positive value if the first element should be lower in the self than the second element.

This function requires that the self is sorted before pushing on new elements, see GLib.AsyncQueue.sort().

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

For an example of func see GLib.AsyncQueue.sort().

New in version 2.10.

push_unlocked(data)[source]
Parameters:

data (object) – data to push onto the self

Pushes the data into the self.

The data parameter must not be None.

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

ref_unlocked()[source]

Increases the reference count of the asynchronous self by 1.

Deprecated since version 2.8: Reference counting is done atomically. so g_async_queue_ref() can be used regardless of the queue's lock.

remove(item)[source]
Parameters:

item (object) – the data to remove from the self

Returns:

True if the item was removed

Return type:

bool

Remove an item from the queue.

New in version 2.46.

remove_unlocked(item)[source]
Parameters:

item (object or None) – the data to remove from the self

Returns:

True if the item was removed

Return type:

bool

Remove an item from the queue.

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

New in version 2.46.

sort(func, *user_data)[source]
Parameters:

Sorts self using func.

The sort function func is passed two elements of the self. It should return 0 if they are equal, a negative value if the first element should be higher in the self or a positive value if the first element should be lower in the self than the second element.

This function will lock self 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:

gint32 id1;
gint32 id2;

id1 = GPOINTER_TO_INT (element1);
id2 = GPOINTER_TO_INT (element2);

return (id1 > id2 ? +1 : id1 == id2 ? 0 : -1);

New in version 2.10.

sort_unlocked(func, *user_data)[source]
Parameters:

Sorts self using func.

The sort function func is passed two elements of the self. It should return 0 if they are equal, a negative value if the first element should be higher in the self or a positive value if the first element should be lower in the self than the second element.

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

New in version 2.10.

timed_pop(end_time)[source]
Parameters:

end_time (GLib.TimeVal) – a GLib.TimeVal, determining the final time

Returns:

data from the queue or None, when no data is received before end_time.

Return type:

object or None

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

If no data is received before end_time, None is returned.

To easily calculate end_time, a combination of GLib.get_real_time() and GLib.TimeVal.add() can be used.

Deprecated since version ???: use GLib.AsyncQueue.timeout_pop().

timed_pop_unlocked(end_time)[source]
Parameters:

end_time (GLib.TimeVal) – a GLib.TimeVal, determining the final time

Returns:

data from the queue or None, when no data is received before end_time.

Return type:

object or None

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

If no data is received before end_time, None is returned.

To easily calculate end_time, a combination of GLib.get_real_time() and GLib.TimeVal.add() can be used.

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

Deprecated since version ???: use GLib.AsyncQueue.timeout_pop_unlocked().

timeout_pop(timeout)[source]
Parameters:

timeout (int) – the number of microseconds to wait

Returns:

data from the queue or None, when no data is received before the timeout.

Return type:

object or None

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

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

timeout_pop_unlocked(timeout)[source]
Parameters:

timeout (int) – the number of microseconds to wait

Returns:

data from the queue or None, when no data is received before the timeout.

Return type:

object or None

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

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

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

try_pop()[source]
Returns:

data from the queue or None, when no data is available immediately.

Return type:

object or None

Tries to pop data from the self. If no data is available, None is returned.

try_pop_unlocked()[source]
Returns:

data from the queue or None, when no data is available immediately.

Return type:

object or None

Tries to pop data from the self. If no data is available, None is returned.

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

unlock()[source]

Releases the queue’s lock.

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

unref()[source]

Decreases the reference count of the asynchronous self by 1.

If the reference count went to 0, the self will be destroyed and the memory allocated will be freed. So you are not allowed to use the self afterwards, as it might have disappeared. You do not need to hold the lock to call this function.

unref_and_unlock()[source]

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

Deprecated since version 2.8: Reference counting is done atomically. so GLib.AsyncQueue.unref() can be used regardless of the queue's lock.