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 that would be returned by ``min(entries)``). A typical pattern for 61 entries 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.. exception:: ShutDown 97 98 Exception raised when :meth:`~Queue.put` or :meth:`~Queue.get` is called on 99 a :class:`Queue` object which has been shut down. 100 101 .. versionadded:: 3.13 102 103 104.. _queueobjects: 105 106Queue Objects 107------------- 108 109Queue objects (:class:`Queue`, :class:`LifoQueue`, or :class:`PriorityQueue`) 110provide the public methods described below. 111 112 113.. method:: Queue.qsize() 114 115 Return the approximate size of the queue. Note, qsize() > 0 doesn't 116 guarantee that a subsequent get() will not block, nor will qsize() < maxsize 117 guarantee that put() will not block. 118 119 120.. method:: Queue.empty() 121 122 Return ``True`` if the queue is empty, ``False`` otherwise. If empty() 123 returns ``True`` it doesn't guarantee that a subsequent call to put() 124 will not block. Similarly, if empty() returns ``False`` it doesn't 125 guarantee that a subsequent call to get() will not block. 126 127 128.. method:: Queue.full() 129 130 Return ``True`` if the queue is full, ``False`` otherwise. If full() 131 returns ``True`` it doesn't guarantee that a subsequent call to get() 132 will not block. Similarly, if full() returns ``False`` it doesn't 133 guarantee that a subsequent call to put() will not block. 134 135 136.. method:: Queue.put(item, block=True, timeout=None) 137 138 Put *item* into the queue. If optional args *block* is true and *timeout* is 139 ``None`` (the default), block if necessary until a free slot is available. If 140 *timeout* is a positive number, it blocks at most *timeout* seconds and raises 141 the :exc:`Full` exception if no free slot was available within that time. 142 Otherwise (*block* is false), put an item on the queue if a free slot is 143 immediately available, else raise the :exc:`Full` exception (*timeout* is 144 ignored in that case). 145 146 Raises :exc:`ShutDown` if the queue has been shut down. 147 148 149.. method:: Queue.put_nowait(item) 150 151 Equivalent to ``put(item, block=False)``. 152 153 154.. method:: Queue.get(block=True, timeout=None) 155 156 Remove and return an item from the queue. If optional args *block* is true and 157 *timeout* is ``None`` (the default), block if necessary until an item is available. 158 If *timeout* is a positive number, it blocks at most *timeout* seconds and 159 raises the :exc:`Empty` exception if no item was available within that time. 160 Otherwise (*block* is false), return an item if one is immediately available, 161 else raise the :exc:`Empty` exception (*timeout* is ignored in that case). 162 163 Prior to 3.0 on POSIX systems, and for all versions on Windows, if 164 *block* is true and *timeout* is ``None``, this operation goes into 165 an uninterruptible wait on an underlying lock. This means that no exceptions 166 can occur, and in particular a SIGINT will not trigger a :exc:`KeyboardInterrupt`. 167 168 Raises :exc:`ShutDown` if the queue has been shut down and is empty, or if 169 the queue has been shut down immediately. 170 171 172.. method:: Queue.get_nowait() 173 174 Equivalent to ``get(False)``. 175 176Two methods are offered to support tracking whether enqueued tasks have been 177fully processed by daemon consumer threads. 178 179 180.. method:: Queue.task_done() 181 182 Indicate that a formerly enqueued task is complete. Used by queue consumer 183 threads. For each :meth:`get` used to fetch a task, a subsequent call to 184 :meth:`task_done` tells the queue that the processing on the task is complete. 185 186 If a :meth:`join` is currently blocking, it will resume when all items have been 187 processed (meaning that a :meth:`task_done` call was received for every item 188 that had been :meth:`put` into the queue). 189 190 ``shutdown(immediate=True)`` calls :meth:`task_done` for each remaining item 191 in the queue. 192 193 Raises a :exc:`ValueError` if called more times than there were items placed in 194 the queue. 195 196 197.. method:: Queue.join() 198 199 Blocks until all items in the queue have been gotten and processed. 200 201 The count of unfinished tasks goes up whenever an item is added to the queue. 202 The count goes down whenever a consumer thread calls :meth:`task_done` to 203 indicate that the item was retrieved and all work on it is complete. When the 204 count of unfinished tasks drops to zero, :meth:`join` unblocks. 205 206 207Example of how to wait for enqueued tasks to be completed:: 208 209 import threading 210 import queue 211 212 q = queue.Queue() 213 214 def worker(): 215 while True: 216 item = q.get() 217 print(f'Working on {item}') 218 print(f'Finished {item}') 219 q.task_done() 220 221 # Turn-on the worker thread. 222 threading.Thread(target=worker, daemon=True).start() 223 224 # Send thirty task requests to the worker. 225 for item in range(30): 226 q.put(item) 227 228 # Block until all tasks are done. 229 q.join() 230 print('All work completed') 231 232 233Terminating queues 234^^^^^^^^^^^^^^^^^^ 235 236:class:`Queue` objects can be made to prevent further interaction by shutting 237them down. 238 239.. method:: Queue.shutdown(immediate=False) 240 241 Shut down the queue, making :meth:`~Queue.get` and :meth:`~Queue.put` raise 242 :exc:`ShutDown`. 243 244 By default, :meth:`~Queue.get` on a shut down queue will only raise once the 245 queue is empty. Set *immediate* to true to make :meth:`~Queue.get` raise 246 immediately instead. 247 248 All blocked callers of :meth:`~Queue.put` and :meth:`~Queue.get` will be 249 unblocked. If *immediate* is true, a task will be marked as done for each 250 remaining item in the queue, which may unblock callers of 251 :meth:`~Queue.join`. 252 253 .. versionadded:: 3.13 254 255 256SimpleQueue Objects 257------------------- 258 259:class:`SimpleQueue` objects provide the public methods described below. 260 261.. method:: SimpleQueue.qsize() 262 263 Return the approximate size of the queue. Note, qsize() > 0 doesn't 264 guarantee that a subsequent get() will not block. 265 266 267.. method:: SimpleQueue.empty() 268 269 Return ``True`` if the queue is empty, ``False`` otherwise. If empty() 270 returns ``False`` it doesn't guarantee that a subsequent call to get() 271 will not block. 272 273 274.. method:: SimpleQueue.put(item, block=True, timeout=None) 275 276 Put *item* into the queue. The method never blocks and always succeeds 277 (except for potential low-level errors such as failure to allocate memory). 278 The optional args *block* and *timeout* are ignored and only provided 279 for compatibility with :meth:`Queue.put`. 280 281 .. impl-detail:: 282 This method has a C implementation which is reentrant. That is, a 283 ``put()`` or ``get()`` call can be interrupted by another ``put()`` 284 call in the same thread without deadlocking or corrupting internal 285 state inside the queue. This makes it appropriate for use in 286 destructors such as ``__del__`` methods or :mod:`weakref` callbacks. 287 288 289.. method:: SimpleQueue.put_nowait(item) 290 291 Equivalent to ``put(item, block=False)``, provided for compatibility with 292 :meth:`Queue.put_nowait`. 293 294 295.. method:: SimpleQueue.get(block=True, timeout=None) 296 297 Remove and return an item from the queue. If optional args *block* is true and 298 *timeout* is ``None`` (the default), block if necessary until an item is available. 299 If *timeout* is a positive number, it blocks at most *timeout* seconds and 300 raises the :exc:`Empty` exception if no item was available within that time. 301 Otherwise (*block* is false), return an item if one is immediately available, 302 else raise the :exc:`Empty` exception (*timeout* is ignored in that case). 303 304 305.. method:: SimpleQueue.get_nowait() 306 307 Equivalent to ``get(False)``. 308 309 310.. seealso:: 311 312 Class :class:`multiprocessing.Queue` 313 A queue class for use in a multi-processing (rather than multi-threading) 314 context. 315 316 :class:`collections.deque` is an alternative implementation of unbounded 317 queues with fast atomic :meth:`~collections.deque.append` and 318 :meth:`~collections.deque.popleft` operations that do not require locking 319 and also support indexing. 320