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.

5 files changed, 179 insertions, 1 deletions

diff --git a/Doc/Makefile b/Doc/Makefile
index cbf2f2d..1410c12 100644
--- a/Doc/Makefile
+++ b/Doc/Makefile
@@ -113,7 +113,7 @@ LIBFILES = lib.tex \
     libbase64.tex libfnmatch.tex libquopri.tex libzlib.tex libsocksvr.tex \
     libmailbox.tex libcommands.tex libcmath.tex libni.tex libgzip.tex \
     libpprint.tex libcode.tex libmimify.tex libre.tex libmacic.tex \
-    libuserdict.tex libdis.tex libxmllib.tex
+    libuserdict.tex libdis.tex libxmllib.tex libqueue.tex
 
 # Library document
 lib.dvi: $(LIBFILES)
diff --git a/Doc/lib.tex b/Doc/lib.tex
index d6c92e4..aa8c31e 100644
--- a/Doc/lib.tex
+++ b/Doc/lib.tex
@@ -127,6 +127,7 @@ to Python and how to embed it in other applications.
 \input{libsocket}
 \input{libselect}
 \input{libthread}
+\input{libqueue}
 \input{libanydbm}
 \input{libwhichdb}
 \input{libzlib}
diff --git a/Doc/lib/lib.tex b/Doc/lib/lib.tex
index d6c92e4..aa8c31e 100644
--- a/Doc/lib/lib.tex
+++ b/Doc/lib/lib.tex
@@ -127,6 +127,7 @@ to Python and how to embed it in other applications.
 \input{libsocket}
 \input{libselect}
 \input{libthread}
+\input{libqueue}
 \input{libanydbm}
 \input{libwhichdb}
 \input{libzlib}
diff --git a/Doc/lib/libqueue.tex b/Doc/lib/libqueue.tex
new file mode 100644
index 0000000..a082da8
--- /dev/null
+++ b/Doc/lib/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}
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}