libqueue.tex 2.35 KB
Newer Older
1
\section{Standard Module \sectcode{Queue}}
2 3 4 5
\stmodindex{Queue}
\label{module-Queue}


Fred Drake's avatar
Fred Drake committed
6
The \module{Queue} module implements a multi-producer, multi-consumer
7 8
FIFO queue.  It is especially useful in threads programming when
information must be exchanged safely between multiple threads.  The
Fred Drake's avatar
Fred Drake committed
9
\class{Queue} class in this module implements all the required locking
10 11 12
semantics.  It depends on the availability of thread support in
Python.

Fred Drake's avatar
Fred Drake committed
13
The \module{Queue} module defines the following class and exception:
14

Fred Drake's avatar
Fred Drake committed
15 16 17 18 19 20 21 22

\begin{classdesc}{Queue}{maxsize}
Constructor for the class.  \var{maxsize} is an integer that sets the
upperbound limit on the number of items that can be placed in the
queue.  Insertion will block once this size has been reached, until
queue items are consumed.  If \var{maxsize} is less than or equal to
zero, the queue size is infinite.
\end{classdesc}
23 24

\begin{excdesc}{Empty}
Fred Drake's avatar
Fred Drake committed
25 26 27 28
Exception raised when non-blocking get (e.g. \method{get_nowait()}) is
called on a \class{Queue} object which is empty, or for which the
emptyiness cannot be determined (i.e. because the appropriate locks
cannot be acquired).
29 30 31
\end{excdesc}

\subsection{Queue Objects}
Fred Drake's avatar
Fred Drake committed
32
\label{QueueObjects}
33

Fred Drake's avatar
Fred Drake committed
34
Class \class{Queue} implements queue objects and has the methods
35 36 37
described below.  This class can be derived from in order to implement
other queue organizations (e.g. stack) but the inheritable interface
is not described here.  See the source code for details.  The public
Fred Drake's avatar
Fred Drake committed
38
methods are:
39

Fred Drake's avatar
Fred Drake committed
40
\setindexsubitem{(Queue method)}
41 42 43 44 45 46 47

\begin{funcdesc}{qsize}{}
Returns the approximate size of the queue.  Because of multithreading
semantics, this number is not reliable.
\end{funcdesc}

\begin{funcdesc}{empty}{}
Fred Drake's avatar
Fred Drake committed
48 49
Returns \code{1} if the queue is empty, \code{0} otherwise.  Because
of multithreading semantics, this is not reliable.
50 51 52
\end{funcdesc}

\begin{funcdesc}{full}{}
Fred Drake's avatar
Fred Drake committed
53
Returns \code{1} if the queue is full, \code{0} otherwise.  Because of
54 55 56 57 58 59 60 61 62 63 64 65 66 67
multithreading semantics, this is not reliable.
\end{funcdesc}

\begin{funcdesc}{put}{item}
Puts \var{item} into the queue.
\end{funcdesc}

\begin{funcdesc}{get}{}
Gets and returns an item from the queue, blocking if necessary until
one is available.
\end{funcdesc}

\begin{funcdesc}{get_nowait}{}
Gets and returns an item from the queue if one is immediately
Fred Drake's avatar
Fred Drake committed
68 69
available.  Raises an \exception{Empty} exception if the queue is
empty or if the queue's emptiness cannot be determined.
70
\end{funcdesc}