mirror of
https://github.com/python/cpython.git
synced 2025-07-23 11:15:24 +00:00
5af0e41482
I don't agree it had a bug (see the report), so this is *not* a candidate for backporting, but the docs were confusing and the Queue implementation was old enough to vote. Rewrote put/put_nowait/get/get_nowait from scratch, to use a pair of Conditions (not_full and not_empty), sharing a common mutex. The code is 1/4 the size now, and 6.25x easier to understand. For blocking with timeout, we also get to reuse (indirectly) the tedious timeout code from threading.Condition. The Full and Empty exceptions raised by non-blocking calls are now easy (instead of nearly impossible) to explain truthfully: Full is raised if and only if the Queue truly is full when the non-blocking put call checks the queue size, and similarly for Empty versus non-blocking get. What I don't know is whether the new implementation is slower (or faster) than the old one. I don't really care. Anyone who cares a lot is encouraged to check that.
96 lines
3.4 KiB
TeX
96 lines
3.4 KiB
TeX
\section{\module{Queue} ---
|
|
A synchronized queue class}
|
|
|
|
\declaremodule{standard}{Queue}
|
|
\modulesynopsis{A synchronized queue class.}
|
|
|
|
|
|
The \module{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
|
|
\class{Queue} class in this module implements all the required locking
|
|
semantics. It depends on the availability of thread support in
|
|
Python.
|
|
|
|
The \module{Queue} module defines the following class and exception:
|
|
|
|
|
|
\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}
|
|
|
|
\begin{excdesc}{Empty}
|
|
Exception raised when non-blocking \method{get()} (or
|
|
\method{get_nowait()}) is called on a \class{Queue} object which is
|
|
empty.
|
|
\end{excdesc}
|
|
|
|
\begin{excdesc}{Full}
|
|
Exception raised when non-blocking \method{put()} (or
|
|
\method{put_nowait()}) is called on a \class{Queue} object which is
|
|
full.
|
|
\end{excdesc}
|
|
|
|
\subsection{Queue Objects}
|
|
\label{QueueObjects}
|
|
|
|
Class \class{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
|
|
methods are:
|
|
|
|
\begin{methoddesc}{qsize}{}
|
|
Return the approximate size of the queue. Because of multithreading
|
|
semantics, this number is not reliable.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}{empty}{}
|
|
Return \code{True} if the queue is empty, \code{False} otherwise.
|
|
Because of multithreading semantics, this is not reliable.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}{full}{}
|
|
Return \code{True} if the queue is full, \code{False} otherwise.
|
|
Because of multithreading semantics, this is not reliable.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}{put}{item\optional{, block\optional{, timeout}}}
|
|
Put \var{item} into the queue. If optional args \var{block} is true
|
|
and \var{timeout} is None (the default), block if necessary until a
|
|
free slot is available. If \var{timeout} is a positive number, it
|
|
blocks at most \var{timeout} seconds and raises the \exception{Full}
|
|
exception if no free slot was available within that time.
|
|
Otherwise (\var{block} is false), put an item on the queue if a free
|
|
slot is immediately available, else raise the \exception{Full}
|
|
exception (\var{timeout} is ignored in that case).
|
|
|
|
\versionadded[the timeout parameter]{2.3}
|
|
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}{put_nowait}{item}
|
|
Equivalent to \code{put(\var{item}, False)}.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}{get}{\optional{block\optional{, timeout}}}
|
|
Remove and return an item from the queue. If optional args
|
|
\var{block} is true and \var{timeout} is None (the default),
|
|
block if necessary until an item is available. If \var{timeout} is
|
|
a positive number, it blocks at most \var{timeout} seconds and raises
|
|
the \exception{Empty} exception if no item was available within that
|
|
time. Otherwise (\var{block} is false), return an item if one is
|
|
immediately available, else raise the \exception{Empty} exception
|
|
(\var{timeout} is ignored in that case).
|
|
|
|
\versionadded[the timeout parameter]{2.3}
|
|
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}{get_nowait}{}
|
|
Equivalent to \code{get(False)}.
|
|
\end{methoddesc}
|