diff options
Diffstat (limited to 'Doc/library/queue.rst')
| -rw-r--r-- | Doc/library/queue.rst | 48 |
1 files changed, 19 insertions, 29 deletions
diff --git a/Doc/library/queue.rst b/Doc/library/queue.rst index 179c4c6..bc35dfe 100644 --- a/Doc/library/queue.rst +++ b/Doc/library/queue.rst @@ -1,19 +1,14 @@ -:mod:`Queue` --- A synchronized queue class +:mod:`queue` --- A synchronized queue class =========================================== -.. module:: Queue +.. module:: queue :synopsis: A synchronized queue class. -.. note:: - The :mod:`Queue` module has been renamed to :mod:`queue` in Python 3. The - :term:`2to3` tool will automatically adapt imports when converting your - sources to Python 3. - -**Source code:** :source:`Lib/Queue.py` +**Source code:** :source:`Lib/queue.py` -------------- -The :mod:`Queue` module implements multi-producer, multi-consumer queues. +The :mod:`queue` module implements multi-producer, multi-consumer queues. It is especially useful in threaded 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 @@ -27,7 +22,8 @@ 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. -The :mod:`Queue` module defines the following classes and exceptions: + +The :mod:`queue` module defines the following classes and exceptions: .. class:: Queue(maxsize=0) @@ -43,7 +39,6 @@ The :mod:`Queue` module defines the following classes and exceptions: 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. - .. versionadded:: 2.6 .. class:: PriorityQueue(maxsize=0) @@ -56,7 +51,6 @@ The :mod:`Queue` module defines the following classes and exceptions: one returned by ``sorted(list(entries))[0]``). A typical pattern for entries is a tuple in the form: ``(priority_number, data)``. - .. versionadded:: 2.6 .. exception:: Empty @@ -69,12 +63,6 @@ The :mod:`Queue` module defines the following classes and exceptions: Exception raised when non-blocking :meth:`put` (or :meth:`put_nowait`) is called on a :class:`Queue` object which is full. -.. seealso:: - - :class:`collections.deque` is an alternative implementation of unbounded - queues with fast atomic :func:`append` and :func:`popleft` operations that - do not require locking. - .. _queueobjects: @@ -108,7 +96,7 @@ provide the public methods described below. guarantee that a subsequent call to put() will not block. -.. method:: Queue.put(item[, block[, timeout]]) +.. method:: Queue.put(item, block=True, timeout=None) 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 @@ -118,16 +106,13 @@ provide the public methods described below. immediately available, else raise the :exc:`Full` exception (*timeout* is ignored in that case). - .. versionadded:: 2.3 - The *timeout* parameter. - .. method:: Queue.put_nowait(item) Equivalent to ``put(item, False)``. -.. method:: Queue.get([block[, timeout]]) +.. method:: Queue.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. @@ -136,9 +121,6 @@ provide the public methods described below. Otherwise (*block* is false), return an item if one is immediately available, else raise the :exc:`Empty` exception (*timeout* is ignored in that case). - .. versionadded:: 2.3 - The *timeout* parameter. - .. method:: Queue.get_nowait() @@ -161,8 +143,6 @@ fully processed by daemon consumer threads. Raises a :exc:`ValueError` if called more times than there were items placed in the queue. - .. versionadded:: 2.5 - .. method:: Queue.join() @@ -173,7 +153,6 @@ fully processed by daemon consumer threads. indicate that the item was retrieved and all work on it is complete. When the count of unfinished tasks drops to zero, :meth:`join` unblocks. - .. versionadded:: 2.5 Example of how to wait for enqueued tasks to be completed:: @@ -194,3 +173,14 @@ Example of how to wait for enqueued tasks to be completed:: q.join() # block until all tasks are done + +.. seealso:: + + Class :class:`multiprocessing.Queue` + A queue class for use in a multi-processing (rather than multi-threading) + context. + + :class:`collections.deque` is an alternative implementation of unbounded + queues with fast atomic :func:`append` and :func:`popleft` operations that + do not require locking. + |