1:mod:`queue` --- A synchronized queue class 2=========================================== 3 4.. module:: queue 5 :synopsis: A synchronized queue class. 6 7**Source code:** :source:`Lib/queue.py` 8 9-------------- 10 11The :mod:`queue` module implements multi-producer, multi-consumer queues. 12It is especially useful in threaded programming when information must be 13exchanged safely between multiple threads. The :class:`Queue` class in this 14module implements all the required locking semantics. 15 16The module implements three types of queue, which differ only in the order in 17which the entries are retrieved. In a :abbr:`FIFO (first-in, first-out)` 18queue, the first tasks added are the first retrieved. In a 19:abbr:`LIFO (last-in, first-out)` queue, the most recently added entry is 20the first retrieved (operating like a stack). With a priority queue, 21the entries are kept sorted (using the :mod:`heapq` module) and the 22lowest valued entry is retrieved first. 23 24Internally, those three types of queues use locks to temporarily block 25competing threads; however, they are not designed to handle reentrancy 26within a thread. 27 28In addition, the module implements a "simple" 29:abbr:`FIFO (first-in, first-out)` queue type, :class:`SimpleQueue`, whose 30specific implementation provides additional guarantees 31in exchange for the smaller functionality. 32 33The :mod:`queue` module defines the following classes and exceptions: 34 35.. class:: Queue(maxsize=0) 36 37 Constructor for a :abbr:`FIFO (first-in, first-out)` queue. *maxsize* is 38 an integer that sets the upperbound 39 limit on the number of items that can be placed in the queue. Insertion will 40 block once this size has been reached, until queue items are consumed. If 41 *maxsize* is less than or equal to zero, the queue size is infinite. 42 43.. class:: LifoQueue(maxsize=0) 44 45 Constructor for a :abbr:`LIFO (last-in, first-out)` queue. *maxsize* is 46 an integer that sets the upperbound 47 limit on the number of items that can be placed in the queue. Insertion will 48 block once this size has been reached, until queue items are consumed. If 49 *maxsize* is less than or equal to zero, the queue size is infinite. 50 51 52.. class:: PriorityQueue(maxsize=0) 53 54 Constructor for a priority queue. *maxsize* is an integer that sets the upperbound 55 limit on the number of items that can be placed in the queue. Insertion will 56 block once this size has been reached, until queue items are consumed. If 57 *maxsize* is less than or equal to zero, the queue size is infinite. 58 59 The lowest valued entries are retrieved first (the lowest valued entry is the 60 one returned by ``sorted(list(entries))[0]``). A typical pattern for entries 61 is a tuple in the form: ``(priority_number, data)``. 62 63 If the *data* elements are not comparable, the data can be wrapped in a class 64 that ignores the data item and only compares the priority number:: 65 66 from dataclasses import dataclass, field 67 from typing import Any 68 69 @dataclass(order=True) 70 class PrioritizedItem: 71 priority: int 72 item: Any=field(compare=False) 73 74.. class:: SimpleQueue() 75 76 Constructor for an unbounded :abbr:`FIFO (first-in, first-out)` queue. 77 Simple queues lack advanced functionality such as task tracking. 78 79 .. versionadded:: 3.7 80 81 82.. exception:: Empty 83 84 Exception raised when non-blocking :meth:`~Queue.get` (or 85 :meth:`~Queue.get_nowait`) is called 86 on a :class:`Queue` object which is empty. 87 88 89.. exception:: Full 90 91 Exception raised when non-blocking :meth:`~Queue.put` (or 92 :meth:`~Queue.put_nowait`) is called 93 on a :class:`Queue` object which is full. 94 95 96.. _queueobjects: 97 98Queue Objects 99------------- 100 101Queue objects (:class:`Queue`, :class:`LifoQueue`, or :class:`PriorityQueue`) 102provide the public methods described below. 103 104 105.. method:: Queue.qsize() 106 107 Return the approximate size of the queue. Note, qsize() > 0 doesn't 108 guarantee that a subsequent get() will not block, nor will qsize() < maxsize 109 guarantee that put() will not block. 110 111 112.. method:: Queue.empty() 113 114 Return ``True`` if the queue is empty, ``False`` otherwise. If empty() 115 returns ``True`` it doesn't guarantee that a subsequent call to put() 116 will not block. Similarly, if empty() returns ``False`` it doesn't 117 guarantee that a subsequent call to get() will not block. 118 119 120.. method:: Queue.full() 121 122 Return ``True`` if the queue is full, ``False`` otherwise. If full() 123 returns ``True`` it doesn't guarantee that a subsequent call to get() 124 will not block. Similarly, if full() returns ``False`` it doesn't 125 guarantee that a subsequent call to put() will not block. 126 127 128.. method:: Queue.put(item, block=True, timeout=None) 129 130 Put *item* into the queue. If optional args *block* is true and *timeout* is 131 ``None`` (the default), block if necessary until a free slot is available. If 132 *timeout* is a positive number, it blocks at most *timeout* seconds and raises 133 the :exc:`Full` exception if no free slot was available within that time. 134 Otherwise (*block* is false), put an item on the queue if a free slot is 135 immediately available, else raise the :exc:`Full` exception (*timeout* is 136 ignored in that case). 137 138 139.. method:: Queue.put_nowait(item) 140 141 Equivalent to ``put(item, False)``. 142 143 144.. method:: Queue.get(block=True, timeout=None) 145 146 Remove and return an item from the queue. If optional args *block* is true and 147 *timeout* is ``None`` (the default), block if necessary until an item is available. 148 If *timeout* is a positive number, it blocks at most *timeout* seconds and 149 raises the :exc:`Empty` exception if no item was available within that time. 150 Otherwise (*block* is false), return an item if one is immediately available, 151 else raise the :exc:`Empty` exception (*timeout* is ignored in that case). 152 153 Prior to 3.0 on POSIX systems, and for all versions on Windows, if 154 *block* is true and *timeout* is ``None``, this operation goes into 155 an uninterruptible wait on an underlying lock. This means that no exceptions 156 can occur, and in particular a SIGINT will not trigger a :exc:`KeyboardInterrupt`. 157 158 159.. method:: Queue.get_nowait() 160 161 Equivalent to ``get(False)``. 162 163Two methods are offered to support tracking whether enqueued tasks have been 164fully processed by daemon consumer threads. 165 166 167.. method:: Queue.task_done() 168 169 Indicate that a formerly enqueued task is complete. Used by queue consumer 170 threads. For each :meth:`get` used to fetch a task, a subsequent call to 171 :meth:`task_done` tells the queue that the processing on the task is complete. 172 173 If a :meth:`join` is currently blocking, it will resume when all items have been 174 processed (meaning that a :meth:`task_done` call was received for every item 175 that had been :meth:`put` into the queue). 176 177 Raises a :exc:`ValueError` if called more times than there were items placed in 178 the queue. 179 180 181.. method:: Queue.join() 182 183 Blocks until all items in the queue have been gotten and processed. 184 185 The count of unfinished tasks goes up whenever an item is added to the queue. 186 The count goes down whenever a consumer thread calls :meth:`task_done` to 187 indicate that the item was retrieved and all work on it is complete. When the 188 count of unfinished tasks drops to zero, :meth:`join` unblocks. 189 190 191Example of how to wait for enqueued tasks to be completed:: 192 193 import threading, queue 194 195 q = queue.Queue() 196 197 def worker(): 198 while True: 199 item = q.get() 200 print(f'Working on {item}') 201 print(f'Finished {item}') 202 q.task_done() 203 204 # turn-on the worker thread 205 threading.Thread(target=worker, daemon=True).start() 206 207 # send thirty task requests to the worker 208 for item in range(30): 209 q.put(item) 210 print('All task requests sent\n', end='') 211 212 # block until all tasks are done 213 q.join() 214 print('All work completed') 215 216 217SimpleQueue Objects 218------------------- 219 220:class:`SimpleQueue` objects provide the public methods described below. 221 222.. method:: SimpleQueue.qsize() 223 224 Return the approximate size of the queue. Note, qsize() > 0 doesn't 225 guarantee that a subsequent get() will not block. 226 227 228.. method:: SimpleQueue.empty() 229 230 Return ``True`` if the queue is empty, ``False`` otherwise. If empty() 231 returns ``False`` it doesn't guarantee that a subsequent call to get() 232 will not block. 233 234 235.. method:: SimpleQueue.put(item, block=True, timeout=None) 236 237 Put *item* into the queue. The method never blocks and always succeeds 238 (except for potential low-level errors such as failure to allocate memory). 239 The optional args *block* and *timeout* are ignored and only provided 240 for compatibility with :meth:`Queue.put`. 241 242 .. impl-detail:: 243 This method has a C implementation which is reentrant. That is, a 244 ``put()`` or ``get()`` call can be interrupted by another ``put()`` 245 call in the same thread without deadlocking or corrupting internal 246 state inside the queue. This makes it appropriate for use in 247 destructors such as ``__del__`` methods or :mod:`weakref` callbacks. 248 249 250.. method:: SimpleQueue.put_nowait(item) 251 252 Equivalent to ``put(item)``, provided for compatibility with 253 :meth:`Queue.put_nowait`. 254 255 256.. method:: SimpleQueue.get(block=True, timeout=None) 257 258 Remove and return an item from the queue. If optional args *block* is true and 259 *timeout* is ``None`` (the default), block if necessary until an item is available. 260 If *timeout* is a positive number, it blocks at most *timeout* seconds and 261 raises the :exc:`Empty` exception if no item was available within that time. 262 Otherwise (*block* is false), return an item if one is immediately available, 263 else raise the :exc:`Empty` exception (*timeout* is ignored in that case). 264 265 266.. method:: SimpleQueue.get_nowait() 267 268 Equivalent to ``get(False)``. 269 270 271.. seealso:: 272 273 Class :class:`multiprocessing.Queue` 274 A queue class for use in a multi-processing (rather than multi-threading) 275 context. 276 277 :class:`collections.deque` is an alternative implementation of unbounded 278 queues with fast atomic :meth:`~collections.deque.append` and 279 :meth:`~collections.deque.popleft` operations that do not require locking 280 and also support indexing. 281