1.. currentmodule:: asyncio 2 3Queues 4====== 5 6Queues: 7 8* :class:`Queue` 9* :class:`PriorityQueue` 10* :class:`LifoQueue` 11 12asyncio queue API was designed to be close to classes of the :mod:`queue` 13module (:class:`~queue.Queue`, :class:`~queue.PriorityQueue`, 14:class:`~queue.LifoQueue`), but it has no *timeout* parameter. The 15:func:`asyncio.wait_for` function can be used to cancel a task after a timeout. 16 17Queue 18----- 19 20.. class:: Queue(maxsize=0, \*, loop=None) 21 22 A queue, useful for coordinating producer and consumer coroutines. 23 24 If *maxsize* is less than or equal to zero, the queue size is infinite. If 25 it is an integer greater than ``0``, then ``yield from put()`` will block 26 when the queue reaches *maxsize*, until an item is removed by :meth:`get`. 27 28 Unlike the standard library :mod:`queue`, you can reliably know this Queue's 29 size with :meth:`qsize`, since your single-threaded asyncio application won't 30 be interrupted between calling :meth:`qsize` and doing an operation on the 31 Queue. 32 33 This class is :ref:`not thread safe <asyncio-multithreading>`. 34 35 .. versionchanged:: 3.4.4 36 New :meth:`join` and :meth:`task_done` methods. 37 38 .. method:: empty() 39 40 Return ``True`` if the queue is empty, ``False`` otherwise. 41 42 .. method:: full() 43 44 Return ``True`` if there are :attr:`maxsize` items in the queue. 45 46 .. note:: 47 48 If the Queue was initialized with ``maxsize=0`` (the default), then 49 :meth:`full()` is never ``True``. 50 51 .. coroutinemethod:: get() 52 53 Remove and return an item from the queue. If queue is empty, wait until 54 an item is available. 55 56 This method is a :ref:`coroutine <coroutine>`. 57 58 .. seealso:: 59 60 The :meth:`empty` method. 61 62 .. method:: get_nowait() 63 64 Remove and return an item from the queue. 65 66 Return an item if one is immediately available, else raise 67 :exc:`QueueEmpty`. 68 69 .. coroutinemethod:: join() 70 71 Block until all items in the queue have been gotten and processed. 72 73 The count of unfinished tasks goes up whenever an item is added to the 74 queue. The count goes down whenever a consumer thread calls 75 :meth:`task_done` to indicate that the item was retrieved and all work on 76 it is complete. When the count of unfinished tasks drops to zero, 77 :meth:`join` unblocks. 78 79 This method is a :ref:`coroutine <coroutine>`. 80 81 .. versionadded:: 3.4.4 82 83 .. coroutinemethod:: put(item) 84 85 Put an item into the queue. If the queue is full, wait until a free slot 86 is available before adding item. 87 88 This method is a :ref:`coroutine <coroutine>`. 89 90 .. seealso:: 91 92 The :meth:`full` method. 93 94 .. method:: put_nowait(item) 95 96 Put an item into the queue without blocking. 97 98 If no free slot is immediately available, raise :exc:`QueueFull`. 99 100 .. method:: qsize() 101 102 Number of items in the queue. 103 104 .. method:: task_done() 105 106 Indicate that a formerly enqueued task is complete. 107 108 Used by queue consumers. For each :meth:`~Queue.get` used to fetch a task, a 109 subsequent call to :meth:`task_done` tells the queue that the processing 110 on the task is complete. 111 112 If a :meth:`join` is currently blocking, it will resume when all items 113 have been processed (meaning that a :meth:`task_done` call was received 114 for every item that had been :meth:`~Queue.put` into the queue). 115 116 Raises :exc:`ValueError` if called more times than there were items 117 placed in the queue. 118 119 .. versionadded:: 3.4.4 120 121 .. attribute:: maxsize 122 123 Number of items allowed in the queue. 124 125 126PriorityQueue 127------------- 128 129.. class:: PriorityQueue 130 131 A subclass of :class:`Queue`; retrieves entries in priority order (lowest 132 first). 133 134 Entries are typically tuples of the form: (priority number, data). 135 136 137LifoQueue 138--------- 139 140.. class:: LifoQueue 141 142 A subclass of :class:`Queue` that retrieves most recently added entries 143 first. 144 145 146Exceptions 147^^^^^^^^^^ 148 149.. exception:: QueueEmpty 150 151 Exception raised when the :meth:`~Queue.get_nowait` method is called on a 152 :class:`Queue` object which is empty. 153 154 155.. exception:: QueueFull 156 157 Exception raised when the :meth:`~Queue.put_nowait` method is called on a 158 :class:`Queue` object which is full. 159