From 17c8e781c0f5d6b7f29b768ffbcaa95438dd9508 Mon Sep 17 00:00:00 2001 From: Barry Warsaw Date: Thu, 20 Nov 1997 19:54:16 +0000 Subject: 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. --- Doc/Makefile | 2 +- Doc/lib.tex | 1 + Doc/lib/lib.tex | 1 + Doc/lib/libqueue.tex | 88 ++++++++++++++++++++++++++++++++++++++++++++++++++++ Doc/libqueue.tex | 88 ++++++++++++++++++++++++++++++++++++++++++++++++++++ 5 files changed, 179 insertions(+), 1 deletion(-) create mode 100644 Doc/lib/libqueue.tex create mode 100644 Doc/libqueue.tex 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} -- cgit v0.12