summaryrefslogtreecommitdiffstats
path: root/Doc/libqueue.tex
diff options
context:
space:
mode:
authorBarry Warsaw <barry@python.org>1997-11-20 19:54:16 (GMT)
committerBarry Warsaw <barry@python.org>1997-11-20 19:54:16 (GMT)
commit17c8e781c0f5d6b7f29b768ffbcaa95438dd9508 (patch)
treec806a381cc63ed9c63f184939cfdc8fd395d7bf7 /Doc/libqueue.tex
parent51bb7b79406a65f78075da371fda74af5d6b2f98 (diff)
downloadcpython-17c8e781c0f5d6b7f29b768ffbcaa95438dd9508.zip
cpython-17c8e781c0f5d6b7f29b768ffbcaa95438dd9508.tar.gz
cpython-17c8e781c0f5d6b7f29b768ffbcaa95438dd9508.tar.bz2
libqueue.tex: Documentation for the Queue.py module.
Makefile: Add dependency on libqueue.tex lib.tex: Place the libqueue.tex documentation just after libthread.tex since Queue depends on thread support in Python.
Diffstat (limited to 'Doc/libqueue.tex')
-rw-r--r--Doc/libqueue.tex88
1 files changed, 88 insertions, 0 deletions
diff --git a/Doc/libqueue.tex b/Doc/libqueue.tex
new file mode 100644
index 0000000..a082da8
--- /dev/null
+++ b/Doc/libqueue.tex
@@ -0,0 +1,88 @@
+\section{Standard module \sectcode{Queue}}
+\stmodindex{Queue}
+
+\label{module-Queue}
+
+% ==== 2. ====
+% Give a short overview of what the module does.
+% If it is platform specific, mention this.
+% Mention other important restrictions or general operating principles.
+% For example:
+
+The \code{Queue} module implements a multi-producer, multi-consumer
+FIFO queue. It is especially useful in threads programming when
+information must be exchanged safely between multiple threads. The
+\code{Queue} class in this module implements all the required locking
+semantics. It depends on the availability of thread support in
+Python.
+
+The \code{Queue} module defines the following exception:
+
+\renewcommand{\indexsubitem}{(in module Queue)}
+
+\begin{excdesc}{Empty}
+Exception raised when non-blocking get (e.g. \code{get_nowait()}) is
+called on a Queue object which is empty, or for which the emptyiness
+cannot be determined (i.e. because the appropriate locks cannot be
+acquired).
+\end{excdesc}
+
+\subsection{Queue Objects}
+
+Class \code{Queue} implements queue objects and has the methods
+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
+interface methods are:
+
+\renewcommand{\indexsubitem}{(__init__ method)}
+
+\begin{funcdesc}{__init__}{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{funcdesc}
+
+\renewcommand{\indexsubitem}{(qsize method)}
+
+\begin{funcdesc}{qsize}{}
+Returns the approximate size of the queue. Because of multithreading
+semantics, this number is not reliable.
+\end{funcdesc}
+
+\renewcommand{\indexsubitem}{(empty method)}
+
+\begin{funcdesc}{empty}{}
+Returns 1 if the queue is empty, 0 otherwise. Because of
+multithreading semantics, this is not reliable.
+\end{funcdesc}
+
+\renewcommand{\indexsubitem}{(full method)}
+
+\begin{funcdesc}{full}{}
+Returns 1 if the queue is full, 0 otherwise. Because of
+multithreading semantics, this is not reliable.
+\end{funcdesc}
+
+\renewcommand{\indexsubitem}{(put method)}
+
+\begin{funcdesc}{put}{item}
+Puts \var{item} into the queue.
+\end{funcdesc}
+
+\renewcommand{\indexsubitem}{(get method)}
+
+\begin{funcdesc}{get}{}
+Gets and returns an item from the queue, blocking if necessary until
+one is available.
+\end{funcdesc}
+
+\renewcommand{\indexsubitem}{(get_nowait method)}
+
+\begin{funcdesc}{get_nowait}{}
+Gets and returns an item from the queue if one is immediately
+available. Raises an \code{Empty} exception if the queue is empty or
+if the queue's emptiness cannot be determined.
+\end{funcdesc}