Mercurial > cpython-lru_cache-weakref

annotate Doc/library/queue.rst @ 65035:87f4b32905df 2.7

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Cosmetic fix to use print function.
author Hirokazu Yamamoto <ocean-city@m2.ccsnet.ne.jp>
date Fri, 01 Oct 2010 10:48:47 +0000
parents ad2f5eacd2a0
children fdd3681b1439
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
46939
4ac9cc1d7798 Fix-up docs for socketserver and queue renaming.
Georg Brandl <georg@python.org>
parents: 46900
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::
47248
9acb314b9072 Queue renaming reversal part 3: move module into place and
Georg Brandl <georg@python.org>
parents: 46939
diff changeset
8 The :mod:`Queue` module has been renamed to :mod:`queue` in Python 3.0. The
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
9acb314b9072 Queue renaming reversal part 3: move module into place and
Georg Brandl <georg@python.org>
parents: 46939
diff changeset
10 sources to 3.0.
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
11
46939
4ac9cc1d7798 Fix-up docs for socketserver and queue renaming.
Georg Brandl <georg@python.org>
parents: 46900
diff changeset
12
47248
9acb314b9072 Queue renaming reversal part 3: move module into place and
Georg Brandl <georg@python.org>
parents: 46939
diff changeset
13 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
14 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
15 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
16 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
17 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
18 module.
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
19
44713
c784f20c967e Minor wordsmithing.
Raymond Hettinger <python@rcn.com>
parents: 44688
diff changeset
20 Implements three types of queue whose only difference is the order that
c784f20c967e Minor wordsmithing.
Raymond Hettinger <python@rcn.com>
parents: 44688
diff changeset
21 the entries are retrieved. In a FIFO queue, the first tasks added are
c784f20c967e Minor wordsmithing.
Raymond Hettinger <python@rcn.com>
parents: 44688
diff changeset
22 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
23 the first retrieved (operating like a stack). With a priority queue,
c784f20c967e Minor wordsmithing.
Raymond Hettinger <python@rcn.com>
parents: 44688
diff changeset
24 the entries are kept sorted (using the :mod:`heapq` module) and the
c784f20c967e Minor wordsmithing.
Raymond Hettinger <python@rcn.com>
parents: 44688
diff changeset
25 lowest valued entry is retrieved first.
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
26
47248
9acb314b9072 Queue renaming reversal part 3: move module into place and
Georg Brandl <georg@python.org>
parents: 46939
diff changeset
27 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
28
59149
ad2f5eacd2a0 #7407: specify default maxsize value; patch by Floris Bruynooghe
Andrew M. Kuchling <amk@amk.ca>
parents: 56639
diff changeset
29 .. class:: Queue(maxsize=0)
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
30
44713
c784f20c967e Minor wordsmithing.
Raymond Hettinger <python@rcn.com>
parents: 44688
diff changeset
31 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
32 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
33 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
34 *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
35
59149
ad2f5eacd2a0 #7407: specify default maxsize value; patch by Floris Bruynooghe
Andrew M. Kuchling <amk@amk.ca>
parents: 56639
diff changeset
36 .. class:: LifoQueue(maxsize=0)
44713
c784f20c967e Minor wordsmithing.
Raymond Hettinger <python@rcn.com>
parents: 44688
diff changeset
37
c784f20c967e Minor wordsmithing.
Raymond Hettinger <python@rcn.com>
parents: 44688
diff changeset
38 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
39 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
40 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
41 *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
42
44722
170cb2739a39 Note versionadded.
Raymond Hettinger <python@rcn.com>
parents: 44713
diff changeset
43 .. versionadded:: 2.6
170cb2739a39 Note versionadded.
Raymond Hettinger <python@rcn.com>
parents: 44713
diff changeset
44
59149
ad2f5eacd2a0 #7407: specify default maxsize value; patch by Floris Bruynooghe
Andrew M. Kuchling <amk@amk.ca>
parents: 56639
diff changeset
45 .. class:: PriorityQueue(maxsize=0)
44713
c784f20c967e Minor wordsmithing.
Raymond Hettinger <python@rcn.com>
parents: 44688
diff changeset
46
c784f20c967e Minor wordsmithing.
Raymond Hettinger <python@rcn.com>
parents: 44688
diff changeset
47 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
48 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
49 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
50 *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
51
c784f20c967e Minor wordsmithing.
Raymond Hettinger <python@rcn.com>
parents: 44688
diff changeset
52 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
53 one returned by ``sorted(list(entries))[0]``). A typical pattern for entries
c784f20c967e Minor wordsmithing.
Raymond Hettinger <python@rcn.com>
parents: 44688
diff changeset
54 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
55
44722
170cb2739a39 Note versionadded.
Raymond Hettinger <python@rcn.com>
parents: 44713
diff changeset
56 .. versionadded:: 2.6
170cb2739a39 Note versionadded.
Raymond Hettinger <python@rcn.com>
parents: 44713
diff changeset
57
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
58 .. exception:: Empty
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
59
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
60 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
61 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
62
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
63
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
64 .. exception:: Full
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 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
67 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
68
52097
5c91a6e18564 Add cross-reference to the collections docs.
Raymond Hettinger <python@rcn.com>
parents: 47248
diff changeset
69 .. seealso::
5c91a6e18564 Add cross-reference to the collections docs.
Raymond Hettinger <python@rcn.com>
parents: 47248
diff changeset
70
5c91a6e18564 Add cross-reference to the collections docs.
Raymond Hettinger <python@rcn.com>
parents: 47248
diff changeset
71 :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
72 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
73 do not require locking.
5c91a6e18564 Add cross-reference to the collections docs.
Raymond Hettinger <python@rcn.com>
parents: 47248
diff changeset
74
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
75
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
76 .. _queueobjects:
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
77
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
78 Queue Objects
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
79 -------------
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
80
45120
c2dcf54e91fd Remove extra tick marks and add a missing closing parenthesis.
Brett Cannon <bcannon@gmail.com>
parents: 44722
diff changeset
81 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
82 provide the public methods described below.
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
83
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
84
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
85 .. method:: Queue.qsize()
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
86
44688
14854c7c6a24 Small grammar nit
Raymond Hettinger <python@rcn.com>
parents: 44686
diff changeset
87 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
88 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
89 guarantee that put() will not block.
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
90
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
91
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
92 .. method:: Queue.empty()
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
93
44686
d0208d65dc22 Better (?) text describing the lack of guarantees provided by qsize(),
Skip Montanaro <skip@pobox.com>
parents: 43223
diff changeset
94 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
95 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
96 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
97 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
98
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
99
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
100 .. method:: Queue.full()
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
101
44686
d0208d65dc22 Better (?) text describing the lack of guarantees provided by qsize(),
Skip Montanaro <skip@pobox.com>
parents: 43223
diff changeset
102 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
103 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
104 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
105 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
106
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
107
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
108 .. method:: Queue.put(item[, block[, timeout]])
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 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
111 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
112 *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
113 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
114 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
115 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
116 ignored in that case).
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
117
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
118 .. versionadded:: 2.3
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
119 The *timeout* parameter.
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
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
122 .. method:: Queue.put_nowait(item)
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 Equivalent to ``put(item, False)``.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
125
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 .. method:: Queue.get([block[, timeout]])
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 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
130 *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
131 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
132 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
133 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
134 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
135
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
136 .. versionadded:: 2.3
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
137 The *timeout* parameter.
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
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
140 .. method:: Queue.get_nowait()
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 Equivalent to ``get(False)``.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
143
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
144 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
145 fully processed by daemon consumer threads.
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
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
148 .. method:: Queue.task_done()
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 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
151 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
152 :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
153
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
154 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
155 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
156 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
157
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
158 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
159 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 .. versionadded:: 2.5
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
162
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 .. method:: Queue.join()
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 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
167
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
168 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
169 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
170 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
171 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
172
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
173 .. versionadded:: 2.5
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
174
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
175 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
176
47248
9acb314b9072 Queue renaming reversal part 3: move module into place and
Georg Brandl <georg@python.org>
parents: 46939
diff changeset
177 def worker():
9acb314b9072 Queue renaming reversal part 3: move module into place and
Georg Brandl <georg@python.org>
parents: 46939
diff changeset
178 while True:
9acb314b9072 Queue renaming reversal part 3: move module into place and
Georg Brandl <georg@python.org>
parents: 46939
diff changeset
179 item = q.get()
9acb314b9072 Queue renaming reversal part 3: move module into place and
Georg Brandl <georg@python.org>
parents: 46939
diff changeset
180 do_work(item)
9acb314b9072 Queue renaming reversal part 3: move module into place and
Georg Brandl <georg@python.org>
parents: 46939
diff changeset
181 q.task_done()
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
182
47248
9acb314b9072 Queue renaming reversal part 3: move module into place and
Georg Brandl <georg@python.org>
parents: 46939
diff changeset
183 q = Queue()
9acb314b9072 Queue renaming reversal part 3: move module into place and
Georg Brandl <georg@python.org>
parents: 46939
diff changeset
184 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
185 t = Thread(target=worker)
56639
bdc390721f97 use property api
Benjamin Peterson <benjamin@python.org>
parents: 52110
diff changeset
186 t.daemon = True
47248
9acb314b9072 Queue renaming reversal part 3: move module into place and
Georg Brandl <georg@python.org>
parents: 46939
diff changeset
187 t.start()
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
188
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
189 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
190 q.put(item)
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 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
193