diff options
Diffstat (limited to 'Doc/lib/libqueue.tex')
-rw-r--r-- | Doc/lib/libqueue.tex | 145 |
1 files changed, 0 insertions, 145 deletions
diff --git a/Doc/lib/libqueue.tex b/Doc/lib/libqueue.tex deleted file mode 100644 index 591a910..0000000 --- a/Doc/lib/libqueue.tex +++ /dev/null @@ -1,145 +0,0 @@ - -\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} |