Mercurial > cpython-lru_cache-weakref

annotate Doc/lib/libqueue.tex @ 24042:63fbbed10714 legacy-trunk

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Simplify HTTPSConnection constructor. See discussion in SF bug 458463.
author Jeremy Hylton <jeremy@alum.mit.edu>
date Fri, 28 Jun 2002 23:38:14 +0000
parents 1f6510051c8a
children 3eafbde56b21
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}{}
10121
b7d8125c2417 Update documentation to reflect changes to Queue.py by Tim Peters.
Guido van Rossum <guido@python.org>
parents: 8918
diff changeset
57 Return \code{1} if the queue is empty, \code{0} otherwise. Because
7634
3d1590b5e3dd Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
58 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
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}{}
10121
b7d8125c2417 Update documentation to reflect changes to Queue.py by Tim Peters.
Guido van Rossum <guido@python.org>
parents: 8918
diff changeset
62 Return \code{1} if the queue is full, \code{0} otherwise. Because of
6611
e6b9d21c8e0c libqueue.tex: Documentation for the Queue.py module.
Barry Warsaw <barry@python.org>
parents:
diff changeset
63 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
10121
b7d8125c2417 Update documentation to reflect changes to Queue.py by Tim Peters.
Guido van Rossum <guido@python.org>
parents: 8918
diff changeset
66 \begin{methoddesc}{put}{item\optional{, block}}
b7d8125c2417 Update documentation to reflect changes to Queue.py by Tim Peters.
Guido van Rossum <guido@python.org>
parents: 8918
diff changeset
67 Put \var{item} into the queue. If optional argument \var{block} is 1
b7d8125c2417 Update documentation to reflect changes to Queue.py by Tim Peters.
Guido van Rossum <guido@python.org>
parents: 8918
diff changeset
68 (the default), block if necessary until a free slot is available.
b7d8125c2417 Update documentation to reflect changes to Queue.py by Tim Peters.
Guido van Rossum <guido@python.org>
parents: 8918
diff changeset
69 Otherwise (\var{block} is 0), put \var{item} on the queue if a free
b7d8125c2417 Update documentation to reflect changes to Queue.py by Tim Peters.
Guido van Rossum <guido@python.org>
parents: 8918
diff changeset
70 slot is immediately available, else raise the \exception{Full}
b7d8125c2417 Update documentation to reflect changes to Queue.py by Tim Peters.
Guido van Rossum <guido@python.org>
parents: 8918
diff changeset
71 exception.
7768
8f177933c41f Use the new {methoddesc} and {memberdesc} environments as appropriate.
Fred Drake <fdrake@acm.org>
parents: 7634
diff changeset
72 \end{methoddesc}
6611
e6b9d21c8e0c libqueue.tex: Documentation for the Queue.py module.
Barry Warsaw <barry@python.org>
parents:
diff changeset
73
10121
b7d8125c2417 Update documentation to reflect changes to Queue.py by Tim Peters.
Guido van Rossum <guido@python.org>
parents: 8918
diff changeset
74 \begin{methoddesc}{put_nowait}{item}
b7d8125c2417 Update documentation to reflect changes to Queue.py by Tim Peters.
Guido van Rossum <guido@python.org>
parents: 8918
diff changeset
75 Equivalent to \code{put(\var{item}, 0)}.
b7d8125c2417 Update documentation to reflect changes to Queue.py by Tim Peters.
Guido van Rossum <guido@python.org>
parents: 8918
diff changeset
76 \end{methoddesc}
b7d8125c2417 Update documentation to reflect changes to Queue.py by Tim Peters.
Guido van Rossum <guido@python.org>
parents: 8918
diff changeset
77
b7d8125c2417 Update documentation to reflect changes to Queue.py by Tim Peters.
Guido van Rossum <guido@python.org>
parents: 8918
diff changeset
78 \begin{methoddesc}{get}{\optional{block}}
b7d8125c2417 Update documentation to reflect changes to Queue.py by Tim Peters.
Guido van Rossum <guido@python.org>
parents: 8918
diff changeset
79 Remove and return an item from the queue. If optional argument
b7d8125c2417 Update documentation to reflect changes to Queue.py by Tim Peters.
Guido van Rossum <guido@python.org>
parents: 8918
diff changeset
80 \var{block} is 1 (the default), block if necessary until an item is
b7d8125c2417 Update documentation to reflect changes to Queue.py by Tim Peters.
Guido van Rossum <guido@python.org>
parents: 8918
diff changeset
81 available. Otherwise (\var{block} is 0), return an item if one is
b7d8125c2417 Update documentation to reflect changes to Queue.py by Tim Peters.
Guido van Rossum <guido@python.org>
parents: 8918
diff changeset
82 immediately available, else raise the
b7d8125c2417 Update documentation to reflect changes to Queue.py by Tim Peters.
Guido van Rossum <guido@python.org>
parents: 8918
diff changeset
83 \exception{Empty} exception.
7768
8f177933c41f Use the new {methoddesc} and {memberdesc} environments as appropriate.
Fred Drake <fdrake@acm.org>
parents: 7634
diff changeset
84 \end{methoddesc}
6611
e6b9d21c8e0c libqueue.tex: Documentation for the Queue.py module.
Barry Warsaw <barry@python.org>
parents:
diff changeset
85
7768
8f177933c41f Use the new {methoddesc} and {memberdesc} environments as appropriate.
Fred Drake <fdrake@acm.org>
parents: 7634
diff changeset
86 \begin{methoddesc}{get_nowait}{}
10121
b7d8125c2417 Update documentation to reflect changes to Queue.py by Tim Peters.
Guido van Rossum <guido@python.org>
parents: 8918
diff changeset
87 Equivalent to \code{get(0)}.
7768
8f177933c41f Use the new {methoddesc} and {memberdesc} environments as appropriate.
Fred Drake <fdrake@acm.org>
parents: 7634
diff changeset
88 \end{methoddesc}