Mercurial > cpython-lru_cache-weakref

annotate Doc/library/queue.rst @ 80661:94de77bd0b4b 2.7

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Issue #16194: document imp.load_dynamic problems when read several extension modules from the same binary object file.
author Andrew Svetlov <andrew.svetlov@gmail.com>
date Thu, 29 Nov 2012 19:51:28 +0200
parents 5683ca62a954
children c24941251473
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
71381
60ce5f279a5e Issue #12574: correct capitalization of the Queue module. Patch by Rafe Kettler
Eli Bendersky <eliben@gmail.com>
parents: 68256
diff changeset
1 :mod:`Queue` --- A synchronized queue class
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2 ===========================================
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
3
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
4 .. module:: Queue
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
5 :synopsis: A synchronized queue class.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
6
46900
a9495a3fe2e0 Added test for Queue rename warning.
Alexandre Vassalotti <alexandre@peadrop.com>
parents: 45120
diff changeset
7 .. note::
76732
8aab13719c02 Use Python 3 instead of 3.0.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 71952
diff changeset
8 The :mod:`Queue` module has been renamed to :mod:`queue` in Python 3. The
47248
9acb314b9072 Queue renaming reversal part 3: move module into place and
Georg Brandl <georg@python.org>
parents: 46939
diff changeset
9 :term:`2to3` tool will automatically adapt imports when converting your
76732
8aab13719c02 Use Python 3 instead of 3.0.
Ezio Melotti <ezio.melotti@gmail.com>
parents: 71952
diff changeset
10 sources to Python 3.
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
11
71952
b5674229d0f9 Backport source links from 3.x.
Éric Araujo <merwok@netwok.org>
parents: 71381
diff changeset
12 **Source code:** :source:`Lib/Queue.py`
b5674229d0f9 Backport source links from 3.x.
Éric Araujo <merwok@netwok.org>
parents: 71381
diff changeset
13
b5674229d0f9 Backport source links from 3.x.
Éric Araujo <merwok@netwok.org>
parents: 71381
diff changeset
14 --------------
46939
4ac9cc1d7798 Fix-up docs for socketserver and queue renaming.
Georg Brandl <georg@python.org>
parents: 46900
diff changeset
15
47248
9acb314b9072 Queue renaming reversal part 3: move module into place and
Georg Brandl <georg@python.org>
parents: 46939
diff changeset
16 The :mod:`Queue` module implements multi-producer, multi-consumer queues.
43223
2052f54ced49 Added cross-references plus a note about dict & list shallow copying.
Mark Summerfield <list@qtrac.plus.com>
parents: 42604
diff changeset
17 It is especially useful in threaded programming when information must be
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
18 exchanged safely between multiple threads. The :class:`Queue` class in this
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
19 module implements all the required locking semantics. It depends on the
43223
2052f54ced49 Added cross-references plus a note about dict & list shallow copying.
Mark Summerfield <list@qtrac.plus.com>
parents: 42604
diff changeset
20 availability of thread support in Python; see the :mod:`threading`
2052f54ced49 Added cross-references plus a note about dict & list shallow copying.
Mark Summerfield <list@qtrac.plus.com>
parents: 42604
diff changeset
21 module.
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
22
76844
5683ca62a954 Improve the grammar of a non-sentence.
R David Murray <rdmurray@bitdance.com>
parents: 76732
diff changeset
23 The module implements three types of queue, which differ only in the order in
5683ca62a954 Improve the grammar of a non-sentence.
R David Murray <rdmurray@bitdance.com>
parents: 76732
diff changeset
24 which the entries are retrieved. In a FIFO queue, the first tasks added are
44713
c784f20c967e Minor wordsmithing.
Raymond Hettinger <python@rcn.com>
parents: 44688
diff changeset
25 the first retrieved. In a LIFO queue, the most recently added entry is
c784f20c967e Minor wordsmithing.
Raymond Hettinger <python@rcn.com>
parents: 44688
diff changeset
26 the first retrieved (operating like a stack). With a priority queue,
c784f20c967e Minor wordsmithing.
Raymond Hettinger <python@rcn.com>
parents: 44688
diff changeset
27 the entries are kept sorted (using the :mod:`heapq` module) and the
c784f20c967e Minor wordsmithing.
Raymond Hettinger <python@rcn.com>
parents: 44688
diff changeset
28 lowest valued entry is retrieved first.
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
29
47248
9acb314b9072 Queue renaming reversal part 3: move module into place and
Georg Brandl <georg@python.org>
parents: 46939
diff changeset
30 The :mod:`Queue` module defines the following classes and exceptions:
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
31
61738
6ae073326e7f Merged revisions 78463 via svnmerge from
Georg Brandl <georg@python.org>
parents: 52110
diff changeset
32 .. class:: Queue(maxsize=0)
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
33
44713
c784f20c967e Minor wordsmithing.
Raymond Hettinger <python@rcn.com>
parents: 44688
diff changeset
34 Constructor for a FIFO queue. *maxsize* is an integer that sets the upperbound
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
35 limit on the number of items that can be placed in the queue. Insertion will
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
36 block once this size has been reached, until queue items are consumed. If
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
37 *maxsize* is less than or equal to zero, the queue size is infinite.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
38
61738
6ae073326e7f Merged revisions 78463 via svnmerge from
Georg Brandl <georg@python.org>
parents: 52110
diff changeset
39 .. class:: LifoQueue(maxsize=0)
44713
c784f20c967e Minor wordsmithing.
Raymond Hettinger <python@rcn.com>
parents: 44688
diff changeset
40
c784f20c967e Minor wordsmithing.
Raymond Hettinger <python@rcn.com>
parents: 44688
diff changeset
41 Constructor for a LIFO queue. *maxsize* is an integer that sets the upperbound
c784f20c967e Minor wordsmithing.
Raymond Hettinger <python@rcn.com>
parents: 44688
diff changeset
42 limit on the number of items that can be placed in the queue. Insertion will
c784f20c967e Minor wordsmithing.
Raymond Hettinger <python@rcn.com>
parents: 44688
diff changeset
43 block once this size has been reached, until queue items are consumed. If
c784f20c967e Minor wordsmithing.
Raymond Hettinger <python@rcn.com>
parents: 44688
diff changeset
44 *maxsize* is less than or equal to zero, the queue size is infinite.
c784f20c967e Minor wordsmithing.
Raymond Hettinger <python@rcn.com>
parents: 44688
diff changeset
45
44722
170cb2739a39 Note versionadded.
Raymond Hettinger <python@rcn.com>
parents: 44713
diff changeset
46 .. versionadded:: 2.6
170cb2739a39 Note versionadded.
Raymond Hettinger <python@rcn.com>
parents: 44713
diff changeset
47
61738
6ae073326e7f Merged revisions 78463 via svnmerge from
Georg Brandl <georg@python.org>
parents: 52110
diff changeset
48 .. class:: PriorityQueue(maxsize=0)
44713
c784f20c967e Minor wordsmithing.
Raymond Hettinger <python@rcn.com>
parents: 44688
diff changeset
49
c784f20c967e Minor wordsmithing.
Raymond Hettinger <python@rcn.com>
parents: 44688
diff changeset
50 Constructor for a priority queue. *maxsize* is an integer that sets the upperbound
c784f20c967e Minor wordsmithing.
Raymond Hettinger <python@rcn.com>
parents: 44688
diff changeset
51 limit on the number of items that can be placed in the queue. Insertion will
c784f20c967e Minor wordsmithing.
Raymond Hettinger <python@rcn.com>
parents: 44688
diff changeset
52 block once this size has been reached, until queue items are consumed. If
c784f20c967e Minor wordsmithing.
Raymond Hettinger <python@rcn.com>
parents: 44688
diff changeset
53 *maxsize* is less than or equal to zero, the queue size is infinite.
c784f20c967e Minor wordsmithing.
Raymond Hettinger <python@rcn.com>
parents: 44688
diff changeset
54
c784f20c967e Minor wordsmithing.
Raymond Hettinger <python@rcn.com>
parents: 44688
diff changeset
55 The lowest valued entries are retrieved first (the lowest valued entry is the
c784f20c967e Minor wordsmithing.
Raymond Hettinger <python@rcn.com>
parents: 44688
diff changeset
56 one returned by ``sorted(list(entries))[0]``). A typical pattern for entries
c784f20c967e Minor wordsmithing.
Raymond Hettinger <python@rcn.com>
parents: 44688
diff changeset
57 is a tuple in the form: ``(priority_number, data)``.
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
58
44722
170cb2739a39 Note versionadded.
Raymond Hettinger <python@rcn.com>
parents: 44713
diff changeset
59 .. versionadded:: 2.6
170cb2739a39 Note versionadded.
Raymond Hettinger <python@rcn.com>
parents: 44713
diff changeset
60
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
61 .. exception:: Empty
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
62
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
63 Exception raised when non-blocking :meth:`get` (or :meth:`get_nowait`) is called
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
64 on a :class:`Queue` object which is empty.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
65
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
66
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
67 .. exception:: Full
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
68
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
69 Exception raised when non-blocking :meth:`put` (or :meth:`put_nowait`) is called
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
70 on a :class:`Queue` object which is full.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
71
52097
5c91a6e18564 Add cross-reference to the collections docs.
Raymond Hettinger <python@rcn.com>
parents: 47248
diff changeset
72 .. seealso::
5c91a6e18564 Add cross-reference to the collections docs.
Raymond Hettinger <python@rcn.com>
parents: 47248
diff changeset
73
5c91a6e18564 Add cross-reference to the collections docs.
Raymond Hettinger <python@rcn.com>
parents: 47248
diff changeset
74 :class:`collections.deque` is an alternative implementation of unbounded
5c91a6e18564 Add cross-reference to the collections docs.
Raymond Hettinger <python@rcn.com>
parents: 47248
diff changeset
75 queues with fast atomic :func:`append` and :func:`popleft` operations that
5c91a6e18564 Add cross-reference to the collections docs.
Raymond Hettinger <python@rcn.com>
parents: 47248
diff changeset
76 do not require locking.
5c91a6e18564 Add cross-reference to the collections docs.
Raymond Hettinger <python@rcn.com>
parents: 47248
diff changeset
77
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
78
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
79 .. _queueobjects:
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
80
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
81 Queue Objects
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
82 -------------
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
83
45120
c2dcf54e91fd Remove extra tick marks and add a missing closing parenthesis.
Brett Cannon <bcannon@gmail.com>
parents: 44722
diff changeset
84 Queue objects (:class:`Queue`, :class:`LifoQueue`, or :class:`PriorityQueue`)
47248
9acb314b9072 Queue renaming reversal part 3: move module into place and
Georg Brandl <georg@python.org>
parents: 46939
diff changeset
85 provide the public methods described below.
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
86
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
87
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
88 .. method:: Queue.qsize()
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
89
44688
14854c7c6a24 Small grammar nit
Raymond Hettinger <python@rcn.com>
parents: 44686
diff changeset
90 Return the approximate size of the queue. Note, qsize() > 0 doesn't
14854c7c6a24 Small grammar nit
Raymond Hettinger <python@rcn.com>
parents: 44686
diff changeset
91 guarantee that a subsequent get() will not block, nor will qsize() < maxsize
44686
d0208d65dc22 Better (?) text describing the lack of guarantees provided by qsize(),
Skip Montanaro <skip@pobox.com>
parents: 43223
diff changeset
92 guarantee that put() will not block.
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
93
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
94
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
95 .. method:: Queue.empty()
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
96
44686
d0208d65dc22 Better (?) text describing the lack of guarantees provided by qsize(),
Skip Montanaro <skip@pobox.com>
parents: 43223
diff changeset
97 Return ``True`` if the queue is empty, ``False`` otherwise. If empty()
d0208d65dc22 Better (?) text describing the lack of guarantees provided by qsize(),
Skip Montanaro <skip@pobox.com>
parents: 43223
diff changeset
98 returns ``True`` it doesn't guarantee that a subsequent call to put()
d0208d65dc22 Better (?) text describing the lack of guarantees provided by qsize(),
Skip Montanaro <skip@pobox.com>
parents: 43223
diff changeset
99 will not block. Similarly, if empty() returns ``False`` it doesn't
d0208d65dc22 Better (?) text describing the lack of guarantees provided by qsize(),
Skip Montanaro <skip@pobox.com>
parents: 43223
diff changeset
100 guarantee that a subsequent call to get() will not block.
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
101
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
102
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
103 .. method:: Queue.full()
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
104
44686
d0208d65dc22 Better (?) text describing the lack of guarantees provided by qsize(),
Skip Montanaro <skip@pobox.com>
parents: 43223
diff changeset
105 Return ``True`` if the queue is full, ``False`` otherwise. If full()
d0208d65dc22 Better (?) text describing the lack of guarantees provided by qsize(),
Skip Montanaro <skip@pobox.com>
parents: 43223
diff changeset
106 returns ``True`` it doesn't guarantee that a subsequent call to get()
d0208d65dc22 Better (?) text describing the lack of guarantees provided by qsize(),
Skip Montanaro <skip@pobox.com>
parents: 43223
diff changeset
107 will not block. Similarly, if full() returns ``False`` it doesn't
d0208d65dc22 Better (?) text describing the lack of guarantees provided by qsize(),
Skip Montanaro <skip@pobox.com>
parents: 43223
diff changeset
108 guarantee that a subsequent call to put() will not block.
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
109
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
110
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
111 .. method:: Queue.put(item[, block[, timeout]])
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
112
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
113 Put *item* into the queue. If optional args *block* is true and *timeout* is
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
114 None (the default), block if necessary until a free slot is available. If
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
115 *timeout* is a positive number, it blocks at most *timeout* seconds and raises
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
116 the :exc:`Full` exception if no free slot was available within that time.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
117 Otherwise (*block* is false), put an item on the queue if a free slot is
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
118 immediately available, else raise the :exc:`Full` exception (*timeout* is
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
119 ignored in that case).
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
120
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
121 .. versionadded:: 2.3
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
122 The *timeout* parameter.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
123
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
124
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
125 .. method:: Queue.put_nowait(item)
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
126
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
127 Equivalent to ``put(item, False)``.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
128
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
129
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
130 .. method:: Queue.get([block[, timeout]])
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
131
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
132 Remove and return an item from the queue. If optional args *block* is true and
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
133 *timeout* is None (the default), block if necessary until an item is available.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
134 If *timeout* is a positive number, it blocks at most *timeout* seconds and
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
135 raises the :exc:`Empty` exception if no item was available within that time.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
136 Otherwise (*block* is false), return an item if one is immediately available,
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
137 else raise the :exc:`Empty` exception (*timeout* is ignored in that case).
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
138
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
139 .. versionadded:: 2.3
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
140 The *timeout* parameter.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
141
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
142
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
143 .. method:: Queue.get_nowait()
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
144
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
145 Equivalent to ``get(False)``.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
146
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
147 Two methods are offered to support tracking whether enqueued tasks have been
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
148 fully processed by daemon consumer threads.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
149
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
150
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
151 .. method:: Queue.task_done()
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
152
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
153 Indicate that a formerly enqueued task is complete. Used by queue consumer
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
154 threads. For each :meth:`get` used to fetch a task, a subsequent call to
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
155 :meth:`task_done` tells the queue that the processing on the task is complete.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
156
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
157 If a :meth:`join` is currently blocking, it will resume when all items have been
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
158 processed (meaning that a :meth:`task_done` call was received for every item
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
159 that had been :meth:`put` into the queue).
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
160
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
161 Raises a :exc:`ValueError` if called more times than there were items placed in
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
162 the queue.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
163
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
164 .. versionadded:: 2.5
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
165
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
166
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
167 .. method:: Queue.join()
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
168
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
169 Blocks until all items in the queue have been gotten and processed.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
170
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
171 The count of unfinished tasks goes up whenever an item is added to the queue.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
172 The count goes down whenever a consumer thread calls :meth:`task_done` to
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
173 indicate that the item was retrieved and all work on it is complete. When the
52110
563b4f883ed8 Fix markup.
Raymond Hettinger <python@rcn.com>
parents: 52097
diff changeset
174 count of unfinished tasks drops to zero, :meth:`join` unblocks.
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
175
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
176 .. versionadded:: 2.5
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
177
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
178 Example of how to wait for enqueued tasks to be completed::
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
179
47248
9acb314b9072 Queue renaming reversal part 3: move module into place and
Georg Brandl <georg@python.org>
parents: 46939
diff changeset
180 def worker():
9acb314b9072 Queue renaming reversal part 3: move module into place and
Georg Brandl <georg@python.org>
parents: 46939
diff changeset
181 while True:
9acb314b9072 Queue renaming reversal part 3: move module into place and
Georg Brandl <georg@python.org>
parents: 46939
diff changeset
182 item = q.get()
9acb314b9072 Queue renaming reversal part 3: move module into place and
Georg Brandl <georg@python.org>
parents: 46939
diff changeset
183 do_work(item)
9acb314b9072 Queue renaming reversal part 3: move module into place and
Georg Brandl <georg@python.org>
parents: 46939
diff changeset
184 q.task_done()
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
185
47248
9acb314b9072 Queue renaming reversal part 3: move module into place and
Georg Brandl <georg@python.org>
parents: 46939
diff changeset
186 q = Queue()
9acb314b9072 Queue renaming reversal part 3: move module into place and
Georg Brandl <georg@python.org>
parents: 46939
diff changeset
187 for i in range(num_worker_threads):
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
188 t = Thread(target=worker)
56639
bdc390721f97 use property api
Benjamin Peterson <benjamin@python.org>
parents: 52110
diff changeset
189 t.daemon = True
47248
9acb314b9072 Queue renaming reversal part 3: move module into place and
Georg Brandl <georg@python.org>
parents: 46939
diff changeset
190 t.start()
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
191
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
192 for item in source():
47248
9acb314b9072 Queue renaming reversal part 3: move module into place and
Georg Brandl <georg@python.org>
parents: 46939
diff changeset
193 q.put(item)
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
194
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
195 q.join() # block until all tasks are done
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
196