mirror of https://github.com/python/cpython
146 lines
5.1 KiB
TeX
146 lines
5.1 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}[Queue]{qsize}{}
|
|
Return the approximate size of the queue. Because of multithreading
|
|
semantics, this number is not reliable.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}[Queue]{empty}{}
|
|
Return \code{True} if the queue is empty, \code{False} otherwise.
|
|
Because of multithreading semantics, this is not reliable.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}[Queue]{full}{}
|
|
Return \code{True} if the queue is full, \code{False} otherwise.
|
|
Because of multithreading semantics, this is not reliable.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}[Queue]{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}[Queue]{put_nowait}{item}
|
|
Equivalent to \code{put(\var{item}, False)}.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}[Queue]{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}[Queue]{get_nowait}{}
|
|
Equivalent to \code{get(False)}.
|
|
\end{methoddesc}
|
|
|
|
Two methods are offered to support tracking whether enqueued tasks have
|
|
been fully processed by daemon consumer threads.
|
|
|
|
\begin{methoddesc}[Queue]{task_done}{}
|
|
Indicate that a formerly enqueued task is complete. Used by queue consumer
|
|
threads. For each \method{get()} used to fetch a task, a subsequent call to
|
|
\method{task_done()} tells the queue that the processing on the task is complete.
|
|
|
|
If a \method{join()} is currently blocking, it will resume when all items
|
|
have been processed (meaning that a \method{task_done()} call was received
|
|
for every item that had been \method{put()} into the queue).
|
|
|
|
Raises a \exception{ValueError} if called more times than there were items
|
|
placed in the queue.
|
|
\versionadded{2.5}
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}[Queue]{join}{}
|
|
Blocks until all items in the queue have been gotten and processed.
|
|
|
|
The count of unfinished tasks goes up whenever an item is added to the
|
|
queue. The count goes down whenever a consumer thread calls \method{task_done()}
|
|
to indicate that the item was retrieved and all work on it is complete.
|
|
When the count of unfinished tasks drops to zero, join() unblocks.
|
|
\versionadded{2.5}
|
|
\end{methoddesc}
|
|
|
|
Example of how to wait for enqueued tasks to be completed:
|
|
|
|
\begin{verbatim}
|
|
def worker():
|
|
while True:
|
|
item = q.get()
|
|
do_work(item)
|
|
q.task_done()
|
|
|
|
q = Queue()
|
|
for i in range(num_worker_threads):
|
|
t = Thread(target=worker)
|
|
t.setDaemon(True)
|
|
t.start()
|
|
|
|
for item in source():
|
|
q.put(item)
|
|
|
|
q.join() # block until all tasks are done
|
|
\end{verbatim}
|