Mercurial > cpython-lru_cache-weakref

annotate Doc/library/queue.rst @ 78069:a8aa77458e12 3.2

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Add c_size_t and c_ssize_t to the ctypes summary table.
author Antoine Pitrou <solipsis@pitrou.net>
date Thu, 12 Jul 2012 20:31:50 +0200
parents 597826f7f6f5
children 6575074aae1c
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
46899
bd2c95c165ea Rename Queue module to queue.
Alexandre Vassalotti <alexandre@peadrop.com>
parents: 46539
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
46899
bd2c95c165ea Rename Queue module to queue.
Alexandre Vassalotti <alexandre@peadrop.com>
parents: 46539
diff changeset
4 .. module:: queue
42604
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
67501
974b27c9d849 Move source links to consistent location and remove wordy, big yellow boxes.
Raymond Hettinger <python@rcn.com>
parents: 67438
diff changeset
7 **Source code:** :source:`Lib/queue.py`
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
8
67504
c4a52526e77f Separate source link from main text.
Raymond Hettinger <python@rcn.com>
parents: 67501
diff changeset
9 --------------
c4a52526e77f Separate source link from main text.
Raymond Hettinger <python@rcn.com>
parents: 67501
diff changeset
10
46899
bd2c95c165ea Rename Queue module to queue.
Alexandre Vassalotti <alexandre@peadrop.com>
parents: 46539
diff changeset
11 The :mod:`queue` module implements multi-producer, multi-consumer queues.
43292
876b7ef4775d Merged revisions 57778-58052 via svnmerge from
Thomas Wouters <thomas@python.org>
parents: 43176
diff changeset
12 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
13 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
14 module implements all the required locking semantics. It depends on the
43292
876b7ef4775d Merged revisions 57778-58052 via svnmerge from
Thomas Wouters <thomas@python.org>
parents: 43176
diff changeset
15 availability of thread support in Python; see the :mod:`threading`
876b7ef4775d Merged revisions 57778-58052 via svnmerge from
Thomas Wouters <thomas@python.org>
parents: 43176
diff changeset
16 module.
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
17
76842
597826f7f6f5 Improve the grammar of a non-sentence.
R David Murray <rdmurray@bitdance.com>
parents: 67504
diff changeset
18 The module implements three types of queue, which differ only in the order in
597826f7f6f5 Improve the grammar of a non-sentence.
R David Murray <rdmurray@bitdance.com>
parents: 67504
diff changeset
19 which the entries are retrieved. In a FIFO queue, the first tasks added are
44716
b469e90273eb Sync-up Queue.py with Py2.6
Raymond Hettinger <python@rcn.com>
parents: 44699
diff changeset
20 the first retrieved. In a LIFO queue, the most recently added entry is
b469e90273eb Sync-up Queue.py with Py2.6
Raymond Hettinger <python@rcn.com>
parents: 44699
diff changeset
21 the first retrieved (operating like a stack). With a priority queue,
b469e90273eb Sync-up Queue.py with Py2.6
Raymond Hettinger <python@rcn.com>
parents: 44699
diff changeset
22 the entries are kept sorted (using the :mod:`heapq` module) and the
b469e90273eb Sync-up Queue.py with Py2.6
Raymond Hettinger <python@rcn.com>
parents: 44699
diff changeset
23 lowest valued entry is retrieved first.
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
24
66209
bb12374c8dc6 Provide links to Python source where the code is short, readable and
Éric Araujo <merwok@netwok.org>
parents: 59150
diff changeset
25
46899
bd2c95c165ea Rename Queue module to queue.
Alexandre Vassalotti <alexandre@peadrop.com>
parents: 46539
diff changeset
26 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
27
59150
9ac35215af4a Merged revisions 78463 via svnmerge from
Andrew M. Kuchling <amk@amk.ca>
parents: 55802
diff changeset
28 .. class:: Queue(maxsize=0)
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
29
44716
b469e90273eb Sync-up Queue.py with Py2.6
Raymond Hettinger <python@rcn.com>
parents: 44699
diff changeset
30 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
31 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
32 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
33 *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
34
59150
9ac35215af4a Merged revisions 78463 via svnmerge from
Andrew M. Kuchling <amk@amk.ca>
parents: 55802
diff changeset
35 .. class:: LifoQueue(maxsize=0)
44716
b469e90273eb Sync-up Queue.py with Py2.6
Raymond Hettinger <python@rcn.com>
parents: 44699
diff changeset
36
b469e90273eb Sync-up Queue.py with Py2.6
Raymond Hettinger <python@rcn.com>
parents: 44699
diff changeset
37 Constructor for a LIFO queue. *maxsize* is an integer that sets the upperbound
b469e90273eb Sync-up Queue.py with Py2.6
Raymond Hettinger <python@rcn.com>
parents: 44699
diff changeset
38 limit on the number of items that can be placed in the queue. Insertion will
b469e90273eb Sync-up Queue.py with Py2.6
Raymond Hettinger <python@rcn.com>
parents: 44699
diff changeset
39 block once this size has been reached, until queue items are consumed. If
b469e90273eb Sync-up Queue.py with Py2.6
Raymond Hettinger <python@rcn.com>
parents: 44699
diff changeset
40 *maxsize* is less than or equal to zero, the queue size is infinite.
b469e90273eb Sync-up Queue.py with Py2.6
Raymond Hettinger <python@rcn.com>
parents: 44699
diff changeset
41
44742
14d4104976fc Merged revisions 59985-60000,60002,60005-60007,60009-60042 via svnmerge from
Christian Heimes <christian@cheimes.de>
parents: 44716
diff changeset
42
59150
9ac35215af4a Merged revisions 78463 via svnmerge from
Andrew M. Kuchling <amk@amk.ca>
parents: 55802
diff changeset
43 .. class:: PriorityQueue(maxsize=0)
44716
b469e90273eb Sync-up Queue.py with Py2.6
Raymond Hettinger <python@rcn.com>
parents: 44699
diff changeset
44
b469e90273eb Sync-up Queue.py with Py2.6
Raymond Hettinger <python@rcn.com>
parents: 44699
diff changeset
45 Constructor for a priority queue. *maxsize* is an integer that sets the upperbound
b469e90273eb Sync-up Queue.py with Py2.6
Raymond Hettinger <python@rcn.com>
parents: 44699
diff changeset
46 limit on the number of items that can be placed in the queue. Insertion will
b469e90273eb Sync-up Queue.py with Py2.6
Raymond Hettinger <python@rcn.com>
parents: 44699
diff changeset
47 block once this size has been reached, until queue items are consumed. If
b469e90273eb Sync-up Queue.py with Py2.6
Raymond Hettinger <python@rcn.com>
parents: 44699
diff changeset
48 *maxsize* is less than or equal to zero, the queue size is infinite.
b469e90273eb Sync-up Queue.py with Py2.6
Raymond Hettinger <python@rcn.com>
parents: 44699
diff changeset
49
b469e90273eb Sync-up Queue.py with Py2.6
Raymond Hettinger <python@rcn.com>
parents: 44699
diff changeset
50 The lowest valued entries are retrieved first (the lowest valued entry is the
b469e90273eb Sync-up Queue.py with Py2.6
Raymond Hettinger <python@rcn.com>
parents: 44699
diff changeset
51 one returned by ``sorted(list(entries))[0]``). A typical pattern for entries
b469e90273eb Sync-up Queue.py with Py2.6
Raymond Hettinger <python@rcn.com>
parents: 44699
diff changeset
52 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
53
44742
14d4104976fc Merged revisions 59985-60000,60002,60005-60007,60009-60042 via svnmerge from
Christian Heimes <christian@cheimes.de>
parents: 44716
diff changeset
54
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
55 .. exception:: Empty
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
56
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
57 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
58 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
59
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
60
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
61 .. exception:: Full
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:`put` (or :meth:`put_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 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
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
67 .. _queueobjects:
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 Queue Objects
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
70 -------------
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
71
45134
bdcf40d1b38e Merged revisions 60481,60485,60489-60520,60523-60527,60530-60533,60535-60538,60540-60551 via svnmerge from
Christian Heimes <christian@cheimes.de>
parents: 44742
diff changeset
72 Queue objects (:class:`Queue`, :class:`LifoQueue`, or :class:`PriorityQueue`)
50563
93cf3a6ead63 Merged revisions 68226 via svnmerge from
Georg Brandl <georg@python.org>
parents: 47674
diff changeset
73 provide the public methods described below.
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
74
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 .. method:: Queue.qsize()
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
77
44699
6f049ca55e06 Merged revisions 59952-59984 via svnmerge from
Guido van Rossum <guido@python.org>
parents: 44675
diff changeset
78 Return the approximate size of the queue. Note, qsize() > 0 doesn't
6f049ca55e06 Merged revisions 59952-59984 via svnmerge from
Guido van Rossum <guido@python.org>
parents: 44675
diff changeset
79 guarantee that a subsequent get() will not block, nor will qsize() < maxsize
6f049ca55e06 Merged revisions 59952-59984 via svnmerge from
Guido van Rossum <guido@python.org>
parents: 44675
diff changeset
80 guarantee that put() will not block.
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
81
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
82
52063
e9e46ade61c7 Redocument the empty() and full() methods.
Raymond Hettinger <python@rcn.com>
parents: 51190
diff changeset
83 .. method:: Queue.empty()
e9e46ade61c7 Redocument the empty() and full() methods.
Raymond Hettinger <python@rcn.com>
parents: 51190
diff changeset
84
e9e46ade61c7 Redocument the empty() and full() methods.
Raymond Hettinger <python@rcn.com>
parents: 51190
diff changeset
85 Return ``True`` if the queue is empty, ``False`` otherwise. If empty()
e9e46ade61c7 Redocument the empty() and full() methods.
Raymond Hettinger <python@rcn.com>
parents: 51190
diff changeset
86 returns ``True`` it doesn't guarantee that a subsequent call to put()
e9e46ade61c7 Redocument the empty() and full() methods.
Raymond Hettinger <python@rcn.com>
parents: 51190
diff changeset
87 will not block. Similarly, if empty() returns ``False`` it doesn't
e9e46ade61c7 Redocument the empty() and full() methods.
Raymond Hettinger <python@rcn.com>
parents: 51190
diff changeset
88 guarantee that a subsequent call to get() will not block.
e9e46ade61c7 Redocument the empty() and full() methods.
Raymond Hettinger <python@rcn.com>
parents: 51190
diff changeset
89
e9e46ade61c7 Redocument the empty() and full() methods.
Raymond Hettinger <python@rcn.com>
parents: 51190
diff changeset
90
e9e46ade61c7 Redocument the empty() and full() methods.
Raymond Hettinger <python@rcn.com>
parents: 51190
diff changeset
91 .. method:: Queue.full()
e9e46ade61c7 Redocument the empty() and full() methods.
Raymond Hettinger <python@rcn.com>
parents: 51190
diff changeset
92
e9e46ade61c7 Redocument the empty() and full() methods.
Raymond Hettinger <python@rcn.com>
parents: 51190
diff changeset
93 Return ``True`` if the queue is full, ``False`` otherwise. If full()
e9e46ade61c7 Redocument the empty() and full() methods.
Raymond Hettinger <python@rcn.com>
parents: 51190
diff changeset
94 returns ``True`` it doesn't guarantee that a subsequent call to get()
e9e46ade61c7 Redocument the empty() and full() methods.
Raymond Hettinger <python@rcn.com>
parents: 51190
diff changeset
95 will not block. Similarly, if full() returns ``False`` it doesn't
e9e46ade61c7 Redocument the empty() and full() methods.
Raymond Hettinger <python@rcn.com>
parents: 51190
diff changeset
96 guarantee that a subsequent call to put() will not block.
e9e46ade61c7 Redocument the empty() and full() methods.
Raymond Hettinger <python@rcn.com>
parents: 51190
diff changeset
97
e9e46ade61c7 Redocument the empty() and full() methods.
Raymond Hettinger <python@rcn.com>
parents: 51190
diff changeset
98
55802
106ee4eb5970 Switch more function arguments docs to new-style.
Georg Brandl <georg@python.org>
parents: 52108
diff changeset
99 .. method:: Queue.put(item, block=True, timeout=None)
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
100
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
101 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
102 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
103 *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
104 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
105 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
106 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
107 ignored in that case).
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
108
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 .. method:: Queue.put_nowait(item)
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
111
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
112 Equivalent to ``put(item, False)``.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
113
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
114
55802
106ee4eb5970 Switch more function arguments docs to new-style.
Georg Brandl <georg@python.org>
parents: 52108
diff changeset
115 .. method:: Queue.get(block=True, timeout=None)
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
116
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
117 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
118 *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
119 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
120 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
121 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
122 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
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.get_nowait()
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 ``get(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 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
130 fully processed by daemon consumer threads.
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
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
133 .. method:: Queue.task_done()
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
134
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
135 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
136 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
137 :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
138
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
139 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
140 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
141 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
142
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
143 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
144 the queue.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
145
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 .. method:: Queue.join()
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
148
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
149 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
150
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
151 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
152 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
153 indicate that the item was retrieved and all work on it is complete. When the
52108
ae3006c7d5b0 Fix markup.
Raymond Hettinger <python@rcn.com>
parents: 52094
diff changeset
154 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
155
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 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
158
50563
93cf3a6ead63 Merged revisions 68226 via svnmerge from
Georg Brandl <georg@python.org>
parents: 47674
diff changeset
159 def worker():
93cf3a6ead63 Merged revisions 68226 via svnmerge from
Georg Brandl <georg@python.org>
parents: 47674
diff changeset
160 while True:
93cf3a6ead63 Merged revisions 68226 via svnmerge from
Georg Brandl <georg@python.org>
parents: 47674
diff changeset
161 item = q.get()
93cf3a6ead63 Merged revisions 68226 via svnmerge from
Georg Brandl <georg@python.org>
parents: 47674
diff changeset
162 do_work(item)
93cf3a6ead63 Merged revisions 68226 via svnmerge from
Georg Brandl <georg@python.org>
parents: 47674
diff changeset
163 q.task_done()
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
164
50563
93cf3a6ead63 Merged revisions 68226 via svnmerge from
Georg Brandl <georg@python.org>
parents: 47674
diff changeset
165 q = Queue()
93cf3a6ead63 Merged revisions 68226 via svnmerge from
Georg Brandl <georg@python.org>
parents: 47674
diff changeset
166 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
167 t = Thread(target=worker)
51190
e227054d496d fix a case of set_daemon #5087
Benjamin Peterson <benjamin@python.org>
parents: 50563
diff changeset
168 t.daemon = True
50563
93cf3a6ead63 Merged revisions 68226 via svnmerge from
Georg Brandl <georg@python.org>
parents: 47674
diff changeset
169 t.start()
42604
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 for item in source():
50563
93cf3a6ead63 Merged revisions 68226 via svnmerge from
Georg Brandl <georg@python.org>
parents: 47674
diff changeset
172 q.put(item)
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
173
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
174 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
175
67435
5f8eb9e7acdc Mention multiprocessing.Queue in the queue docs
Antoine Pitrou <solipsis@pitrou.net>
parents: 66209
diff changeset
176
5f8eb9e7acdc Mention multiprocessing.Queue in the queue docs
Antoine Pitrou <solipsis@pitrou.net>
parents: 66209
diff changeset
177 .. seealso::
5f8eb9e7acdc Mention multiprocessing.Queue in the queue docs
Antoine Pitrou <solipsis@pitrou.net>
parents: 66209
diff changeset
178
5f8eb9e7acdc Mention multiprocessing.Queue in the queue docs
Antoine Pitrou <solipsis@pitrou.net>
parents: 66209
diff changeset
179 Class :class:`multiprocessing.Queue`
5f8eb9e7acdc Mention multiprocessing.Queue in the queue docs
Antoine Pitrou <solipsis@pitrou.net>
parents: 66209
diff changeset
180 A queue class for use in a multi-processing (rather than multi-threading)
5f8eb9e7acdc Mention multiprocessing.Queue in the queue docs
Antoine Pitrou <solipsis@pitrou.net>
parents: 66209
diff changeset
181 context.
5f8eb9e7acdc Mention multiprocessing.Queue in the queue docs
Antoine Pitrou <solipsis@pitrou.net>
parents: 66209
diff changeset
182
67438
133dee82a009 Fix indent.
Georg Brandl <georg@python.org>
parents: 67437
diff changeset
183 :class:`collections.deque` is an alternative implementation of unbounded
67437
df9a0616004d Combine the two seealso sections.
Raymond Hettinger <python@rcn.com>
parents: 67435
diff changeset
184 queues with fast atomic :func:`append` and :func:`popleft` operations that
df9a0616004d Combine the two seealso sections.
Raymond Hettinger <python@rcn.com>
parents: 67435
diff changeset
185 do not require locking.
df9a0616004d Combine the two seealso sections.
Raymond Hettinger <python@rcn.com>
parents: 67435
diff changeset
186