:right-sidebar: True AsyncQueue =================================================================== .. currentmodule:: gi.repository.GLib .. class:: AsyncQueue(*args, **kwargs) :no-contents-entry: An opaque data structure which represents an asynchronous queue. It should only be accessed through the ``g_async_queue_*`` functions. Methods ------- .. rst-class:: interim-class .. class:: AsyncQueue :no-index: .. method:: length() -> 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. .. method:: length_unlocked() -> 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. .. method:: lock() -> None Acquires the ``queue``\'s lock. If another thread is already holding the lock, this call will block until the lock becomes available. Call :func:`~gi.repository.GLib.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. .. classmethod:: new() -> ~gi.repository.GLib.AsyncQueue Creates a new asynchronous queue. .. classmethod:: new_full() -> ~gi.repository.GLib.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. .. versionadded:: 2.16 .. method:: pop() -> ~typing.Any | None Pops data from the ``queue``\. If ``queue`` is empty, this function blocks until data becomes available. .. method:: pop_unlocked() -> ~typing.Any | None 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. .. method:: push(data: ~typing.Any) -> None Pushes the ``data`` into the ``queue``\. The ``data`` parameter must not be :const:`None`. :param data: data to push onto the ``queue`` .. method:: push_front(item: ~typing.Any) -> None Pushes the ``item`` into the ``queue``\. ``item`` must not be :const:`None`. In contrast to :func:`~gi.repository.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. .. versionadded:: 2.46 :param item: data to push into the ``queue`` .. method:: push_front_unlocked(item: ~typing.Any) -> None Pushes the ``item`` into the ``queue``\. ``item`` must not be :const:`None`. In contrast to :func:`~gi.repository.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 ``queue``\'s lock. .. versionadded:: 2.46 :param item: data to push into the ``queue`` .. method:: push_sorted(data: ~typing.Any, func: ~typing.Callable[[~typing.Any, ~typing.Any, ~typing.Any], int], user_data: ~typing.Any = None) -> 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 :func:`~gi.repository.GLib.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 :func:`~gi.repository.GLib.AsyncQueue.sort`. .. versionadded:: 2.10 :param data: the ``data`` to push into the ``queue`` :param func: the :obj:`~gi.repository.GLib.CompareDataFunc` is used to sort ``queue`` :param user_data: user data passed to ``func``\. .. method:: push_sorted_unlocked(data: ~typing.Any, func: ~typing.Callable[[~typing.Any, ~typing.Any, ~typing.Any], int], user_data: ~typing.Any = None) -> 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 :func:`~gi.repository.GLib.AsyncQueue.sort`. This function must be called while holding the ``queue``\'s lock. For an example of ``func`` see :func:`~gi.repository.GLib.AsyncQueue.sort`. .. versionadded:: 2.10 :param data: the data to push into the ``queue`` :param func: the :obj:`~gi.repository.GLib.CompareDataFunc` is used to sort ``queue`` :param user_data: user data passed to ``func``\. .. method:: push_unlocked(data: ~typing.Any) -> None Pushes the ``data`` into the ``queue``\. The ``data`` parameter must not be :const:`None`. This function must be called while holding the ``queue``\'s lock. :param data: data to push onto the ``queue`` .. method:: remove(item: ~typing.Any) -> bool Remove an item from the queue. .. versionadded:: 2.46 :param item: the data to remove from the ``queue`` :return: 0 if the file was successfully removed, -1 if an error occurred .. method:: remove_unlocked(item: ~typing.Any = None) -> bool Remove an item from the queue. This function must be called while holding the ``queue``\'s lock. .. versionadded:: 2.46 :param item: the data to remove from the ``queue`` .. method:: sort(func: ~typing.Callable[[~typing.Any, ~typing.Any, ~typing.Any], int], user_data: ~typing.Any = None) -> 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: .. code-block:: C :dedent: gint32 id1; gint32 id2; id1 = GPOINTER_TO_INT (element1); id2 = GPOINTER_TO_INT (element2); return (id1 > id2 ? +1 : id1 == id2 ? 0 : -1); .. versionadded:: 2.10 :param func: the :obj:`~gi.repository.GLib.CompareDataFunc` is used to sort ``queue`` :param user_data: user data passed to ``func`` .. method:: sort_unlocked(func: ~typing.Callable[[~typing.Any, ~typing.Any, ~typing.Any], int], user_data: ~typing.Any = None) -> 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. .. versionadded:: 2.10 :param func: the :obj:`~gi.repository.GLib.CompareDataFunc` is used to sort ``queue`` :param user_data: user data passed to ``func`` .. method:: timed_pop(end_time: ~gi.repository.GLib.TimeVal) -> ~typing.Any | None 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``\, :const:`None` is returned. To easily calculate ``end_time``\, a combination of :func:`~gi.repository.GLib.get_real_time` and :func:`~gi.repository.GLib.TimeVal.add` can be used. .. deprecated:: Unknown use :func:`~gi.repository.GLib.AsyncQueue.timeout_pop`. :param end_time: a :obj:`~gi.repository.GLib.TimeVal`\, determining the final time .. method:: timed_pop_unlocked(end_time: ~gi.repository.GLib.TimeVal) -> ~typing.Any | None 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``\, :const:`None` is returned. To easily calculate ``end_time``\, a combination of :func:`~gi.repository.GLib.get_real_time` and :func:`~gi.repository.GLib.TimeVal.add` can be used. This function must be called while holding the ``queue``\'s lock. .. deprecated:: Unknown use :func:`~gi.repository.GLib.AsyncQueue.timeout_pop_unlocked`. :param end_time: a :obj:`~gi.repository.GLib.TimeVal`\, determining the final time .. method:: timeout_pop(timeout: int) -> ~typing.Any | 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, :const:`None` is returned. :param timeout: the number of microseconds to wait .. method:: timeout_pop_unlocked(timeout: int) -> ~typing.Any | 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, :const:`None` is returned. This function must be called while holding the ``queue``\'s lock. :param timeout: the number of microseconds to wait .. method:: try_pop() -> ~typing.Any | None Tries to pop data from the ``queue``\. If no data is available, :const:`None` is returned. .. method:: try_pop_unlocked() -> ~typing.Any | None Tries to pop data from the ``queue``\. If no data is available, :const:`None` is returned. This function must be called while holding the ``queue``\'s lock. .. method:: unlock() -> None Releases the queue's lock. Calling this function when you have not acquired the with :func:`~gi.repository.GLib.AsyncQueue.lock` leads to undefined behaviour.