Mercurial > cpython-lru_cache-weakref

annotate Doc/lib/libqueue.tex @ 6719:faebc1940432 legacy-trunk

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Understand -Xlinker option.
author Guido van Rossum <guido@python.org>
date Tue, 02 Dec 1997 20:38:11 +0000
parents e6b9d21c8e0c
children 2522c8f8615b
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
6611
e6b9d21c8e0c libqueue.tex: Documentation for the Queue.py module.
Barry Warsaw <barry@python.org>
parents:
diff changeset
1 \section{Standard module \sectcode{Queue}}
e6b9d21c8e0c libqueue.tex: Documentation for the Queue.py module.
Barry Warsaw <barry@python.org>
parents:
diff changeset
2 \stmodindex{Queue}
e6b9d21c8e0c libqueue.tex: Documentation for the Queue.py module.
Barry Warsaw <barry@python.org>
parents:
diff changeset
3
e6b9d21c8e0c libqueue.tex: Documentation for the Queue.py module.
Barry Warsaw <barry@python.org>
parents:
diff changeset
4 \label{module-Queue}
e6b9d21c8e0c libqueue.tex: Documentation for the Queue.py module.
Barry Warsaw <barry@python.org>
parents:
diff changeset
5
e6b9d21c8e0c libqueue.tex: Documentation for the Queue.py module.
Barry Warsaw <barry@python.org>
parents:
diff changeset
6 % ==== 2. ====
e6b9d21c8e0c libqueue.tex: Documentation for the Queue.py module.
Barry Warsaw <barry@python.org>
parents:
diff changeset
7 % Give a short overview of what the module does.
e6b9d21c8e0c libqueue.tex: Documentation for the Queue.py module.
Barry Warsaw <barry@python.org>
parents:
diff changeset
8 % If it is platform specific, mention this.
e6b9d21c8e0c libqueue.tex: Documentation for the Queue.py module.
Barry Warsaw <barry@python.org>
parents:
diff changeset
9 % Mention other important restrictions or general operating principles.
e6b9d21c8e0c libqueue.tex: Documentation for the Queue.py module.
Barry Warsaw <barry@python.org>
parents:
diff changeset
10 % For example:
e6b9d21c8e0c libqueue.tex: Documentation for the Queue.py module.
Barry Warsaw <barry@python.org>
parents:
diff changeset
11
e6b9d21c8e0c libqueue.tex: Documentation for the Queue.py module.
Barry Warsaw <barry@python.org>
parents:
diff changeset
12 The \code{Queue} module implements a multi-producer, multi-consumer
e6b9d21c8e0c libqueue.tex: Documentation for the Queue.py module.
Barry Warsaw <barry@python.org>
parents:
diff changeset
13 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
14 information must be exchanged safely between multiple threads. The
e6b9d21c8e0c libqueue.tex: Documentation for the Queue.py module.
Barry Warsaw <barry@python.org>
parents:
diff changeset
15 \code{Queue} class in this module implements all the required locking
e6b9d21c8e0c libqueue.tex: Documentation for the Queue.py module.
Barry Warsaw <barry@python.org>
parents:
diff changeset
16 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
17 Python.
e6b9d21c8e0c libqueue.tex: Documentation for the Queue.py module.
Barry Warsaw <barry@python.org>
parents:
diff changeset
18
e6b9d21c8e0c libqueue.tex: Documentation for the Queue.py module.
Barry Warsaw <barry@python.org>
parents:
diff changeset
19 The \code{Queue} module defines the following exception:
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 \renewcommand{\indexsubitem}{(in module Queue)}
e6b9d21c8e0c libqueue.tex: Documentation for the Queue.py module.
Barry Warsaw <barry@python.org>
parents:
diff changeset
22
e6b9d21c8e0c libqueue.tex: Documentation for the Queue.py module.
Barry Warsaw <barry@python.org>
parents:
diff changeset
23 \begin{excdesc}{Empty}
e6b9d21c8e0c libqueue.tex: Documentation for the Queue.py module.
Barry Warsaw <barry@python.org>
parents:
diff changeset
24 Exception raised when non-blocking get (e.g. \code{get_nowait()}) is
e6b9d21c8e0c libqueue.tex: Documentation for the Queue.py module.
Barry Warsaw <barry@python.org>
parents:
diff changeset
25 called on a Queue object which is empty, or for which the emptyiness
e6b9d21c8e0c libqueue.tex: Documentation for the Queue.py module.
Barry Warsaw <barry@python.org>
parents:
diff changeset
26 cannot be determined (i.e. because the appropriate locks cannot be
e6b9d21c8e0c libqueue.tex: Documentation for the Queue.py module.
Barry Warsaw <barry@python.org>
parents:
diff changeset
27 acquired).
e6b9d21c8e0c libqueue.tex: Documentation for the Queue.py module.
Barry Warsaw <barry@python.org>
parents:
diff changeset
28 \end{excdesc}
e6b9d21c8e0c libqueue.tex: Documentation for the Queue.py module.
Barry Warsaw <barry@python.org>
parents:
diff changeset
29
e6b9d21c8e0c libqueue.tex: Documentation for the Queue.py module.
Barry Warsaw <barry@python.org>
parents:
diff changeset
30 \subsection{Queue Objects}
e6b9d21c8e0c libqueue.tex: Documentation for the Queue.py module.
Barry Warsaw <barry@python.org>
parents:
diff changeset
31
e6b9d21c8e0c libqueue.tex: Documentation for the Queue.py module.
Barry Warsaw <barry@python.org>
parents:
diff changeset
32 Class \code{Queue} implements queue objects and has the methods
e6b9d21c8e0c libqueue.tex: Documentation for the Queue.py module.
Barry Warsaw <barry@python.org>
parents:
diff changeset
33 described below. This class can be derived from in order to implement
e6b9d21c8e0c libqueue.tex: Documentation for the Queue.py module.
Barry Warsaw <barry@python.org>
parents:
diff changeset
34 other queue organizations (e.g. stack) but the inheritable interface
e6b9d21c8e0c libqueue.tex: Documentation for the Queue.py module.
Barry Warsaw <barry@python.org>
parents:
diff changeset
35 is not described here. See the source code for details. The public
e6b9d21c8e0c libqueue.tex: Documentation for the Queue.py module.
Barry Warsaw <barry@python.org>
parents:
diff changeset
36 interface methods are:
e6b9d21c8e0c libqueue.tex: Documentation for the Queue.py module.
Barry Warsaw <barry@python.org>
parents:
diff changeset
37
e6b9d21c8e0c libqueue.tex: Documentation for the Queue.py module.
Barry Warsaw <barry@python.org>
parents:
diff changeset
38 \renewcommand{\indexsubitem}{(__init__ method)}
e6b9d21c8e0c libqueue.tex: Documentation for the Queue.py module.
Barry Warsaw <barry@python.org>
parents:
diff changeset
39
e6b9d21c8e0c libqueue.tex: Documentation for the Queue.py module.
Barry Warsaw <barry@python.org>
parents:
diff changeset
40 \begin{funcdesc}{__init__}{maxsize}
e6b9d21c8e0c libqueue.tex: Documentation for the Queue.py module.
Barry Warsaw <barry@python.org>
parents:
diff changeset
41 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
42 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
43 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
44 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
45 zero, the queue size is infinite.
e6b9d21c8e0c libqueue.tex: Documentation for the Queue.py module.
Barry Warsaw <barry@python.org>
parents:
diff changeset
46 \end{funcdesc}
e6b9d21c8e0c libqueue.tex: Documentation for the Queue.py module.
Barry Warsaw <barry@python.org>
parents:
diff changeset
47
e6b9d21c8e0c libqueue.tex: Documentation for the Queue.py module.
Barry Warsaw <barry@python.org>
parents:
diff changeset
48 \renewcommand{\indexsubitem}{(qsize method)}
e6b9d21c8e0c libqueue.tex: Documentation for the Queue.py module.
Barry Warsaw <barry@python.org>
parents:
diff changeset
49
e6b9d21c8e0c libqueue.tex: Documentation for the Queue.py module.
Barry Warsaw <barry@python.org>
parents:
diff changeset
50 \begin{funcdesc}{qsize}{}
e6b9d21c8e0c libqueue.tex: Documentation for the Queue.py module.
Barry Warsaw <barry@python.org>
parents:
diff changeset
51 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
52 semantics, this number is not reliable.
e6b9d21c8e0c libqueue.tex: Documentation for the Queue.py module.
Barry Warsaw <barry@python.org>
parents:
diff changeset
53 \end{funcdesc}
e6b9d21c8e0c libqueue.tex: Documentation for the Queue.py module.
Barry Warsaw <barry@python.org>
parents:
diff changeset
54
e6b9d21c8e0c libqueue.tex: Documentation for the Queue.py module.
Barry Warsaw <barry@python.org>
parents:
diff changeset
55 \renewcommand{\indexsubitem}{(empty method)}
e6b9d21c8e0c libqueue.tex: Documentation for the Queue.py module.
Barry Warsaw <barry@python.org>
parents:
diff changeset
56
e6b9d21c8e0c libqueue.tex: Documentation for the Queue.py module.
Barry Warsaw <barry@python.org>
parents:
diff changeset
57 \begin{funcdesc}{empty}{}
e6b9d21c8e0c libqueue.tex: Documentation for the Queue.py module.
Barry Warsaw <barry@python.org>
parents:
diff changeset
58 Returns 1 if the queue is empty, 0 otherwise. Because of
e6b9d21c8e0c libqueue.tex: Documentation for the Queue.py module.
Barry Warsaw <barry@python.org>
parents:
diff changeset
59 multithreading semantics, this is not reliable.
e6b9d21c8e0c libqueue.tex: Documentation for the Queue.py module.
Barry Warsaw <barry@python.org>
parents:
diff changeset
60 \end{funcdesc}
e6b9d21c8e0c libqueue.tex: Documentation for the Queue.py module.
Barry Warsaw <barry@python.org>
parents:
diff changeset
61
e6b9d21c8e0c libqueue.tex: Documentation for the Queue.py module.
Barry Warsaw <barry@python.org>
parents:
diff changeset
62 \renewcommand{\indexsubitem}{(full method)}
e6b9d21c8e0c libqueue.tex: Documentation for the Queue.py module.
Barry Warsaw <barry@python.org>
parents:
diff changeset
63
e6b9d21c8e0c libqueue.tex: Documentation for the Queue.py module.
Barry Warsaw <barry@python.org>
parents:
diff changeset
64 \begin{funcdesc}{full}{}
e6b9d21c8e0c libqueue.tex: Documentation for the Queue.py module.
Barry Warsaw <barry@python.org>
parents:
diff changeset
65 Returns 1 if the queue is full, 0 otherwise. Because of
e6b9d21c8e0c libqueue.tex: Documentation for the Queue.py module.
Barry Warsaw <barry@python.org>
parents:
diff changeset
66 multithreading semantics, this is not reliable.
e6b9d21c8e0c libqueue.tex: Documentation for the Queue.py module.
Barry Warsaw <barry@python.org>
parents:
diff changeset
67 \end{funcdesc}
e6b9d21c8e0c libqueue.tex: Documentation for the Queue.py module.
Barry Warsaw <barry@python.org>
parents:
diff changeset
68
e6b9d21c8e0c libqueue.tex: Documentation for the Queue.py module.
Barry Warsaw <barry@python.org>
parents:
diff changeset
69 \renewcommand{\indexsubitem}{(put method)}
e6b9d21c8e0c libqueue.tex: Documentation for the Queue.py module.
Barry Warsaw <barry@python.org>
parents:
diff changeset
70
e6b9d21c8e0c libqueue.tex: Documentation for the Queue.py module.
Barry Warsaw <barry@python.org>
parents:
diff changeset
71 \begin{funcdesc}{put}{item}
e6b9d21c8e0c libqueue.tex: Documentation for the Queue.py module.
Barry Warsaw <barry@python.org>
parents:
diff changeset
72 Puts \var{item} into the queue.
e6b9d21c8e0c libqueue.tex: Documentation for the Queue.py module.
Barry Warsaw <barry@python.org>
parents:
diff changeset
73 \end{funcdesc}
e6b9d21c8e0c libqueue.tex: Documentation for the Queue.py module.
Barry Warsaw <barry@python.org>
parents:
diff changeset
74
e6b9d21c8e0c libqueue.tex: Documentation for the Queue.py module.
Barry Warsaw <barry@python.org>
parents:
diff changeset
75 \renewcommand{\indexsubitem}{(get method)}
e6b9d21c8e0c libqueue.tex: Documentation for the Queue.py module.
Barry Warsaw <barry@python.org>
parents:
diff changeset
76
e6b9d21c8e0c libqueue.tex: Documentation for the Queue.py module.
Barry Warsaw <barry@python.org>
parents:
diff changeset
77 \begin{funcdesc}{get}{}
e6b9d21c8e0c libqueue.tex: Documentation for the Queue.py module.
Barry Warsaw <barry@python.org>
parents:
diff changeset
78 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
79 one is available.
e6b9d21c8e0c libqueue.tex: Documentation for the Queue.py module.
Barry Warsaw <barry@python.org>
parents:
diff changeset
80 \end{funcdesc}
e6b9d21c8e0c libqueue.tex: Documentation for the Queue.py module.
Barry Warsaw <barry@python.org>
parents:
diff changeset
81
e6b9d21c8e0c libqueue.tex: Documentation for the Queue.py module.
Barry Warsaw <barry@python.org>
parents:
diff changeset
82 \renewcommand{\indexsubitem}{(get_nowait method)}
e6b9d21c8e0c libqueue.tex: Documentation for the Queue.py module.
Barry Warsaw <barry@python.org>
parents:
diff changeset
83
e6b9d21c8e0c libqueue.tex: Documentation for the Queue.py module.
Barry Warsaw <barry@python.org>
parents:
diff changeset
84 \begin{funcdesc}{get_nowait}{}
e6b9d21c8e0c libqueue.tex: Documentation for the Queue.py module.
Barry Warsaw <barry@python.org>
parents:
diff changeset
85 Gets and returns an item from the queue if one is immediately
e6b9d21c8e0c libqueue.tex: Documentation for the Queue.py module.
Barry Warsaw <barry@python.org>
parents:
diff changeset
86 available. Raises an \code{Empty} exception if the queue is empty or
e6b9d21c8e0c libqueue.tex: Documentation for the Queue.py module.
Barry Warsaw <barry@python.org>
parents:
diff changeset
87 if the queue's emptiness cannot be determined.
e6b9d21c8e0c libqueue.tex: Documentation for the Queue.py module.
Barry Warsaw <barry@python.org>
parents:
diff changeset
88 \end{funcdesc}