Skip to content

GLib.AsyncQueue

record (struct)

An opaque data structure which represents an asynchronous queue.

It should only be accessed through the g_async_queue_* functions.

Methods

length

def length(self) -> 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 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.

length_unlocked

def length_unlocked(self) -> 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 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.

lock

def lock(self) -> None

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

Call AsyncQueue.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.

pop

def pop(self) -> int

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

pop_unlocked

def pop_unlocked(self) -> int

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.

push

def push(self, data: int) -> None

Pushes the data into the queue.

The data parameter must not be None.

Parameters:

  • data — data to push onto the queue

push_front

def push_front(self, item: int) -> None

Pushes the item into the queue. item must not be None. In contrast to 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.

Parameters:

  • item — data to push into the queue

push_front_unlocked

def push_front_unlocked(self, item: int) -> None

Pushes the item into the queue. item must not be None. In contrast to 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 queue's lock.

Parameters:

  • item — data to push into the queue

push_sorted

def push_sorted(self, data: int, func: CompareDataFunc) -> None

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 AsyncQueue.sort.

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

For an example of func see AsyncQueue.sort.

Parameters:

  • data — the data to push into the queue
  • func — the GCompareDataFunc is used to sort queue

push_sorted_unlocked

def push_sorted_unlocked(self, data: int, func: CompareDataFunc) -> None

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 AsyncQueue.sort.

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

For an example of func see AsyncQueue.sort.

Parameters:

  • data — the data to push into the queue
  • func — the GCompareDataFunc is used to sort queue

push_unlocked

def push_unlocked(self, data: int) -> None

Pushes the data into the queue.

The data parameter must not be None.

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

Parameters:

  • data — data to push onto the queue

ref

def ref(self) -> AsyncQueue

Increases the reference count of the asynchronous queue by 1. You do not need to hold the lock to call this function.

ref_unlocked

def ref_unlocked(self) -> None

:::warning Deprecated since 2.8 This API is deprecated. :::

Increases the reference count of the asynchronous queue by 1.

remove

def remove(self, item: int) -> bool

Remove an item from the queue.

Parameters:

  • item — the data to remove from the queue

remove_unlocked

def remove_unlocked(self, item: int) -> bool

Remove an item from the queue.

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

Parameters:

  • item — the data to remove from the queue

sort

def sort(self, func: CompareDataFunc) -> None

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:

gint32 id1;
 gint32 id2;

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

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

Parameters:

  • func — the GCompareDataFunc is used to sort queue

sort_unlocked

def sort_unlocked(self, func: CompareDataFunc) -> None

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.

Parameters:

  • func — the GCompareDataFunc is used to sort queue

timed_pop

def timed_pop(self, end_time: TimeVal) -> int | None

:::warning Deprecated This API is deprecated. :::

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, None is returned.

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

Parameters:

  • end_time — a TimeVal, determining the final time

timed_pop_unlocked

def timed_pop_unlocked(self, end_time: TimeVal) -> int | None

:::warning Deprecated This API is deprecated. :::

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, None is returned.

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

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

Parameters:

  • end_time — a TimeVal, determining the final time

timeout_pop

def timeout_pop(self, timeout: int) -> int | None

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, None is returned.

Parameters:

  • timeout — the number of microseconds to wait

timeout_pop_unlocked

def timeout_pop_unlocked(self, timeout: int) -> int | None

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, None is returned.

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

Parameters:

  • timeout — the number of microseconds to wait

try_pop

def try_pop(self) -> int | None

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

try_pop_unlocked

def try_pop_unlocked(self) -> int | None

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

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

unlock

def unlock(self) -> None

Releases the queue's lock.

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

unref

def unref(self) -> None

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.

unref_and_unlock

def unref_and_unlock(self) -> None

:::warning Deprecated since 2.8 This API is deprecated. :::

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.

Static functions

new

@staticmethod
def new() -> AsyncQueue

Creates a new asynchronous queue.

new_full

@staticmethod
def new_full(item_free_func: DestroyNotify | None = ...) -> AsyncQueue

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.

Parameters:

  • item_free_func — function to free queue elements