1:mod:`Queue` --- A synchronized queue class
2===========================================
3
4.. module:: Queue
5   :synopsis: A synchronized queue class.
6
7.. note::
8   The :mod:`Queue` module has been renamed to :mod:`queue` in Python 3.  The
9   :term:`2to3` tool will automatically adapt imports when converting your
10   sources to Python 3.
11
12**Source code:** :source:`Lib/Queue.py`
13
14--------------
15
16The :mod:`Queue` module implements multi-producer, multi-consumer queues.
17It is especially useful in threaded programming when information must be
18exchanged safely between multiple threads.  The :class:`~Queue.Queue` class in this
19module implements all the required locking semantics.  It depends on the
20availability of thread support in Python; see the :mod:`threading`
21module.
22
23The module implements three types of queue, which differ only in the order in
24which the entries are retrieved.  In a FIFO queue, the first tasks added are
25the first retrieved. In a LIFO queue, the most recently added entry is
26the first retrieved (operating like a stack).  With a priority queue,
27the entries are kept sorted (using the :mod:`heapq` module) and the
28lowest valued entry is retrieved first.
29
30The :mod:`Queue` module defines the following classes and exceptions:
31
32.. class:: Queue(maxsize=0)
33
34   Constructor for a FIFO queue.  *maxsize* is an integer that sets the upperbound
35   limit on the number of items that can be placed in the queue.  Insertion will
36   block once this size has been reached, until queue items are consumed.  If
37   *maxsize* is less than or equal to zero, the queue size is infinite.
38
39.. class:: LifoQueue(maxsize=0)
40
41   Constructor for a LIFO queue.  *maxsize* is an integer that sets the upperbound
42   limit on the number of items that can be placed in the queue.  Insertion will
43   block once this size has been reached, until queue items are consumed.  If
44   *maxsize* is less than or equal to zero, the queue size is infinite.
45
46   .. versionadded:: 2.6
47
48.. class:: PriorityQueue(maxsize=0)
49
50   Constructor for a priority queue.  *maxsize* is an integer that sets the upperbound
51   limit on the number of items that can be placed in the queue.  Insertion will
52   block once this size has been reached, until queue items are consumed.  If
53   *maxsize* is less than or equal to zero, the queue size is infinite.
54
55   The lowest valued entries are retrieved first (the lowest valued entry is the
56   one returned by ``sorted(list(entries))[0]``).  A typical pattern for entries
57   is a tuple in the form: ``(priority_number, data)``.
58
59   .. versionadded:: 2.6
60
61.. exception:: Empty
62
63   Exception raised when non-blocking :meth:`~Queue.get` (or
64   :meth:`~Queue.get_nowait`) is called
65   on a :class:`~Queue.Queue` object which is empty.
66
67
68.. exception:: Full
69
70   Exception raised when non-blocking :meth:`~Queue.put` (or
71   :meth:`~Queue.put_nowait`) is called
72   on a :class:`~Queue.Queue` object which is full.
73
74.. seealso::
75
76   :class:`collections.deque` is an alternative implementation of unbounded
77   queues with fast atomic :func:`append` and :func:`popleft` operations that
78   do not require locking.
79
80
81.. _queueobjects:
82
83Queue Objects
84-------------
85
86Queue objects (:class:`~Queue.Queue`, :class:`LifoQueue`, or :class:`PriorityQueue`)
87provide the public methods described below.
88
89
90.. method:: Queue.qsize()
91
92   Return the approximate size of the queue.  Note, qsize() > 0 doesn't
93   guarantee that a subsequent get() will not block, nor will qsize() < maxsize
94   guarantee that put() will not block.
95
96
97.. method:: Queue.empty()
98
99   Return ``True`` if the queue is empty, ``False`` otherwise.  If empty()
100   returns ``True`` it doesn't guarantee that a subsequent call to put()
101   will not block.  Similarly, if empty() returns ``False`` it doesn't
102   guarantee that a subsequent call to get() will not block.
103
104
105.. method:: Queue.full()
106
107   Return ``True`` if the queue is full, ``False`` otherwise.  If full()
108   returns ``True`` it doesn't guarantee that a subsequent call to get()
109   will not block.  Similarly, if full() returns ``False`` it doesn't
110   guarantee that a subsequent call to put() will not block.
111
112
113.. method:: Queue.put(item[, block[, timeout]])
114
115   Put *item* into the queue. If optional args *block* is true and *timeout* is
116   ``None`` (the default), block if necessary until a free slot is available. If
117   *timeout* is a positive number, it blocks at most *timeout* seconds and raises
118   the :exc:`Full` exception if no free slot was available within that time.
119   Otherwise (*block* is false), put an item on the queue if a free slot is
120   immediately available, else raise the :exc:`Full` exception (*timeout* is
121   ignored in that case).
122
123   .. versionadded:: 2.3
124      The *timeout* parameter.
125
126
127.. method:: Queue.put_nowait(item)
128
129   Equivalent to ``put(item, False)``.
130
131
132.. method:: Queue.get([block[, timeout]])
133
134   Remove and return an item from the queue. If optional args *block* is true and
135   *timeout* is ``None`` (the default), block if necessary until an item is available.
136   If *timeout* is a positive number, it blocks at most *timeout* seconds and
137   raises the :exc:`Empty` exception if no item was available within that time.
138   Otherwise (*block* is false), return an item if one is immediately available,
139   else raise the :exc:`Empty` exception (*timeout* is ignored in that case).
140
141   .. versionadded:: 2.3
142      The *timeout* parameter.
143
144
145.. method:: Queue.get_nowait()
146
147   Equivalent to ``get(False)``.
148
149Two methods are offered to support tracking whether enqueued tasks have been
150fully processed by daemon consumer threads.
151
152
153.. method:: Queue.task_done()
154
155   Indicate that a formerly enqueued task is complete.  Used by queue consumer
156   threads.  For each :meth:`get` used to fetch a task, a subsequent call to
157   :meth:`task_done` tells the queue that the processing on the task is complete.
158
159   If a :meth:`join` is currently blocking, it will resume when all items have been
160   processed (meaning that a :meth:`task_done` call was received for every item
161   that had been :meth:`put` into the queue).
162
163   Raises a :exc:`ValueError` if called more times than there were items placed in
164   the queue.
165
166   .. versionadded:: 2.5
167
168
169.. method:: Queue.join()
170
171   Blocks until all items in the queue have been gotten and processed.
172
173   The count of unfinished tasks goes up whenever an item is added to the queue.
174   The count goes down whenever a consumer thread calls :meth:`task_done` to
175   indicate that the item was retrieved and all work on it is complete. When the
176   count of unfinished tasks drops to zero, :meth:`join` unblocks.
177
178   .. versionadded:: 2.5
179
180Example of how to wait for enqueued tasks to be completed::
181
182   def worker():
183       while True:
184           item = q.get()
185           do_work(item)
186           q.task_done()
187
188   q = Queue()
189   for i in range(num_worker_threads):
190        t = Thread(target=worker)
191        t.daemon = True
192        t.start()
193
194   for item in source():
195       q.put(item)
196
197   q.join()       # block until all tasks are done
198
199