Mercurial > cpython-lru_cache-weakref

annotate Doc/lib/libqueue.tex @ 28646:193b8aec00ce legacy-trunk

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Changes from Jonathan Riehl to allow his pgen extension (PEP 269) to work. This includes some more code that used to be part of pgen in the main parser; I'm okay with that. I'll see if the Windows build needs work next.
author Guido van Rossum <guido@python.org>
date Thu, 17 Apr 2003 14:55:42 +0000
parents 3eafbde56b21
children 63fa60f2d61c
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
8918
acfffe14628e New section header style.
Fred Drake <fdrake@acm.org>
parents: 8716
diff changeset
1 \section{\module{Queue} ---
15142
563dee598d3a Fixed lots of small nits caught by Ka-Ping Yee <ping@lfw.org>.
Fred Drake <fdrake@acm.org>
parents: 12223
diff changeset
2 A synchronized queue class}
563dee598d3a Fixed lots of small nits caught by Ka-Ping Yee <ping@lfw.org>.
Fred Drake <fdrake@acm.org>
parents: 12223
diff changeset
3
8716
760dcf197048 Adjusted to use the new module synopsis support macros.
Fred Drake <fdrake@acm.org>
parents: 7877
diff changeset
4 \declaremodule{standard}{Queue}
8918
acfffe14628e New section header style.
Fred Drake <fdrake@acm.org>
parents: 8716
diff changeset
5 \modulesynopsis{A synchronized queue class.}
8716
760dcf197048 Adjusted to use the new module synopsis support macros.
Fred Drake <fdrake@acm.org>
parents: 7877
diff changeset
6
6611
e6b9d21c8e0c libqueue.tex: Documentation for the Queue.py module.
Barry Warsaw <barry@python.org>
parents:
diff changeset
7
7634
3d1590b5e3dd Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
8 The \module{Queue} module implements a multi-producer, multi-consumer
6611
e6b9d21c8e0c libqueue.tex: Documentation for the Queue.py module.
Barry Warsaw <barry@python.org>
parents:
diff changeset
9 FIFO queue. It is especially useful in threads programming when
e6b9d21c8e0c libqueue.tex: Documentation for the Queue.py module.
Barry Warsaw <barry@python.org>
parents:
diff changeset
10 information must be exchanged safely between multiple threads. The
7634
3d1590b5e3dd Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
11 \class{Queue} class in this module implements all the required locking
6611
e6b9d21c8e0c libqueue.tex: Documentation for the Queue.py module.
Barry Warsaw <barry@python.org>
parents:
diff changeset
12 semantics. It depends on the availability of thread support in
e6b9d21c8e0c libqueue.tex: Documentation for the Queue.py module.
Barry Warsaw <barry@python.org>
parents:
diff changeset
13 Python.
e6b9d21c8e0c libqueue.tex: Documentation for the Queue.py module.
Barry Warsaw <barry@python.org>
parents:
diff changeset
14
23997
1f6510051c8a add seealso link to the bisect module
Skip Montanaro <skip@pobox.com>
parents: 15142
diff changeset
15 \begin{seealso}
1f6510051c8a add seealso link to the bisect module
Skip Montanaro <skip@pobox.com>
parents: 15142
diff changeset
16 \seemodule{bisect}{PriorityQueue example using the Queue class}
1f6510051c8a add seealso link to the bisect module
Skip Montanaro <skip@pobox.com>
parents: 15142
diff changeset
17 \end{seealso}
1f6510051c8a add seealso link to the bisect module
Skip Montanaro <skip@pobox.com>
parents: 15142
diff changeset
18
7634
3d1590b5e3dd Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
19 The \module{Queue} module defines the following class and exception:
6611
e6b9d21c8e0c libqueue.tex: Documentation for the Queue.py module.
Barry Warsaw <barry@python.org>
parents:
diff changeset
20
e6b9d21c8e0c libqueue.tex: Documentation for the Queue.py module.
Barry Warsaw <barry@python.org>
parents:
diff changeset
21
7634
3d1590b5e3dd Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
22 \begin{classdesc}{Queue}{maxsize}
6611
e6b9d21c8e0c libqueue.tex: Documentation for the Queue.py module.
Barry Warsaw <barry@python.org>
parents:
diff changeset
23 Constructor for the class. \var{maxsize} is an integer that sets the
e6b9d21c8e0c libqueue.tex: Documentation for the Queue.py module.
Barry Warsaw <barry@python.org>
parents:
diff changeset
24 upperbound limit on the number of items that can be placed in the
e6b9d21c8e0c libqueue.tex: Documentation for the Queue.py module.
Barry Warsaw <barry@python.org>
parents:
diff changeset
25 queue. Insertion will block once this size has been reached, until
e6b9d21c8e0c libqueue.tex: Documentation for the Queue.py module.
Barry Warsaw <barry@python.org>
parents:
diff changeset
26 queue items are consumed. If \var{maxsize} is less than or equal to
e6b9d21c8e0c libqueue.tex: Documentation for the Queue.py module.
Barry Warsaw <barry@python.org>
parents:
diff changeset
27 zero, the queue size is infinite.
7634
3d1590b5e3dd Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
28 \end{classdesc}
3d1590b5e3dd Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
29
3d1590b5e3dd Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
30 \begin{excdesc}{Empty}
10121
b7d8125c2417 Update documentation to reflect changes to Queue.py by Tim Peters.
Guido van Rossum <guido@python.org>
parents: 8918
diff changeset
31 Exception raised when non-blocking \method{get()} (or
b7d8125c2417 Update documentation to reflect changes to Queue.py by Tim Peters.
Guido van Rossum <guido@python.org>
parents: 8918
diff changeset
32 \method{get_nowait()}) is called on a \class{Queue} object which is
b7d8125c2417 Update documentation to reflect changes to Queue.py by Tim Peters.
Guido van Rossum <guido@python.org>
parents: 8918
diff changeset
33 empty or locked.
b7d8125c2417 Update documentation to reflect changes to Queue.py by Tim Peters.
Guido van Rossum <guido@python.org>
parents: 8918
diff changeset
34 \end{excdesc}
b7d8125c2417 Update documentation to reflect changes to Queue.py by Tim Peters.
Guido van Rossum <guido@python.org>
parents: 8918
diff changeset
35
b7d8125c2417 Update documentation to reflect changes to Queue.py by Tim Peters.
Guido van Rossum <guido@python.org>
parents: 8918
diff changeset
36 \begin{excdesc}{Full}
b7d8125c2417 Update documentation to reflect changes to Queue.py by Tim Peters.
Guido van Rossum <guido@python.org>
parents: 8918
diff changeset
37 Exception raised when non-blocking \method{put()} (or
12223
e82e82b3b9ad Merged changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 10121
diff changeset
38 \method{put_nowait()}) is called on a \class{Queue} object which is
10121
b7d8125c2417 Update documentation to reflect changes to Queue.py by Tim Peters.
Guido van Rossum <guido@python.org>
parents: 8918
diff changeset
39 full or locked.
7634
3d1590b5e3dd Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
40 \end{excdesc}
6611
e6b9d21c8e0c libqueue.tex: Documentation for the Queue.py module.
Barry Warsaw <barry@python.org>
parents:
diff changeset
41
7634
3d1590b5e3dd Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
42 \subsection{Queue Objects}
3d1590b5e3dd Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
43 \label{QueueObjects}
3d1590b5e3dd Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
44
3d1590b5e3dd Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
45 Class \class{Queue} implements queue objects and has the methods
3d1590b5e3dd Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
46 described below. This class can be derived from in order to implement
3d1590b5e3dd Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
47 other queue organizations (e.g. stack) but the inheritable interface
3d1590b5e3dd Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
48 is not described here. See the source code for details. The public
3d1590b5e3dd Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
49 methods are:
3d1590b5e3dd Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
50
7768
8f177933c41f Use the new {methoddesc} and {memberdesc} environments as appropriate.
Fred Drake <fdrake@acm.org>
parents: 7634
diff changeset
51 \begin{methoddesc}{qsize}{}
10121
b7d8125c2417 Update documentation to reflect changes to Queue.py by Tim Peters.
Guido van Rossum <guido@python.org>
parents: 8918
diff changeset
52 Return the approximate size of the queue. Because of multithreading
6611
e6b9d21c8e0c libqueue.tex: Documentation for the Queue.py module.
Barry Warsaw <barry@python.org>
parents:
diff changeset
53 semantics, this number is not reliable.
7768
8f177933c41f Use the new {methoddesc} and {memberdesc} environments as appropriate.
Fred Drake <fdrake@acm.org>
parents: 7634
diff changeset
54 \end{methoddesc}
6611
e6b9d21c8e0c libqueue.tex: Documentation for the Queue.py module.
Barry Warsaw <barry@python.org>
parents:
diff changeset
55
7768
8f177933c41f Use the new {methoddesc} and {memberdesc} environments as appropriate.
Fred Drake <fdrake@acm.org>
parents: 7634
diff changeset
56 \begin{methoddesc}{empty}{}
25796
3eafbde56b21 Patch #572628: Optional timeouts for put and get.
Martin v. Löwis <martin@v.loewis.de>
parents: 23997
diff changeset
57 Return \code{True} if the queue is empty, \code{False} otherwise.
3eafbde56b21 Patch #572628: Optional timeouts for put and get.
Martin v. Löwis <martin@v.loewis.de>
parents: 23997
diff changeset
58 Becauseof multithreading semantics, this is not reliable.
7768
8f177933c41f Use the new {methoddesc} and {memberdesc} environments as appropriate.
Fred Drake <fdrake@acm.org>
parents: 7634
diff changeset
59 \end{methoddesc}
6611
e6b9d21c8e0c libqueue.tex: Documentation for the Queue.py module.
Barry Warsaw <barry@python.org>
parents:
diff changeset
60
7768
8f177933c41f Use the new {methoddesc} and {memberdesc} environments as appropriate.
Fred Drake <fdrake@acm.org>
parents: 7634
diff changeset
61 \begin{methoddesc}{full}{}
25796
3eafbde56b21 Patch #572628: Optional timeouts for put and get.
Martin v. Löwis <martin@v.loewis.de>
parents: 23997
diff changeset
62 Return \code{True} if the queue is full, \code{False} otherwise.
3eafbde56b21 Patch #572628: Optional timeouts for put and get.
Martin v. Löwis <martin@v.loewis.de>
parents: 23997
diff changeset
63 Because of multithreading semantics, this is not reliable.
7768
8f177933c41f Use the new {methoddesc} and {memberdesc} environments as appropriate.
Fred Drake <fdrake@acm.org>
parents: 7634
diff changeset
64 \end{methoddesc}
6611
e6b9d21c8e0c libqueue.tex: Documentation for the Queue.py module.
Barry Warsaw <barry@python.org>
parents:
diff changeset
65
25796
3eafbde56b21 Patch #572628: Optional timeouts for put and get.
Martin v. Löwis <martin@v.loewis.de>
parents: 23997
diff changeset
66 \begin{methoddesc}{put}{item\optional{, block\optional{, timeout}}}
3eafbde56b21 Patch #572628: Optional timeouts for put and get.
Martin v. Löwis <martin@v.loewis.de>
parents: 23997
diff changeset
67 Put \var{item} into the queue. If optional args \var{block} is true
3eafbde56b21 Patch #572628: Optional timeouts for put and get.
Martin v. Löwis <martin@v.loewis.de>
parents: 23997
diff changeset
68 and \var{timeout} is None (the default), block if necessary until a
3eafbde56b21 Patch #572628: Optional timeouts for put and get.
Martin v. Löwis <martin@v.loewis.de>
parents: 23997
diff changeset
69 free slot is available. If \var{timeout} is a positive number, it
3eafbde56b21 Patch #572628: Optional timeouts for put and get.
Martin v. Löwis <martin@v.loewis.de>
parents: 23997
diff changeset
70 blocks at most \var{timeout} seconds and raises the \exception{Full}
3eafbde56b21 Patch #572628: Optional timeouts for put and get.
Martin v. Löwis <martin@v.loewis.de>
parents: 23997
diff changeset
71 exception if no free slot was available within that time.
3eafbde56b21 Patch #572628: Optional timeouts for put and get.
Martin v. Löwis <martin@v.loewis.de>
parents: 23997
diff changeset
72 Otherwise (\var{block} is false), put an item on the queue if a free
10121
b7d8125c2417 Update documentation to reflect changes to Queue.py by Tim Peters.
Guido van Rossum <guido@python.org>
parents: 8918
diff changeset
73 slot is immediately available, else raise the \exception{Full}
25796
3eafbde56b21 Patch #572628: Optional timeouts for put and get.
Martin v. Löwis <martin@v.loewis.de>
parents: 23997
diff changeset
74 exception (\var{timeout} is ignored in that case).
3eafbde56b21 Patch #572628: Optional timeouts for put and get.
Martin v. Löwis <martin@v.loewis.de>
parents: 23997
diff changeset
75
3eafbde56b21 Patch #572628: Optional timeouts for put and get.
Martin v. Löwis <martin@v.loewis.de>
parents: 23997
diff changeset
76 \versionadded[the timeout parameter]{2.3}
3eafbde56b21 Patch #572628: Optional timeouts for put and get.
Martin v. Löwis <martin@v.loewis.de>
parents: 23997
diff changeset
77
7768
8f177933c41f Use the new {methoddesc} and {memberdesc} environments as appropriate.
Fred Drake <fdrake@acm.org>
parents: 7634
diff changeset
78 \end{methoddesc}
6611
e6b9d21c8e0c libqueue.tex: Documentation for the Queue.py module.
Barry Warsaw <barry@python.org>
parents:
diff changeset
79
10121
b7d8125c2417 Update documentation to reflect changes to Queue.py by Tim Peters.
Guido van Rossum <guido@python.org>
parents: 8918
diff changeset
80 \begin{methoddesc}{put_nowait}{item}
25796
3eafbde56b21 Patch #572628: Optional timeouts for put and get.
Martin v. Löwis <martin@v.loewis.de>
parents: 23997
diff changeset
81 Equivalent to \code{put(\var{item}, False)}.
10121
b7d8125c2417 Update documentation to reflect changes to Queue.py by Tim Peters.
Guido van Rossum <guido@python.org>
parents: 8918
diff changeset
82 \end{methoddesc}
b7d8125c2417 Update documentation to reflect changes to Queue.py by Tim Peters.
Guido van Rossum <guido@python.org>
parents: 8918
diff changeset
83
25796
3eafbde56b21 Patch #572628: Optional timeouts for put and get.
Martin v. Löwis <martin@v.loewis.de>
parents: 23997
diff changeset
84 \begin{methoddesc}{get}{\optional{block\optional{, timeout}}}
3eafbde56b21 Patch #572628: Optional timeouts for put and get.
Martin v. Löwis <martin@v.loewis.de>
parents: 23997
diff changeset
85 Remove and return an item from the queue. If optional args
3eafbde56b21 Patch #572628: Optional timeouts for put and get.
Martin v. Löwis <martin@v.loewis.de>
parents: 23997
diff changeset
86 \var{block} is true and \var{timeout} is None (the default),
3eafbde56b21 Patch #572628: Optional timeouts for put and get.
Martin v. Löwis <martin@v.loewis.de>
parents: 23997
diff changeset
87 block if necessary until an item is available. If \var{timeout} is
3eafbde56b21 Patch #572628: Optional timeouts for put and get.
Martin v. Löwis <martin@v.loewis.de>
parents: 23997
diff changeset
88 a positive number, it blocks at most \var{timeout} seconds and raises
3eafbde56b21 Patch #572628: Optional timeouts for put and get.
Martin v. Löwis <martin@v.loewis.de>
parents: 23997
diff changeset
89 the \exception{Empty} exception if no item was available within that
3eafbde56b21 Patch #572628: Optional timeouts for put and get.
Martin v. Löwis <martin@v.loewis.de>
parents: 23997
diff changeset
90 time. Otherwise (\var{block} is false), return an item if one is
3eafbde56b21 Patch #572628: Optional timeouts for put and get.
Martin v. Löwis <martin@v.loewis.de>
parents: 23997
diff changeset
91 immediately available, else raise the \exception{Empty} exception
3eafbde56b21 Patch #572628: Optional timeouts for put and get.
Martin v. Löwis <martin@v.loewis.de>
parents: 23997
diff changeset
92 (\var{timeout} is ignored in that case).
3eafbde56b21 Patch #572628: Optional timeouts for put and get.
Martin v. Löwis <martin@v.loewis.de>
parents: 23997
diff changeset
93
3eafbde56b21 Patch #572628: Optional timeouts for put and get.
Martin v. Löwis <martin@v.loewis.de>
parents: 23997
diff changeset
94 \versionadded[the timeout parameter]{2.3}
3eafbde56b21 Patch #572628: Optional timeouts for put and get.
Martin v. Löwis <martin@v.loewis.de>
parents: 23997
diff changeset
95
7768
8f177933c41f Use the new {methoddesc} and {memberdesc} environments as appropriate.
Fred Drake <fdrake@acm.org>
parents: 7634
diff changeset
96 \end{methoddesc}
6611
e6b9d21c8e0c libqueue.tex: Documentation for the Queue.py module.
Barry Warsaw <barry@python.org>
parents:
diff changeset
97
7768
8f177933c41f Use the new {methoddesc} and {memberdesc} environments as appropriate.
Fred Drake <fdrake@acm.org>
parents: 7634
diff changeset
98 \begin{methoddesc}{get_nowait}{}
25796
3eafbde56b21 Patch #572628: Optional timeouts for put and get.
Martin v. Löwis <martin@v.loewis.de>
parents: 23997
diff changeset
99 Equivalent to \code{get(False)}.
7768
8f177933c41f Use the new {methoddesc} and {memberdesc} environments as appropriate.
Fred Drake <fdrake@acm.org>
parents: 7634
diff changeset
100 \end{methoddesc}