cpython/Doc/library/queue.rst

280 lines
10 KiB
ReStructuredText
Raw Normal View History

:mod:`queue` --- A synchronized queue class
2007-08-15 11:28:22 -03:00
===========================================
.. module:: queue
2007-08-15 11:28:22 -03:00
:synopsis: A synchronized queue class.
**Source code:** :source:`Lib/queue.py`
2007-08-15 11:28:22 -03:00
2011-01-10 15:54:11 -04:00
--------------
The :mod:`queue` module implements multi-producer, multi-consumer queues.
Merged revisions 57778-58052 via svnmerge from svn+ssh://pythondev@svn.python.org/python/trunk ........ r57820 | georg.brandl | 2007-08-31 08:59:27 +0200 (Fri, 31 Aug 2007) | 2 lines Document new shorthand notation for index entries. ........ r57827 | georg.brandl | 2007-08-31 10:47:51 +0200 (Fri, 31 Aug 2007) | 2 lines Fix subitem markup. ........ r57833 | martin.v.loewis | 2007-08-31 12:01:07 +0200 (Fri, 31 Aug 2007) | 1 line Mark registry components as 64-bit on Win64. ........ r57854 | bill.janssen | 2007-08-31 21:02:23 +0200 (Fri, 31 Aug 2007) | 1 line deprecate use of FakeSocket ........ r57855 | bill.janssen | 2007-08-31 21:02:46 +0200 (Fri, 31 Aug 2007) | 1 line remove mentions of socket.ssl in comments ........ r57856 | bill.janssen | 2007-08-31 21:03:31 +0200 (Fri, 31 Aug 2007) | 1 line remove use of non-existent SSLFakeSocket in apparently untested code ........ r57859 | martin.v.loewis | 2007-09-01 08:36:03 +0200 (Sat, 01 Sep 2007) | 3 lines Bug #1737210: Change Manufacturer of Windows installer to PSF. Will backport to 2.5. ........ r57865 | georg.brandl | 2007-09-01 09:51:24 +0200 (Sat, 01 Sep 2007) | 2 lines Fix RST link (backport from Py3k). ........ r57876 | georg.brandl | 2007-09-01 17:49:49 +0200 (Sat, 01 Sep 2007) | 2 lines Document sets' ">" and "<" operations (backport from py3k). ........ r57878 | skip.montanaro | 2007-09-01 19:40:03 +0200 (Sat, 01 Sep 2007) | 4 lines Added a note and examples to explain that re.split does not split on an empty pattern match. (issue 852532). ........ r57879 | walter.doerwald | 2007-09-01 20:18:09 +0200 (Sat, 01 Sep 2007) | 2 lines Fix wrong function names. ........ r57880 | walter.doerwald | 2007-09-01 20:34:05 +0200 (Sat, 01 Sep 2007) | 2 lines Fix typo. ........ r57889 | andrew.kuchling | 2007-09-01 22:31:59 +0200 (Sat, 01 Sep 2007) | 1 line Markup fix ........ r57892 | andrew.kuchling | 2007-09-01 22:43:36 +0200 (Sat, 01 Sep 2007) | 1 line Add various items ........ r57895 | andrew.kuchling | 2007-09-01 23:17:58 +0200 (Sat, 01 Sep 2007) | 1 line Wording change ........ r57896 | andrew.kuchling | 2007-09-01 23:18:31 +0200 (Sat, 01 Sep 2007) | 1 line Add more items ........ r57904 | ronald.oussoren | 2007-09-02 11:46:07 +0200 (Sun, 02 Sep 2007) | 3 lines Macosx: this patch ensures that the value of MACOSX_DEPLOYMENT_TARGET used by the Makefile is also used at configure-time. ........ r57925 | georg.brandl | 2007-09-03 09:16:46 +0200 (Mon, 03 Sep 2007) | 2 lines Fix #883466: don't allow Unicode as arguments to quopri and uu codecs. ........ r57936 | matthias.klose | 2007-09-04 01:33:04 +0200 (Tue, 04 Sep 2007) | 2 lines - Added support for linking the bsddb module against BerkeleyDB 4.6.x. ........ r57954 | mark.summerfield | 2007-09-04 10:16:15 +0200 (Tue, 04 Sep 2007) | 3 lines Added cross-references plus a note about dict & list shallow copying. ........ r57958 | martin.v.loewis | 2007-09-04 11:51:57 +0200 (Tue, 04 Sep 2007) | 3 lines Document that we rely on the OS to release the crypto context. Fixes #1626801. ........ r57960 | martin.v.loewis | 2007-09-04 15:13:14 +0200 (Tue, 04 Sep 2007) | 3 lines Patch #1388440: Add set_completion_display_matches_hook and get_completion_type to readline. ........ r57961 | martin.v.loewis | 2007-09-04 16:19:28 +0200 (Tue, 04 Sep 2007) | 3 lines Patch #1031213: Decode source line in SyntaxErrors back to its original source encoding. Will backport to 2.5. ........ r57972 | matthias.klose | 2007-09-04 20:17:36 +0200 (Tue, 04 Sep 2007) | 3 lines - Makefile.pre.in(buildbottest): Run an optional script pybuildbot.identify to include some information about the build environment. ........ r57973 | matthias.klose | 2007-09-04 21:05:38 +0200 (Tue, 04 Sep 2007) | 2 lines - Makefile.pre.in(buildbottest): Remove whitespace at eol. ........ r57975 | matthias.klose | 2007-09-04 22:46:02 +0200 (Tue, 04 Sep 2007) | 2 lines - Fix libffi configure for hppa*-*-linux* | parisc*-*-linux*. ........ r57980 | bill.janssen | 2007-09-05 02:46:27 +0200 (Wed, 05 Sep 2007) | 1 line SSL certificate distinguished names should be represented by tuples ........ r57985 | martin.v.loewis | 2007-09-05 08:39:17 +0200 (Wed, 05 Sep 2007) | 3 lines Patch #1105: Explain that one needs to build the solution to get dependencies right. ........ r57987 | armin.rigo | 2007-09-05 09:51:21 +0200 (Wed, 05 Sep 2007) | 4 lines PyDict_GetItem() returns a borrowed reference. There are probably a number of places that are open to attacks such as the following one, in bltinmodule.c:min_max(). ........ r57991 | martin.v.loewis | 2007-09-05 13:47:34 +0200 (Wed, 05 Sep 2007) | 3 lines Patch #786737: Allow building in a tree of symlinks pointing to a readonly source. ........ r57993 | georg.brandl | 2007-09-05 15:36:44 +0200 (Wed, 05 Sep 2007) | 2 lines Backport from Py3k: Bug #1684991: explain lookup semantics for __special__ methods (new-style classes only). ........ r58004 | armin.rigo | 2007-09-06 10:30:51 +0200 (Thu, 06 Sep 2007) | 4 lines Patch #1733973 by peaker: ptrace_enter_call() assumes no exception is currently set. This assumption is broken when throwing into a generator. ........ r58006 | armin.rigo | 2007-09-06 11:30:38 +0200 (Thu, 06 Sep 2007) | 4 lines PyDict_GetItem() returns a borrowed reference. This attack is against ceval.c:IMPORT_NAME, which calls an object (__builtin__.__import__) without holding a reference to it. ........ r58013 | georg.brandl | 2007-09-06 16:49:56 +0200 (Thu, 06 Sep 2007) | 2 lines Backport from 3k: #1116: fix reference to old filename. ........ r58021 | thomas.heller | 2007-09-06 22:26:20 +0200 (Thu, 06 Sep 2007) | 1 line Fix typo: c_float represents to C float type. ........ r58022 | skip.montanaro | 2007-09-07 00:29:06 +0200 (Fri, 07 Sep 2007) | 3 lines If this is correct for py3k branch and it's already in the release25-maint branch, seems like it ought to be on the trunk as well. ........ r58023 | gregory.p.smith | 2007-09-07 00:59:59 +0200 (Fri, 07 Sep 2007) | 4 lines Apply the fix from Issue1112 to make this test more robust and keep windows happy. ........ r58031 | brett.cannon | 2007-09-07 05:17:50 +0200 (Fri, 07 Sep 2007) | 4 lines Make uuid1 and uuid4 tests conditional on whether ctypes can be imported; implementation of either function depends on ctypes but uuid as a whole does not. ........ r58032 | brett.cannon | 2007-09-07 06:18:30 +0200 (Fri, 07 Sep 2007) | 6 lines Fix a crasher where Python code managed to infinitely recurse in C code without ever going back out to Python code in PyObject_Call(). Required introducing a static RuntimeError instance so that normalizing an exception there is no reliance on a recursive call that would put the exception system over the recursion check itself. ........ r58034 | thomas.heller | 2007-09-07 08:32:17 +0200 (Fri, 07 Sep 2007) | 1 line Add a 'c_longdouble' type to the ctypes module. ........ r58035 | thomas.heller | 2007-09-07 11:30:40 +0200 (Fri, 07 Sep 2007) | 1 line Remove unneeded #include. ........ r58036 | thomas.heller | 2007-09-07 11:33:24 +0200 (Fri, 07 Sep 2007) | 6 lines Backport from py3k branch: Add a workaround for a strange bug on win64, when _ctypes is compiled with the SDK compiler. This should fix the failing Lib\ctypes\test\test_as_parameter.py test. ........ r58037 | georg.brandl | 2007-09-07 16:14:40 +0200 (Fri, 07 Sep 2007) | 2 lines Fix a wrong indentation for sublists. ........ r58043 | georg.brandl | 2007-09-07 22:10:49 +0200 (Fri, 07 Sep 2007) | 2 lines #1095: ln -f doesn't work portably, fix in Makefile. ........ r58049 | skip.montanaro | 2007-09-08 02:34:17 +0200 (Sat, 08 Sep 2007) | 1 line be explicit about the actual location of the missing file ........
2007-09-08 14:39:28 -03:00
It is especially useful in threaded programming when information must be
2007-08-15 11:28:22 -03:00
exchanged safely between multiple threads. The :class:`Queue` class in this
module implements all the required locking semantics.
2007-08-15 11:28:22 -03:00
2012-05-08 22:28:24 -03:00
The module implements three types of queue, which differ only in the order in
2016-05-16 03:31:54 -03:00
which the entries are retrieved. In a :abbr:`FIFO (first-in, first-out)`
queue, the first tasks added are the first retrieved. In a
:abbr:`LIFO (last-in, first-out)` queue, the most recently added entry is
2008-01-16 20:13:27 -04:00
the first retrieved (operating like a stack). With a priority queue,
the entries are kept sorted (using the :mod:`heapq` module) and the
lowest valued entry is retrieved first.
2007-08-15 11:28:22 -03:00
Internally, those three types of queues use locks to temporarily block
competing threads; however, they are not designed to handle reentrancy
within a thread.
In addition, the module implements a "simple"
:abbr:`FIFO (first-in, first-out)` queue type, :class:`SimpleQueue`, whose
specific implementation provides additional guarantees
in exchange for the smaller functionality.
The :mod:`queue` module defines the following classes and exceptions:
2007-08-15 11:28:22 -03:00
.. class:: Queue(maxsize=0)
2007-08-15 11:28:22 -03:00
2016-05-16 03:31:54 -03:00
Constructor for a :abbr:`FIFO (first-in, first-out)` queue. *maxsize* is
an integer that sets the upperbound
2007-08-15 11:28:22 -03:00
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
*maxsize* is less than or equal to zero, the queue size is infinite.
.. class:: LifoQueue(maxsize=0)
2008-01-16 20:13:27 -04:00
2016-05-16 03:31:54 -03:00
Constructor for a :abbr:`LIFO (last-in, first-out)` queue. *maxsize* is
an integer that sets the upperbound
2008-01-16 20:13:27 -04:00
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
*maxsize* is less than or equal to zero, the queue size is infinite.
Merged revisions 59985-60000,60002,60005-60007,60009-60042 via svnmerge from svn+ssh://pythondev@svn.python.org/python/trunk ........ r59987 | raymond.hettinger | 2008-01-15 21:52:42 +0100 (Tue, 15 Jan 2008) | 1 line Refactor if/elif chain for clarity and speed. Remove dependency on subclasses having to implement _empty and _full. ........ r59988 | raymond.hettinger | 2008-01-15 22:22:47 +0100 (Tue, 15 Jan 2008) | 1 line Fix-up half-written paragraph in the docs ........ r59989 | amaury.forgeotdarc | 2008-01-15 22:25:11 +0100 (Tue, 15 Jan 2008) | 3 lines test_doctest fails since r59984. Not sure if these are the correct values, but save_stdout has to be set before its usage... ........ r59992 | andrew.kuchling | 2008-01-16 01:32:03 +0100 (Wed, 16 Jan 2008) | 1 line Docstring typos ........ r59993 | andrew.kuchling | 2008-01-16 04:17:25 +0100 (Wed, 16 Jan 2008) | 1 line Add PEP 3141 section ........ r59998 | andrew.kuchling | 2008-01-16 14:01:51 +0100 (Wed, 16 Jan 2008) | 1 line Markup fix ........ r59999 | georg.brandl | 2008-01-16 17:56:29 +0100 (Wed, 16 Jan 2008) | 2 lines Fix MSDN library URL. (#1854) ........ r60006 | georg.brandl | 2008-01-16 21:27:56 +0100 (Wed, 16 Jan 2008) | 3 lines Add Python-specific content to Doc dir. Update configuration file to work with the newest Sphinx. ........ r60007 | georg.brandl | 2008-01-16 21:29:00 +0100 (Wed, 16 Jan 2008) | 2 lines Doc build should work with 2.4 now. ........ r60009 | raymond.hettinger | 2008-01-17 00:38:16 +0100 (Thu, 17 Jan 2008) | 1 line Minor wordsmithing. ........ r60010 | raymond.hettinger | 2008-01-17 00:40:45 +0100 (Thu, 17 Jan 2008) | 1 line Add queues will alternative fetch orders (priority based and stack based). ........ r60011 | raymond.hettinger | 2008-01-17 00:49:35 +0100 (Thu, 17 Jan 2008) | 1 line Add news entry. ........ r60013 | raymond.hettinger | 2008-01-17 04:02:14 +0100 (Thu, 17 Jan 2008) | 1 line Make starmap() match its pure python definition and accept any itertable input (not just tuples). ........ r60015 | gregory.p.smith | 2008-01-17 08:43:20 +0100 (Thu, 17 Jan 2008) | 3 lines Comply with RFC 3207. Fixes issue 829951 - http://bugs.python.org/issue829951 ........ r60018 | gregory.p.smith | 2008-01-17 09:03:17 +0100 (Thu, 17 Jan 2008) | 2 lines entry for r60015 ........ r60019 | raymond.hettinger | 2008-01-17 09:07:05 +0100 (Thu, 17 Jan 2008) | 1 line Note versionadded. ........ r60020 | gregory.p.smith | 2008-01-17 09:35:49 +0100 (Thu, 17 Jan 2008) | 8 lines Fixes (accepts patch) issue1339 - http://bugs.python.org/issue1339 - Factor out the duplication of EHLO/HELO in login() and sendmail() to a new function, ehlo_or_helo_if_needed(). - Use ehlo_or_helo_if_needed() in starttls() - Check for the starttls exception in starttls() in the same way as login() checks for the auth extension. Contributed by Bill Fenner. ........ r60021 | andrew.kuchling | 2008-01-17 13:00:15 +0100 (Thu, 17 Jan 2008) | 1 line Revise 3141 section a bit; add some Windows items ........ r60022 | brett.cannon | 2008-01-17 19:45:10 +0100 (Thu, 17 Jan 2008) | 2 lines Fix a function pointer declaration to silence the compiler. ........ r60024 | raymond.hettinger | 2008-01-17 20:31:38 +0100 (Thu, 17 Jan 2008) | 1 line Issue #1861: Add read-only attribute listing upcoming events in the order they will be run. ........ r60025 | andrew.kuchling | 2008-01-17 20:49:24 +0100 (Thu, 17 Jan 2008) | 1 line Correction from Jordan Lewis: halfdelay() uses tenths of a second, not milliseconds ........ r60026 | raymond.hettinger | 2008-01-17 23:27:49 +0100 (Thu, 17 Jan 2008) | 1 line Add advice on choosing between scheduler and threading.Timer(). ........ r60028 | christian.heimes | 2008-01-18 00:01:44 +0100 (Fri, 18 Jan 2008) | 2 lines Updated new property syntax. An elaborate example for subclassing and the getter was missing. Added comment about VS 2008 and PGO builds. ........ r60029 | raymond.hettinger | 2008-01-18 00:32:01 +0100 (Fri, 18 Jan 2008) | 1 line Fix-up Timer() example. ........ r60030 | raymond.hettinger | 2008-01-18 00:56:56 +0100 (Fri, 18 Jan 2008) | 1 line Fix markup ........ r60031 | raymond.hettinger | 2008-01-18 01:10:42 +0100 (Fri, 18 Jan 2008) | 1 line clearcache() needs to remove the dict as well as clear it. ........ r60033 | andrew.kuchling | 2008-01-18 03:26:16 +0100 (Fri, 18 Jan 2008) | 1 line Bump verson ........ r60034 | andrew.kuchling | 2008-01-18 03:42:52 +0100 (Fri, 18 Jan 2008) | 1 line Typo fix ........ r60035 | christian.heimes | 2008-01-18 08:30:20 +0100 (Fri, 18 Jan 2008) | 3 lines Coverity issue CID #197 var_decl: Declared variable "stm" without initializer ninit_use_in_call: Using uninitialized value "stm" (field "stm".tm_zone uninitialized) in call to function "mktime" ........ r60036 | christian.heimes | 2008-01-18 08:45:30 +0100 (Fri, 18 Jan 2008) | 11 lines Coverity issue CID #167 Event alloc_fn: Called allocation function "metacompile" [model] Event var_assign: Assigned variable "gr" to storage returned from "metacompile" gr = metacompile(n); Event pass_arg: Variable "gr" not freed or pointed-to in function "maketables" [model] g = maketables(gr); translatelabels(g); addfirstsets(g); Event leaked_storage: Returned without freeing storage "gr" return g; ........ r60038 | christian.heimes | 2008-01-18 09:04:57 +0100 (Fri, 18 Jan 2008) | 3 lines Coverity issue CID #182 size_error: Allocating 1 bytes to pointer "children", which needs at least 4 bytes ........ r60041 | christian.heimes | 2008-01-18 09:47:59 +0100 (Fri, 18 Jan 2008) | 4 lines Coverity issue CID #169 local_ptr_assign_local: Assigning address of stack variable "namebuf" to pointer "filename" out_of_scope: Variable "namebuf" goes out of scope use_invalid: Used "filename" pointing to out-of-scope variable "namebuf" ........ r60042 | christian.heimes | 2008-01-18 09:53:45 +0100 (Fri, 18 Jan 2008) | 2 lines Coverity CID #168 leaked_storage: Returned without freeing storage "fp" ........
2008-01-18 05:56:22 -04:00
.. class:: PriorityQueue(maxsize=0)
2008-01-16 20:13:27 -04:00
Constructor for a priority queue. *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
*maxsize* is less than or equal to zero, the queue size is infinite.
The lowest valued entries are retrieved first (the lowest valued entry is the
one returned by ``sorted(list(entries))[0]``). A typical pattern for entries
is a tuple in the form: ``(priority_number, data)``.
2007-08-15 11:28:22 -03:00
If the *data* elements are not comparable, the data can be wrapped in a class
that ignores the data item and only compares the priority number::
from dataclasses import dataclass, field
from typing import Any
@dataclass(order=True)
class PrioritizedItem:
priority: int
item: Any=field(compare=False)
Merged revisions 59985-60000,60002,60005-60007,60009-60042 via svnmerge from svn+ssh://pythondev@svn.python.org/python/trunk ........ r59987 | raymond.hettinger | 2008-01-15 21:52:42 +0100 (Tue, 15 Jan 2008) | 1 line Refactor if/elif chain for clarity and speed. Remove dependency on subclasses having to implement _empty and _full. ........ r59988 | raymond.hettinger | 2008-01-15 22:22:47 +0100 (Tue, 15 Jan 2008) | 1 line Fix-up half-written paragraph in the docs ........ r59989 | amaury.forgeotdarc | 2008-01-15 22:25:11 +0100 (Tue, 15 Jan 2008) | 3 lines test_doctest fails since r59984. Not sure if these are the correct values, but save_stdout has to be set before its usage... ........ r59992 | andrew.kuchling | 2008-01-16 01:32:03 +0100 (Wed, 16 Jan 2008) | 1 line Docstring typos ........ r59993 | andrew.kuchling | 2008-01-16 04:17:25 +0100 (Wed, 16 Jan 2008) | 1 line Add PEP 3141 section ........ r59998 | andrew.kuchling | 2008-01-16 14:01:51 +0100 (Wed, 16 Jan 2008) | 1 line Markup fix ........ r59999 | georg.brandl | 2008-01-16 17:56:29 +0100 (Wed, 16 Jan 2008) | 2 lines Fix MSDN library URL. (#1854) ........ r60006 | georg.brandl | 2008-01-16 21:27:56 +0100 (Wed, 16 Jan 2008) | 3 lines Add Python-specific content to Doc dir. Update configuration file to work with the newest Sphinx. ........ r60007 | georg.brandl | 2008-01-16 21:29:00 +0100 (Wed, 16 Jan 2008) | 2 lines Doc build should work with 2.4 now. ........ r60009 | raymond.hettinger | 2008-01-17 00:38:16 +0100 (Thu, 17 Jan 2008) | 1 line Minor wordsmithing. ........ r60010 | raymond.hettinger | 2008-01-17 00:40:45 +0100 (Thu, 17 Jan 2008) | 1 line Add queues will alternative fetch orders (priority based and stack based). ........ r60011 | raymond.hettinger | 2008-01-17 00:49:35 +0100 (Thu, 17 Jan 2008) | 1 line Add news entry. ........ r60013 | raymond.hettinger | 2008-01-17 04:02:14 +0100 (Thu, 17 Jan 2008) | 1 line Make starmap() match its pure python definition and accept any itertable input (not just tuples). ........ r60015 | gregory.p.smith | 2008-01-17 08:43:20 +0100 (Thu, 17 Jan 2008) | 3 lines Comply with RFC 3207. Fixes issue 829951 - http://bugs.python.org/issue829951 ........ r60018 | gregory.p.smith | 2008-01-17 09:03:17 +0100 (Thu, 17 Jan 2008) | 2 lines entry for r60015 ........ r60019 | raymond.hettinger | 2008-01-17 09:07:05 +0100 (Thu, 17 Jan 2008) | 1 line Note versionadded. ........ r60020 | gregory.p.smith | 2008-01-17 09:35:49 +0100 (Thu, 17 Jan 2008) | 8 lines Fixes (accepts patch) issue1339 - http://bugs.python.org/issue1339 - Factor out the duplication of EHLO/HELO in login() and sendmail() to a new function, ehlo_or_helo_if_needed(). - Use ehlo_or_helo_if_needed() in starttls() - Check for the starttls exception in starttls() in the same way as login() checks for the auth extension. Contributed by Bill Fenner. ........ r60021 | andrew.kuchling | 2008-01-17 13:00:15 +0100 (Thu, 17 Jan 2008) | 1 line Revise 3141 section a bit; add some Windows items ........ r60022 | brett.cannon | 2008-01-17 19:45:10 +0100 (Thu, 17 Jan 2008) | 2 lines Fix a function pointer declaration to silence the compiler. ........ r60024 | raymond.hettinger | 2008-01-17 20:31:38 +0100 (Thu, 17 Jan 2008) | 1 line Issue #1861: Add read-only attribute listing upcoming events in the order they will be run. ........ r60025 | andrew.kuchling | 2008-01-17 20:49:24 +0100 (Thu, 17 Jan 2008) | 1 line Correction from Jordan Lewis: halfdelay() uses tenths of a second, not milliseconds ........ r60026 | raymond.hettinger | 2008-01-17 23:27:49 +0100 (Thu, 17 Jan 2008) | 1 line Add advice on choosing between scheduler and threading.Timer(). ........ r60028 | christian.heimes | 2008-01-18 00:01:44 +0100 (Fri, 18 Jan 2008) | 2 lines Updated new property syntax. An elaborate example for subclassing and the getter was missing. Added comment about VS 2008 and PGO builds. ........ r60029 | raymond.hettinger | 2008-01-18 00:32:01 +0100 (Fri, 18 Jan 2008) | 1 line Fix-up Timer() example. ........ r60030 | raymond.hettinger | 2008-01-18 00:56:56 +0100 (Fri, 18 Jan 2008) | 1 line Fix markup ........ r60031 | raymond.hettinger | 2008-01-18 01:10:42 +0100 (Fri, 18 Jan 2008) | 1 line clearcache() needs to remove the dict as well as clear it. ........ r60033 | andrew.kuchling | 2008-01-18 03:26:16 +0100 (Fri, 18 Jan 2008) | 1 line Bump verson ........ r60034 | andrew.kuchling | 2008-01-18 03:42:52 +0100 (Fri, 18 Jan 2008) | 1 line Typo fix ........ r60035 | christian.heimes | 2008-01-18 08:30:20 +0100 (Fri, 18 Jan 2008) | 3 lines Coverity issue CID #197 var_decl: Declared variable "stm" without initializer ninit_use_in_call: Using uninitialized value "stm" (field "stm".tm_zone uninitialized) in call to function "mktime" ........ r60036 | christian.heimes | 2008-01-18 08:45:30 +0100 (Fri, 18 Jan 2008) | 11 lines Coverity issue CID #167 Event alloc_fn: Called allocation function "metacompile" [model] Event var_assign: Assigned variable "gr" to storage returned from "metacompile" gr = metacompile(n); Event pass_arg: Variable "gr" not freed or pointed-to in function "maketables" [model] g = maketables(gr); translatelabels(g); addfirstsets(g); Event leaked_storage: Returned without freeing storage "gr" return g; ........ r60038 | christian.heimes | 2008-01-18 09:04:57 +0100 (Fri, 18 Jan 2008) | 3 lines Coverity issue CID #182 size_error: Allocating 1 bytes to pointer "children", which needs at least 4 bytes ........ r60041 | christian.heimes | 2008-01-18 09:47:59 +0100 (Fri, 18 Jan 2008) | 4 lines Coverity issue CID #169 local_ptr_assign_local: Assigning address of stack variable "namebuf" to pointer "filename" out_of_scope: Variable "namebuf" goes out of scope use_invalid: Used "filename" pointing to out-of-scope variable "namebuf" ........ r60042 | christian.heimes | 2008-01-18 09:53:45 +0100 (Fri, 18 Jan 2008) | 2 lines Coverity CID #168 leaked_storage: Returned without freeing storage "fp" ........
2008-01-18 05:56:22 -04:00
.. class:: SimpleQueue()
Constructor for an unbounded :abbr:`FIFO (first-in, first-out)` queue.
Simple queues lack advanced functionality such as task tracking.
.. versionadded:: 3.7
2007-08-15 11:28:22 -03:00
.. exception:: Empty
Exception raised when non-blocking :meth:`~Queue.get` (or
:meth:`~Queue.get_nowait`) is called
2007-08-15 11:28:22 -03:00
on a :class:`Queue` object which is empty.
.. exception:: Full
Exception raised when non-blocking :meth:`~Queue.put` (or
:meth:`~Queue.put_nowait`) is called
2007-08-15 11:28:22 -03:00
on a :class:`Queue` object which is full.
.. _queueobjects:
Queue Objects
-------------
Merged revisions 60481,60485,60489-60520,60523-60527,60530-60533,60535-60538,60540-60551 via svnmerge from svn+ssh://pythondev@svn.python.org/python/trunk NOTE: I blocked the following revisions: svnmerge.py block -r 60521,60522,60528,60529,60534,60539 The new tests must be merged with lots of manual work. ........ r60493 | georg.brandl | 2008-02-01 12:59:08 +0100 (Fri, 01 Feb 2008) | 2 lines Update IPv6 RFC number. ........ r60497 | georg.brandl | 2008-02-01 16:50:15 +0100 (Fri, 01 Feb 2008) | 2 lines Add link checker builder, written for GHOP by Thomas Lamb. ........ r60500 | georg.brandl | 2008-02-01 19:08:09 +0100 (Fri, 01 Feb 2008) | 2 lines Rename batch file. ........ r60504 | christian.heimes | 2008-02-01 19:49:26 +0100 (Fri, 01 Feb 2008) | 1 line More int -> pid_t. ........ r60507 | georg.brandl | 2008-02-01 20:24:01 +0100 (Fri, 01 Feb 2008) | 2 lines Wording nit. ........ r60510 | georg.brandl | 2008-02-01 21:45:33 +0100 (Fri, 01 Feb 2008) | 2 lines Update for latest sphinx latex writer. ........ r60511 | raymond.hettinger | 2008-02-01 22:30:23 +0100 (Fri, 01 Feb 2008) | 1 line Issue #1996: float.as_integer_ratio() should return fraction in lowest terms. ........ r60512 | raymond.hettinger | 2008-02-01 23:15:52 +0100 (Fri, 01 Feb 2008) | 1 line Integer ratio should return ints instead of longs whereever possible. ........ r60513 | raymond.hettinger | 2008-02-01 23:22:50 +0100 (Fri, 01 Feb 2008) | 1 line labs() takes a long for an input. ........ r60514 | raymond.hettinger | 2008-02-01 23:42:59 +0100 (Fri, 01 Feb 2008) | 1 line Test round-trip on float.as_integer_ratio() and float.__truediv__(). ........ r60515 | marc-andre.lemburg | 2008-02-01 23:58:17 +0100 (Fri, 01 Feb 2008) | 3 lines Bump distutils version number to match Python version. ........ r60516 | raymond.hettinger | 2008-02-02 00:12:19 +0100 (Sat, 02 Feb 2008) | 1 line Fix int/long typecase. Add check for non-binary floating point. ........ r60517 | raymond.hettinger | 2008-02-02 00:45:44 +0100 (Sat, 02 Feb 2008) | 1 line Add protection from weirdness while scaling the mantissa to an integer. ........ r60518 | raymond.hettinger | 2008-02-02 06:11:40 +0100 (Sat, 02 Feb 2008) | 1 line Simpler solution to handling non-IEEE 754 environments. ........ r60519 | raymond.hettinger | 2008-02-02 06:24:44 +0100 (Sat, 02 Feb 2008) | 1 line Neaten-up a bit. ........ r60520 | georg.brandl | 2008-02-02 10:56:20 +0100 (Sat, 02 Feb 2008) | 2 lines Amendments to the urllib2 docs, written for GHOP by Thomas Lamb. ........ r60525 | georg.brandl | 2008-02-02 11:49:58 +0100 (Sat, 02 Feb 2008) | 3 lines Add email example how to send a multipart message. Written for GHOP by Martin Matejek. ........ r60526 | georg.brandl | 2008-02-02 12:05:00 +0100 (Sat, 02 Feb 2008) | 2 lines Rewrite test_socketserver as unittest, written for GHOP by Benjamin Petersen. ........ r60527 | georg.brandl | 2008-02-02 12:05:34 +0100 (Sat, 02 Feb 2008) | 2 lines Add GHOP contributor. ........ r60530 | mark.dickinson | 2008-02-02 18:16:13 +0100 (Sat, 02 Feb 2008) | 2 lines Make the Rational constructor accept '3.' and '.2' as well as '3.2'. ........ r60531 | neal.norwitz | 2008-02-02 19:52:51 +0100 (Sat, 02 Feb 2008) | 1 line Update the leaky tests (ie, ignore these tests if they report leaks). This version has been running for a while. ........ r60533 | skip.montanaro | 2008-02-02 20:11:57 +0100 (Sat, 02 Feb 2008) | 7 lines Split the refleak mail body into two parts, the first being those failing tests which are deemed more important issues, the second those which are known to have difficult to solve problems and are generally expected to leak. Hopefully this doesn't break the script... ........ r60535 | georg.brandl | 2008-02-03 01:04:50 +0100 (Sun, 03 Feb 2008) | 3 lines Wait for a delay before reaping children -- this should fix the test_socketserver failures on several platforms. ........ r60536 | brett.cannon | 2008-02-03 03:07:55 +0100 (Sun, 03 Feb 2008) | 2 lines Fix a minor typo. ........ r60537 | brett.cannon | 2008-02-03 03:08:45 +0100 (Sun, 03 Feb 2008) | 3 lines Directories from CPPFLAGS and LDFLAGS were being added in the reverse order for searches as to how they were listed in the environment variable. ........ r60538 | brett.cannon | 2008-02-03 03:34:14 +0100 (Sun, 03 Feb 2008) | 2 lines Remove extra tick marks and add a missing closing parenthesis. ........ r60540 | andrew.macintyre | 2008-02-03 07:58:06 +0100 (Sun, 03 Feb 2008) | 2 lines Update OS/2 EMX build bits for 2.6. ........ r60541 | andrew.macintyre | 2008-02-03 08:01:11 +0100 (Sun, 03 Feb 2008) | 2 lines Rename module definition file to reflect v2.6. ........ r60542 | andrew.macintyre | 2008-02-03 08:07:31 +0100 (Sun, 03 Feb 2008) | 6 lines The wrapper function is supposed to be for spawnvpe() so that's what we should call [this wrapper only available on OS/2]. Backport candidate to 2.5. ........ r60544 | gregory.p.smith | 2008-02-03 08:20:53 +0100 (Sun, 03 Feb 2008) | 6 lines Merge this fix from the pybsddb tree: r293 | jcea | 2008-01-31 01:08:19 -0800 (Thu, 31 Jan 2008) | 4 lines Solved memory leak when using cursors with databases without environment. ........ r60546 | gregory.p.smith | 2008-02-03 09:01:46 +0100 (Sun, 03 Feb 2008) | 2 lines remove a repeated occurance of a hardcoded berkeleydb library version number ........ r60549 | brett.cannon | 2008-02-03 10:59:21 +0100 (Sun, 03 Feb 2008) | 2 lines Add an entry for r60537. ........ r60550 | georg.brandl | 2008-02-03 13:29:00 +0100 (Sun, 03 Feb 2008) | 2 lines #2003: fix sentence. ........ r60551 | christian.heimes | 2008-02-03 15:34:18 +0100 (Sun, 03 Feb 2008) | 2 lines Fixed paths to Windows build directories in build_ext.py Use vsbuild instead of devenv in build.bat and _bsddb.vcproj ........
2008-02-03 12:51:08 -04:00
Queue objects (:class:`Queue`, :class:`LifoQueue`, or :class:`PriorityQueue`)
2009-01-03 17:18:54 -04:00
provide the public methods described below.
2007-08-15 11:28:22 -03:00
.. method:: Queue.qsize()
Merged revisions 59952-59984 via svnmerge from svn+ssh://pythondev@svn.python.org/python/trunk ........ r59952 | thomas.heller | 2008-01-14 02:35:28 -0800 (Mon, 14 Jan 2008) | 1 line Issue 1821: configure libffi for amd64 on FreeeBSD. ........ r59953 | andrew.kuchling | 2008-01-14 06:48:43 -0800 (Mon, 14 Jan 2008) | 1 line Update description of float_info ........ r59959 | raymond.hettinger | 2008-01-14 14:58:05 -0800 (Mon, 14 Jan 2008) | 1 line Fix 1698398: Zipfile.printdir() crashed because the format string expected a tuple object of length six instead of a time.struct_time object. ........ r59961 | andrew.kuchling | 2008-01-14 17:29:16 -0800 (Mon, 14 Jan 2008) | 1 line Typo fixes ........ r59962 | andrew.kuchling | 2008-01-14 17:29:44 -0800 (Mon, 14 Jan 2008) | 1 line Markup fix ........ r59963 | andrew.kuchling | 2008-01-14 17:47:32 -0800 (Mon, 14 Jan 2008) | 1 line Add many items ........ r59964 | andrew.kuchling | 2008-01-14 17:55:32 -0800 (Mon, 14 Jan 2008) | 1 line Repair unfinished sentence ........ r59967 | raymond.hettinger | 2008-01-14 19:02:37 -0800 (Mon, 14 Jan 2008) | 5 lines Issue 1820: structseq objects did not work with the % formatting operator or isinstance(t, tuple). Orignal patch (without tests) by Leif Walsh. ........ r59968 | raymond.hettinger | 2008-01-14 19:07:42 -0800 (Mon, 14 Jan 2008) | 1 line Tighten the definition of a named tuple. ........ r59969 | skip.montanaro | 2008-01-14 19:40:20 -0800 (Mon, 14 Jan 2008) | 3 lines Better (?) text describing the lack of guarantees provided by qsize(), empty() and full(). ........ r59970 | raymond.hettinger | 2008-01-14 21:39:59 -0800 (Mon, 14 Jan 2008) | 1 line Temporarily revert 59967 until GC can be added. ........ r59971 | raymond.hettinger | 2008-01-14 21:46:43 -0800 (Mon, 14 Jan 2008) | 1 line Small grammar nit ........ r59972 | georg.brandl | 2008-01-14 22:55:56 -0800 (Mon, 14 Jan 2008) | 2 lines Typo. ........ r59973 | georg.brandl | 2008-01-14 22:58:15 -0800 (Mon, 14 Jan 2008) | 2 lines Remove duplicate entry. ........ r59974 | jeffrey.yasskin | 2008-01-14 23:46:24 -0800 (Mon, 14 Jan 2008) | 12 lines Add rational.Rational as an implementation of numbers.Rational with infinite precision. This has been discussed at http://bugs.python.org/issue1682. It's useful primarily for teaching, but it also demonstrates how to implement a member of the numeric tower, including fallbacks for mixed-mode arithmetic. I expect to write a couple more patches in this area: * Rational.from_decimal() * Rational.trim/approximate() (maybe with different names) * Maybe remove the parentheses from Rational.__str__() * Maybe rename one of the Rational classes * Maybe make Rational('3/2') work. ........ r59978 | andrew.kuchling | 2008-01-15 06:38:05 -0800 (Tue, 15 Jan 2008) | 8 lines Restore description of sys.dont_write_bytecode. The duplication is intentional -- this paragraph is in a section describing additions to the sys module, and there's a later section that mentions the switch. I think most people scan the what's-new and don't read it in detail, so a bit of duplication is OK. ........ r59984 | guido.van.rossum | 2008-01-15 09:59:29 -0800 (Tue, 15 Jan 2008) | 3 lines Issue #1786 (by myself): pdb should use its own stdin/stdout around an exec call and when creating a recursive instance. ........
2008-01-15 17:44:53 -04:00
Return the approximate size of the queue. Note, qsize() > 0 doesn't
guarantee that a subsequent get() will not block, nor will qsize() < maxsize
guarantee that put() will not block.
2007-08-15 11:28:22 -03:00
.. method:: Queue.empty()
Return ``True`` if the queue is empty, ``False`` otherwise. If empty()
returns ``True`` it doesn't guarantee that a subsequent call to put()
will not block. Similarly, if empty() returns ``False`` it doesn't
guarantee that a subsequent call to get() will not block.
.. method:: Queue.full()
Return ``True`` if the queue is full, ``False`` otherwise. If full()
returns ``True`` it doesn't guarantee that a subsequent call to get()
will not block. Similarly, if full() returns ``False`` it doesn't
guarantee that a subsequent call to put() will not block.
.. method:: Queue.put(item, block=True, timeout=None)
2007-08-15 11:28:22 -03:00
Put *item* into the queue. If optional args *block* is true and *timeout* is
``None`` (the default), block if necessary until a free slot is available. If
2007-08-15 11:28:22 -03:00
*timeout* is a positive number, it blocks at most *timeout* seconds and raises
the :exc:`Full` exception if no free slot was available within that time.
Otherwise (*block* is false), put an item on the queue if a free slot is
immediately available, else raise the :exc:`Full` exception (*timeout* is
ignored in that case).
.. method:: Queue.put_nowait(item)
Equivalent to ``put(item, block=False)``.
2007-08-15 11:28:22 -03:00
.. method:: Queue.get(block=True, timeout=None)
2007-08-15 11:28:22 -03:00
Remove and return an item from the queue. If optional args *block* is true and
*timeout* is ``None`` (the default), block if necessary until an item is available.
2007-08-15 11:28:22 -03:00
If *timeout* is a positive number, it blocks at most *timeout* seconds and
raises the :exc:`Empty` exception if no item was available within that time.
Otherwise (*block* is false), return an item if one is immediately available,
else raise the :exc:`Empty` exception (*timeout* is ignored in that case).
Prior to 3.0 on POSIX systems, and for all versions on Windows, if
*block* is true and *timeout* is ``None``, this operation goes into
an uninterruptible wait on an underlying lock. This means that no exceptions
can occur, and in particular a SIGINT will not trigger a :exc:`KeyboardInterrupt`.
2007-08-15 11:28:22 -03:00
.. method:: Queue.get_nowait()
Equivalent to ``get(False)``.
Two methods are offered to support tracking whether enqueued tasks have been
fully processed by daemon consumer threads.
.. method:: Queue.task_done()
Indicate that a formerly enqueued task is complete. Used by queue consumer
threads. For each :meth:`get` used to fetch a task, a subsequent call to
:meth:`task_done` tells the queue that the processing on the task is complete.
If a :meth:`join` is currently blocking, it will resume when all items have been
processed (meaning that a :meth:`task_done` call was received for every item
that had been :meth:`put` into the queue).
Raises a :exc:`ValueError` if called more times than there were items placed in
the queue.
.. method:: 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 :meth:`task_done` to
indicate that the item was retrieved and all work on it is complete. When the
2009-03-09 21:07:25 -03:00
count of unfinished tasks drops to zero, :meth:`join` unblocks.
2007-08-15 11:28:22 -03:00
Example of how to wait for enqueued tasks to be completed::
import threading, queue
q = queue.Queue()
def worker():
while True:
item = q.get()
print(f'Working on {item}')
print(f'Finished {item}')
q.task_done()
# Turn-on the worker thread.
threading.Thread(target=worker, daemon=True).start()
2007-08-15 11:28:22 -03:00
# Send thirty task requests to the worker.
for item in range(30):
q.put(item)
2007-08-15 11:28:22 -03:00
# Block until all tasks are done.
q.join()
print('All work completed')
2007-08-15 11:28:22 -03:00
SimpleQueue Objects
-------------------
:class:`SimpleQueue` objects provide the public methods described below.
.. method:: SimpleQueue.qsize()
Return the approximate size of the queue. Note, qsize() > 0 doesn't
guarantee that a subsequent get() will not block.
.. method:: SimpleQueue.empty()
Return ``True`` if the queue is empty, ``False`` otherwise. If empty()
returns ``False`` it doesn't guarantee that a subsequent call to get()
will not block.
.. method:: SimpleQueue.put(item, block=True, timeout=None)
Put *item* into the queue. The method never blocks and always succeeds
(except for potential low-level errors such as failure to allocate memory).
The optional args *block* and *timeout* are ignored and only provided
for compatibility with :meth:`Queue.put`.
.. impl-detail::
This method has a C implementation which is reentrant. That is, a
``put()`` or ``get()`` call can be interrupted by another ``put()``
call in the same thread without deadlocking or corrupting internal
state inside the queue. This makes it appropriate for use in
destructors such as ``__del__`` methods or :mod:`weakref` callbacks.
.. method:: SimpleQueue.put_nowait(item)
Equivalent to ``put(item, block=False)``, provided for compatibility with
:meth:`Queue.put_nowait`.
.. method:: SimpleQueue.get(block=True, timeout=None)
Remove and return an item from the queue. If optional args *block* is true and
*timeout* is ``None`` (the default), block if necessary until an item is available.
If *timeout* is a positive number, it blocks at most *timeout* seconds and
raises the :exc:`Empty` exception if no item was available within that time.
Otherwise (*block* is false), return an item if one is immediately available,
else raise the :exc:`Empty` exception (*timeout* is ignored in that case).
.. method:: SimpleQueue.get_nowait()
Equivalent to ``get(False)``.
.. seealso::
Class :class:`multiprocessing.Queue`
A queue class for use in a multi-processing (rather than multi-threading)
context.
2011-01-07 16:58:25 -04:00
:class:`collections.deque` is an alternative implementation of unbounded
queues with fast atomic :meth:`~collections.deque.append` and
:meth:`~collections.deque.popleft` operations that do not require locking
and also support indexing.