Mercurial > cpython-lru_cache-weakref

annotate Doc/lib/libqueue.tex @ 8918:acfffe14628e legacy-trunk

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
New section header style. Fix up a few synopses.
author Fred Drake <fdrake@acm.org>
date Mon, 10 Aug 1998 19:42:37 +0000
parents 760dcf197048
children b7d8125c2417
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} ---
acfffe14628e New section header style.
Fred Drake <fdrake@acm.org>
parents: 8716
diff changeset
2 A synchronized queue class.}
8716
760dcf197048 Adjusted to use the new module synopsis support macros.
Fred Drake <fdrake@acm.org>
parents: 7877
diff changeset
3 \declaremodule{standard}{Queue}
760dcf197048 Adjusted to use the new module synopsis support macros.
Fred Drake <fdrake@acm.org>
parents: 7877
diff changeset
4
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
e6b9d21c8e0c libqueue.tex: Documentation for the Queue.py module.
Barry Warsaw <barry@python.org>
parents:
diff changeset
8
7634
3d1590b5e3dd Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
9 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
10 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
11 information must be exchanged safely between multiple threads. The
7634
3d1590b5e3dd Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
12 \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
13 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
14 Python.
e6b9d21c8e0c libqueue.tex: Documentation for the Queue.py module.
Barry Warsaw <barry@python.org>
parents:
diff changeset
15
7634
3d1590b5e3dd Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
16 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
17
e6b9d21c8e0c libqueue.tex: Documentation for the Queue.py module.
Barry Warsaw <barry@python.org>
parents:
diff changeset
18
7634
3d1590b5e3dd Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
19 \begin{classdesc}{Queue}{maxsize}
6611
e6b9d21c8e0c libqueue.tex: Documentation for the Queue.py module.
Barry Warsaw <barry@python.org>
parents:
diff changeset
20 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
21 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
22 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
23 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
24 zero, the queue size is infinite.
7634
3d1590b5e3dd Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
25 \end{classdesc}
3d1590b5e3dd Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
26
3d1590b5e3dd Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
27 \begin{excdesc}{Empty}
3d1590b5e3dd Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
28 Exception raised when non-blocking get (e.g. \method{get_nowait()}) is
3d1590b5e3dd Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
29 called on a \class{Queue} object which is empty, or for which the
3d1590b5e3dd Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
30 emptyiness cannot be determined (i.e. because the appropriate locks
3d1590b5e3dd Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
31 cannot be acquired).
3d1590b5e3dd Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
32 \end{excdesc}
6611
e6b9d21c8e0c libqueue.tex: Documentation for the Queue.py module.
Barry Warsaw <barry@python.org>
parents:
diff changeset
33
7634
3d1590b5e3dd Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
34 \subsection{Queue Objects}
3d1590b5e3dd Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
35 \label{QueueObjects}
3d1590b5e3dd Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
36
3d1590b5e3dd Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
37 Class \class{Queue} implements queue objects and has the methods
3d1590b5e3dd Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
38 described below. This class can be derived from in order to implement
3d1590b5e3dd Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
39 other queue organizations (e.g. stack) but the inheritable interface
3d1590b5e3dd Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
40 is not described here. See the source code for details. The public
3d1590b5e3dd Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
41 methods are:
3d1590b5e3dd Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
42
7768
8f177933c41f Use the new {methoddesc} and {memberdesc} environments as appropriate.
Fred Drake <fdrake@acm.org>
parents: 7634
diff changeset
43 \begin{methoddesc}{qsize}{}
6611
e6b9d21c8e0c libqueue.tex: Documentation for the Queue.py module.
Barry Warsaw <barry@python.org>
parents:
diff changeset
44 Returns the approximate size of the queue. Because of multithreading
e6b9d21c8e0c libqueue.tex: Documentation for the Queue.py module.
Barry Warsaw <barry@python.org>
parents:
diff changeset
45 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
46 \end{methoddesc}
6611
e6b9d21c8e0c libqueue.tex: Documentation for the Queue.py module.
Barry Warsaw <barry@python.org>
parents:
diff changeset
47
7768
8f177933c41f Use the new {methoddesc} and {memberdesc} environments as appropriate.
Fred Drake <fdrake@acm.org>
parents: 7634
diff changeset
48 \begin{methoddesc}{empty}{}
7634
3d1590b5e3dd Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
49 Returns \code{1} if the queue is empty, \code{0} otherwise. Because
3d1590b5e3dd Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
50 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
51 \end{methoddesc}
6611
e6b9d21c8e0c libqueue.tex: Documentation for the Queue.py module.
Barry Warsaw <barry@python.org>
parents:
diff changeset
52
7768
8f177933c41f Use the new {methoddesc} and {memberdesc} environments as appropriate.
Fred Drake <fdrake@acm.org>
parents: 7634
diff changeset
53 \begin{methoddesc}{full}{}
7634
3d1590b5e3dd Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
54 Returns \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
55 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
56 \end{methoddesc}
6611
e6b9d21c8e0c libqueue.tex: Documentation for the Queue.py module.
Barry Warsaw <barry@python.org>
parents:
diff changeset
57
7768
8f177933c41f Use the new {methoddesc} and {memberdesc} environments as appropriate.
Fred Drake <fdrake@acm.org>
parents: 7634
diff changeset
58 \begin{methoddesc}{put}{item}
6611
e6b9d21c8e0c libqueue.tex: Documentation for the Queue.py module.
Barry Warsaw <barry@python.org>
parents:
diff changeset
59 Puts \var{item} into the queue.
7768
8f177933c41f Use the new {methoddesc} and {memberdesc} environments as appropriate.
Fred Drake <fdrake@acm.org>
parents: 7634
diff changeset
60 \end{methoddesc}
6611
e6b9d21c8e0c libqueue.tex: Documentation for the Queue.py module.
Barry Warsaw <barry@python.org>
parents:
diff changeset
61
7768
8f177933c41f Use the new {methoddesc} and {memberdesc} environments as appropriate.
Fred Drake <fdrake@acm.org>
parents: 7634
diff changeset
62 \begin{methoddesc}{get}{}
6611
e6b9d21c8e0c libqueue.tex: Documentation for the Queue.py module.
Barry Warsaw <barry@python.org>
parents:
diff changeset
63 Gets and returns an item from the queue, blocking if necessary until
e6b9d21c8e0c libqueue.tex: Documentation for the Queue.py module.
Barry Warsaw <barry@python.org>
parents:
diff changeset
64 one is available.
7768
8f177933c41f Use the new {methoddesc} and {memberdesc} environments as appropriate.
Fred Drake <fdrake@acm.org>
parents: 7634
diff changeset
65 \end{methoddesc}
6611
e6b9d21c8e0c libqueue.tex: Documentation for the Queue.py module.
Barry Warsaw <barry@python.org>
parents:
diff changeset
66
7768
8f177933c41f Use the new {methoddesc} and {memberdesc} environments as appropriate.
Fred Drake <fdrake@acm.org>
parents: 7634
diff changeset
67 \begin{methoddesc}{get_nowait}{}
6611
e6b9d21c8e0c libqueue.tex: Documentation for the Queue.py module.
Barry Warsaw <barry@python.org>
parents:
diff changeset
68 Gets and returns an item from the queue if one is immediately
7634
3d1590b5e3dd Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
69 available. Raises an \exception{Empty} exception if the queue is
3d1590b5e3dd Logical markup.
Fred Drake <fdrake@acm.org>
parents: 7277
diff changeset
70 empty or if the queue's emptiness cannot be determined.
7768
8f177933c41f Use the new {methoddesc} and {memberdesc} environments as appropriate.
Fred Drake <fdrake@acm.org>
parents: 7634
diff changeset
71 \end{methoddesc}