cpython-lru_cache-weakref: Doc/lib/libqueue.tex annotate

annotate Doc/lib/libqueue.tex @ 32624:73016bd01a71 legacy-trunk

Bug #788520: Queue class has logic error when non-blocking 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.

author	Tim Peters <tim.peters@gmail.com>
date	Mon, 12 Jul 2004 00:45:14 +0000
parents	63fa60f2d61c
children	bed3f52f0dc6

rev	line source
8918 acfffe14628e New section header style. Fred Drake <fdrake@acm.org> parents: 8716 diff changeset	1 \section{\module{Queue} ---
15142 563dee598d3a Fixed lots of small nits caught by Ka-Ping Yee <ping@lfw.org>. Fred Drake <fdrake@acm.org> parents: 12223 diff changeset	2 A synchronized queue class}
563dee598d3a Fixed lots of small nits caught by Ka-Ping Yee <ping@lfw.org>. Fred Drake <fdrake@acm.org> parents: 12223 diff changeset	3
8716 760dcf197048 Adjusted to use the new module synopsis support macros. Fred Drake <fdrake@acm.org> parents: 7877 diff changeset	4 \declaremodule{standard}{Queue}
8918 acfffe14628e New section header style. Fred Drake <fdrake@acm.org> parents: 8716 diff changeset	5 \modulesynopsis{A synchronized queue class.}
8716 760dcf197048 Adjusted to use the new module synopsis support macros. Fred Drake <fdrake@acm.org> parents: 7877 diff changeset	6
6611 e6b9d21c8e0c libqueue.tex: Documentation for the Queue.py module. Barry Warsaw <barry@python.org> parents: diff changeset	7
7634 3d1590b5e3dd Logical markup. Fred Drake <fdrake@acm.org> parents: 7277 diff changeset	8 The \module{Queue} module implements a multi-producer, multi-consumer
6611 e6b9d21c8e0c libqueue.tex: Documentation for the Queue.py module. Barry Warsaw <barry@python.org> parents: diff changeset	9 FIFO queue. It is especially useful in threads programming when
e6b9d21c8e0c libqueue.tex: Documentation for the Queue.py module. Barry Warsaw <barry@python.org> parents: diff changeset	10 information must be exchanged safely between multiple threads. The
7634 3d1590b5e3dd Logical markup. Fred Drake <fdrake@acm.org> parents: 7277 diff changeset	11 \class{Queue} class in this module implements all the required locking
6611 e6b9d21c8e0c libqueue.tex: Documentation for the Queue.py module. Barry Warsaw <barry@python.org> parents: diff changeset	12 semantics. It depends on the availability of thread support in
e6b9d21c8e0c libqueue.tex: Documentation for the Queue.py module. Barry Warsaw <barry@python.org> parents: diff changeset	13 Python.
e6b9d21c8e0c libqueue.tex: Documentation for the Queue.py module. Barry Warsaw <barry@python.org> parents: diff changeset	14
7634 3d1590b5e3dd Logical markup. Fred Drake <fdrake@acm.org> parents: 7277 diff changeset	15 The \module{Queue} module defines the following class and exception:
6611 e6b9d21c8e0c libqueue.tex: Documentation for the Queue.py module. Barry Warsaw <barry@python.org> parents: diff changeset	16
e6b9d21c8e0c libqueue.tex: Documentation for the Queue.py module. Barry Warsaw <barry@python.org> parents: diff changeset	17
7634 3d1590b5e3dd Logical markup. Fred Drake <fdrake@acm.org> parents: 7277 diff changeset	18 \begin{classdesc}{Queue}{maxsize}
6611 e6b9d21c8e0c libqueue.tex: Documentation for the Queue.py module. Barry Warsaw <barry@python.org> parents: diff changeset	19 Constructor for the class. \var{maxsize} is an integer that sets the
e6b9d21c8e0c libqueue.tex: Documentation for the Queue.py module. Barry Warsaw <barry@python.org> parents: diff changeset	20 upperbound limit on the number of items that can be placed in the
e6b9d21c8e0c libqueue.tex: Documentation for the Queue.py module. Barry Warsaw <barry@python.org> parents: diff changeset	21 queue. Insertion will block once this size has been reached, until
e6b9d21c8e0c libqueue.tex: Documentation for the Queue.py module. Barry Warsaw <barry@python.org> parents: diff changeset	22 queue items are consumed. If \var{maxsize} is less than or equal to
e6b9d21c8e0c libqueue.tex: Documentation for the Queue.py module. Barry Warsaw <barry@python.org> parents: diff changeset	23 zero, the queue size is infinite.
7634 3d1590b5e3dd Logical markup. Fred Drake <fdrake@acm.org> parents: 7277 diff changeset	24 \end{classdesc}
3d1590b5e3dd Logical markup. Fred Drake <fdrake@acm.org> parents: 7277 diff changeset	25
3d1590b5e3dd Logical markup. Fred Drake <fdrake@acm.org> parents: 7277 diff changeset	26 \begin{excdesc}{Empty}
10121 b7d8125c2417 Update documentation to reflect changes to Queue.py by Tim Peters. Guido van Rossum <guido@python.org> parents: 8918 diff changeset	27 Exception raised when non-blocking \method{get()} (or
b7d8125c2417 Update documentation to reflect changes to Queue.py by Tim Peters. Guido van Rossum <guido@python.org> parents: 8918 diff changeset	28 \method{get_nowait()}) is called on a \class{Queue} object which is
32624 73016bd01a71 Bug #788520: Queue class has logic error when non-blocking Tim Peters <tim.peters@gmail.com> parents: 31436 diff changeset	29 empty.
10121 b7d8125c2417 Update documentation to reflect changes to Queue.py by Tim Peters. Guido van Rossum <guido@python.org> parents: 8918 diff changeset	30 \end{excdesc}
b7d8125c2417 Update documentation to reflect changes to Queue.py by Tim Peters. Guido van Rossum <guido@python.org> parents: 8918 diff changeset	31
b7d8125c2417 Update documentation to reflect changes to Queue.py by Tim Peters. Guido van Rossum <guido@python.org> parents: 8918 diff changeset	32 \begin{excdesc}{Full}
b7d8125c2417 Update documentation to reflect changes to Queue.py by Tim Peters. Guido van Rossum <guido@python.org> parents: 8918 diff changeset	33 Exception raised when non-blocking \method{put()} (or
12223 e82e82b3b9ad Merged changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 10121 diff changeset	34 \method{put_nowait()}) is called on a \class{Queue} object which is
32624 73016bd01a71 Bug #788520: Queue class has logic error when non-blocking Tim Peters <tim.peters@gmail.com> parents: 31436 diff changeset	35 full.
7634 3d1590b5e3dd Logical markup. Fred Drake <fdrake@acm.org> parents: 7277 diff changeset	36 \end{excdesc}
6611 e6b9d21c8e0c libqueue.tex: Documentation for the Queue.py module. Barry Warsaw <barry@python.org> parents: diff changeset	37
7634 3d1590b5e3dd Logical markup. Fred Drake <fdrake@acm.org> parents: 7277 diff changeset	38 \subsection{Queue Objects}
3d1590b5e3dd Logical markup. Fred Drake <fdrake@acm.org> parents: 7277 diff changeset	39 \label{QueueObjects}
3d1590b5e3dd Logical markup. Fred Drake <fdrake@acm.org> parents: 7277 diff changeset	40
3d1590b5e3dd Logical markup. Fred Drake <fdrake@acm.org> parents: 7277 diff changeset	41 Class \class{Queue} implements queue objects and has the methods
3d1590b5e3dd Logical markup. Fred Drake <fdrake@acm.org> parents: 7277 diff changeset	42 described below. This class can be derived from in order to implement
3d1590b5e3dd Logical markup. Fred Drake <fdrake@acm.org> parents: 7277 diff changeset	43 other queue organizations (e.g. stack) but the inheritable interface
3d1590b5e3dd Logical markup. Fred Drake <fdrake@acm.org> parents: 7277 diff changeset	44 is not described here. See the source code for details. The public
3d1590b5e3dd Logical markup. Fred Drake <fdrake@acm.org> parents: 7277 diff changeset	45 methods are:
3d1590b5e3dd Logical markup. Fred Drake <fdrake@acm.org> parents: 7277 diff changeset	46
7768 8f177933c41f Use the new {methoddesc} and {memberdesc} environments as appropriate. Fred Drake <fdrake@acm.org> parents: 7634 diff changeset	47 \begin{methoddesc}{qsize}{}
10121 b7d8125c2417 Update documentation to reflect changes to Queue.py by Tim Peters. Guido van Rossum <guido@python.org> parents: 8918 diff changeset	48 Return the approximate size of the queue. Because of multithreading
6611 e6b9d21c8e0c libqueue.tex: Documentation for the Queue.py module. Barry Warsaw <barry@python.org> parents: diff changeset	49 semantics, this number is not reliable.
7768 8f177933c41f Use the new {methoddesc} and {memberdesc} environments as appropriate. Fred Drake <fdrake@acm.org> parents: 7634 diff changeset	50 \end{methoddesc}
6611 e6b9d21c8e0c libqueue.tex: Documentation for the Queue.py module. Barry Warsaw <barry@python.org> parents: diff changeset	51
7768 8f177933c41f Use the new {methoddesc} and {memberdesc} environments as appropriate. Fred Drake <fdrake@acm.org> parents: 7634 diff changeset	52 \begin{methoddesc}{empty}{}
25796 3eafbde56b21 Patch #572628: Optional timeouts for put and get. Martin v. Löwis <martin@v.loewis.de> parents: 23997 diff changeset	53 Return \code{True} if the queue is empty, \code{False} otherwise.
32624 73016bd01a71 Bug #788520: Queue class has logic error when non-blocking Tim Peters <tim.peters@gmail.com> parents: 31436 diff changeset	54 Because of multithreading semantics, this is not reliable.
7768 8f177933c41f Use the new {methoddesc} and {memberdesc} environments as appropriate. Fred Drake <fdrake@acm.org> parents: 7634 diff changeset	55 \end{methoddesc}
6611 e6b9d21c8e0c libqueue.tex: Documentation for the Queue.py module. Barry Warsaw <barry@python.org> parents: diff changeset	56
7768 8f177933c41f Use the new {methoddesc} and {memberdesc} environments as appropriate. Fred Drake <fdrake@acm.org> parents: 7634 diff changeset	57 \begin{methoddesc}{full}{}
25796 3eafbde56b21 Patch #572628: Optional timeouts for put and get. Martin v. Löwis <martin@v.loewis.de> parents: 23997 diff changeset	58 Return \code{True} if the queue is full, \code{False} otherwise.
3eafbde56b21 Patch #572628: Optional timeouts for put and get. Martin v. Löwis <martin@v.loewis.de> parents: 23997 diff changeset	59 Because of multithreading semantics, this is not reliable.
7768 8f177933c41f Use the new {methoddesc} and {memberdesc} environments as appropriate. Fred Drake <fdrake@acm.org> parents: 7634 diff changeset	60 \end{methoddesc}
6611 e6b9d21c8e0c libqueue.tex: Documentation for the Queue.py module. Barry Warsaw <barry@python.org> parents: diff changeset	61
25796 3eafbde56b21 Patch #572628: Optional timeouts for put and get. Martin v. Löwis <martin@v.loewis.de> parents: 23997 diff changeset	62 \begin{methoddesc}{put}{item\optional{, block\optional{, timeout}}}
3eafbde56b21 Patch #572628: Optional timeouts for put and get. Martin v. Löwis <martin@v.loewis.de> parents: 23997 diff changeset	63 Put \var{item} into the queue. If optional args \var{block} is true
3eafbde56b21 Patch #572628: Optional timeouts for put and get. Martin v. Löwis <martin@v.loewis.de> parents: 23997 diff changeset	64 and \var{timeout} is None (the default), block if necessary until a
3eafbde56b21 Patch #572628: Optional timeouts for put and get. Martin v. Löwis <martin@v.loewis.de> parents: 23997 diff changeset	65 free slot is available. If \var{timeout} is a positive number, it
3eafbde56b21 Patch #572628: Optional timeouts for put and get. Martin v. Löwis <martin@v.loewis.de> parents: 23997 diff changeset	66 blocks at most \var{timeout} seconds and raises the \exception{Full}
3eafbde56b21 Patch #572628: Optional timeouts for put and get. Martin v. Löwis <martin@v.loewis.de> parents: 23997 diff changeset	67 exception if no free slot was available within that time.
3eafbde56b21 Patch #572628: Optional timeouts for put and get. Martin v. Löwis <martin@v.loewis.de> parents: 23997 diff changeset	68 Otherwise (\var{block} is false), put an item on the queue if a free
10121 b7d8125c2417 Update documentation to reflect changes to Queue.py by Tim Peters. Guido van Rossum <guido@python.org> parents: 8918 diff changeset	69 slot is immediately available, else raise the \exception{Full}
25796 3eafbde56b21 Patch #572628: Optional timeouts for put and get. Martin v. Löwis <martin@v.loewis.de> parents: 23997 diff changeset	70 exception (\var{timeout} is ignored in that case).
3eafbde56b21 Patch #572628: Optional timeouts for put and get. Martin v. Löwis <martin@v.loewis.de> parents: 23997 diff changeset	71
3eafbde56b21 Patch #572628: Optional timeouts for put and get. Martin v. Löwis <martin@v.loewis.de> parents: 23997 diff changeset	72 \versionadded[the timeout parameter]{2.3}
3eafbde56b21 Patch #572628: Optional timeouts for put and get. Martin v. Löwis <martin@v.loewis.de> parents: 23997 diff changeset	73
7768 8f177933c41f Use the new {methoddesc} and {memberdesc} environments as appropriate. Fred Drake <fdrake@acm.org> parents: 7634 diff changeset	74 \end{methoddesc}
6611 e6b9d21c8e0c libqueue.tex: Documentation for the Queue.py module. Barry Warsaw <barry@python.org> parents: diff changeset	75
10121 b7d8125c2417 Update documentation to reflect changes to Queue.py by Tim Peters. Guido van Rossum <guido@python.org> parents: 8918 diff changeset	76 \begin{methoddesc}{put_nowait}{item}
25796 3eafbde56b21 Patch #572628: Optional timeouts for put and get. Martin v. Löwis <martin@v.loewis.de> parents: 23997 diff changeset	77 Equivalent to \code{put(\var{item}, False)}.
10121 b7d8125c2417 Update documentation to reflect changes to Queue.py by Tim Peters. Guido van Rossum <guido@python.org> parents: 8918 diff changeset	78 \end{methoddesc}
b7d8125c2417 Update documentation to reflect changes to Queue.py by Tim Peters. Guido van Rossum <guido@python.org> parents: 8918 diff changeset	79
25796 3eafbde56b21 Patch #572628: Optional timeouts for put and get. Martin v. Löwis <martin@v.loewis.de> parents: 23997 diff changeset	80 \begin{methoddesc}{get}{\optional{block\optional{, timeout}}}
3eafbde56b21 Patch #572628: Optional timeouts for put and get. Martin v. Löwis <martin@v.loewis.de> parents: 23997 diff changeset	81 Remove and return an item from the queue. If optional args
3eafbde56b21 Patch #572628: Optional timeouts for put and get. Martin v. Löwis <martin@v.loewis.de> parents: 23997 diff changeset	82 \var{block} is true and \var{timeout} is None (the default),
3eafbde56b21 Patch #572628: Optional timeouts for put and get. Martin v. Löwis <martin@v.loewis.de> parents: 23997 diff changeset	83 block if necessary until an item is available. If \var{timeout} is
3eafbde56b21 Patch #572628: Optional timeouts for put and get. Martin v. Löwis <martin@v.loewis.de> parents: 23997 diff changeset	84 a positive number, it blocks at most \var{timeout} seconds and raises
3eafbde56b21 Patch #572628: Optional timeouts for put and get. Martin v. Löwis <martin@v.loewis.de> parents: 23997 diff changeset	85 the \exception{Empty} exception if no item was available within that
3eafbde56b21 Patch #572628: Optional timeouts for put and get. Martin v. Löwis <martin@v.loewis.de> parents: 23997 diff changeset	86 time. Otherwise (\var{block} is false), return an item if one is
3eafbde56b21 Patch #572628: Optional timeouts for put and get. Martin v. Löwis <martin@v.loewis.de> parents: 23997 diff changeset	87 immediately available, else raise the \exception{Empty} exception
3eafbde56b21 Patch #572628: Optional timeouts for put and get. Martin v. Löwis <martin@v.loewis.de> parents: 23997 diff changeset	88 (\var{timeout} is ignored in that case).
3eafbde56b21 Patch #572628: Optional timeouts for put and get. Martin v. Löwis <martin@v.loewis.de> parents: 23997 diff changeset	89
3eafbde56b21 Patch #572628: Optional timeouts for put and get. Martin v. Löwis <martin@v.loewis.de> parents: 23997 diff changeset	90 \versionadded[the timeout parameter]{2.3}
3eafbde56b21 Patch #572628: Optional timeouts for put and get. Martin v. Löwis <martin@v.loewis.de> parents: 23997 diff changeset	91
7768 8f177933c41f Use the new {methoddesc} and {memberdesc} environments as appropriate. Fred Drake <fdrake@acm.org> parents: 7634 diff changeset	92 \end{methoddesc}
6611 e6b9d21c8e0c libqueue.tex: Documentation for the Queue.py module. Barry Warsaw <barry@python.org> parents: diff changeset	93
7768 8f177933c41f Use the new {methoddesc} and {memberdesc} environments as appropriate. Fred Drake <fdrake@acm.org> parents: 7634 diff changeset	94 \begin{methoddesc}{get_nowait}{}
25796 3eafbde56b21 Patch #572628: Optional timeouts for put and get. Martin v. Löwis <martin@v.loewis.de> parents: 23997 diff changeset	95 Equivalent to \code{get(False)}.
7768 8f177933c41f Use the new {methoddesc} and {memberdesc} environments as appropriate. Fred Drake <fdrake@acm.org> parents: 7634 diff changeset	96 \end{methoddesc}

Mercurial > cpython-lru_cache-weakref

annotate Doc/lib/libqueue.tex @ 32624:73016bd01a71 legacy-trunk