diff --git a/Doc/library/asyncio-queue.rst b/Doc/library/asyncio-queue.rst
index d99213aa81d53e..963bc1fb82c12f 100644
--- a/Doc/library/asyncio-queue.rst
+++ b/Doc/library/asyncio-queue.rst
@@ -102,17 +102,33 @@ Queue
.. method:: shutdown(immediate=False)
- Shut down the queue, making :meth:`~Queue.get` and :meth:`~Queue.put`
+ Put a :class:`Queue` instance into a shutdown mode.
+
+ The queue can no longer grow.
+ Future calls to :meth:`~Queue.put` raise :exc:`QueueShutDown`.
+ Currently blocked callers of :meth:`~Queue.put` will be unblocked
+ and will raise :exc:`QueueShutDown` in the formerly blocked thread.
+
+ If *immediate* is false (the default), the queue can be wound
+ down normally with :meth:`~Queue.get` calls to extract tasks
+ that have already been loaded.
+
+ And if :meth:`~Queue.task_done` is called for each remaining task, a
+ pending :meth:`~Queue.join` will be unblocked normally.
+
+ Once the queue is empty, future calls to :meth:`~Queue.get` will
raise :exc:`QueueShutDown`.
- By default, :meth:`~Queue.get` on a shut down queue will only
- raise once the queue is empty. Set *immediate* to true to make
- :meth:`~Queue.get` raise immediately instead.
+ If *immediate* is true, the queue is terminated immediately.
+ The queue is drained to be completely empty. All callers of
+ :meth:`~Queue.join` are unblocked regardless of the number
+ of unfinished tasks. Blocked callers of :meth:`~Queue.get`
+ are unblocked and will raise :exc:`QueueShutDown` because the
+ queue is empty.
- All blocked callers of :meth:`~Queue.put` and :meth:`~Queue.get`
- will be unblocked. If *immediate* is true, a task will be marked
- as done for each remaining item in the queue, which may unblock
- callers of :meth:`~Queue.join`.
+ Use caution when using :meth:`~Queue.join` with *immediate* set
+ to true. This unblocks the join even when no work has been done
+ on the tasks, violating the usual invariant for joining a queue.
.. versionadded:: 3.13
@@ -129,9 +145,6 @@ Queue
call was received for every item that had been :meth:`~Queue.put`
into the queue).
- ``shutdown(immediate=True)`` calls :meth:`task_done` for each
- remaining item in the queue.
-
Raises :exc:`ValueError` if called more times than there were
items placed in the queue.
diff --git a/Doc/library/queue.rst b/Doc/library/queue.rst
index fbbebcf4ed8f92..6dcf06aab00295 100644
--- a/Doc/library/queue.rst
+++ b/Doc/library/queue.rst
@@ -187,9 +187,6 @@ fully processed by daemon consumer threads.
processed (meaning that a :meth:`task_done` call was received for every item
that had been :meth:`put` into the queue).
- ``shutdown(immediate=True)`` calls :meth:`task_done` for each remaining item
- in the queue.
-
Raises a :exc:`ValueError` if called more times than there were items placed in
the queue.
@@ -204,6 +201,9 @@ fully processed by daemon consumer threads.
count of unfinished tasks drops to zero, :meth:`join` unblocks.
+Waiting for task completion
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
Example of how to wait for enqueued tasks to be completed::
import threading
@@ -233,22 +233,38 @@ Example of how to wait for enqueued tasks to be completed::
Terminating queues
^^^^^^^^^^^^^^^^^^
-:class:`Queue` objects can be made to prevent further interaction by shutting
-them down.
+When no longer needed, :class:`Queue` objects can be wound down
+until empty or terminated immediately with a hard shutdown.
.. method:: Queue.shutdown(immediate=False)
- Shut down the queue, making :meth:`~Queue.get` and :meth:`~Queue.put` raise
- :exc:`ShutDown`.
+ Put a :class:`Queue` instance into a shutdown mode.
+
+ The queue can no longer grow.
+ Future calls to :meth:`~Queue.put` raise :exc:`ShutDown`.
+ Currently blocked callers of :meth:`~Queue.put` will be unblocked
+ and will raise :exc:`ShutDown` in the formerly blocked thread.
+
+ If *immediate* is false (the default), the queue can be wound
+ down normally with :meth:`~Queue.get` calls to extract tasks
+ that have already been loaded.
+
+ And if :meth:`~Queue.task_done` is called for each remaining task, a
+ pending :meth:`~Queue.join` will be unblocked normally.
+
+ Once the queue is empty, future calls to :meth:`~Queue.get` will
+ raise :exc:`ShutDown`.
- By default, :meth:`~Queue.get` on a shut down queue will only raise once the
- queue is empty. Set *immediate* to true to make :meth:`~Queue.get` raise
- immediately instead.
+ If *immediate* is true, the queue is terminated immediately.
+ The queue is drained to be completely empty. All callers of
+ :meth:`~Queue.join` are unblocked regardless of the number
+ of unfinished tasks. Blocked callers of :meth:`~Queue.get`
+ are unblocked and will raise :exc:`ShutDown` because the
+ queue is empty.
- All blocked callers of :meth:`~Queue.put` and :meth:`~Queue.get` will be
- unblocked. If *immediate* is true, a task will be marked as done for each
- remaining item in the queue, which may unblock callers of
- :meth:`~Queue.join`.
+ Use caution when using :meth:`~Queue.join` with *immediate* set
+ to true. This unblocks the join even when no work has been done
+ on the tasks, violating the usual invariant for joining a queue.
.. versionadded:: 3.13
diff --git a/Lib/asyncio/queues.py b/Lib/asyncio/queues.py
index 2f3865114a84f9..e5d6f2e4b61e17 100644
--- a/Lib/asyncio/queues.py
+++ b/Lib/asyncio/queues.py
@@ -227,9 +227,6 @@ def task_done(self):
been processed (meaning that a task_done() call was received for every
item that had been put() into the queue).
- shutdown(immediate=True) calls task_done() for each remaining item in
- the queue.
-
Raises ValueError if called more times than there were items placed in
the queue.
"""
@@ -257,8 +254,8 @@ def shutdown(self, immediate=False):
'immediate' to True to make gets raise immediately instead.
All blocked callers of put() and get() will be unblocked. If
- 'immediate', a task is marked as done for each item remaining in
- the queue, which may unblock callers of join().
+ 'immediate', unblock callers of join() regardless of the
+ number of unfinished tasks.
"""
self._is_shutdown = True
if immediate:
diff --git a/Lib/queue.py b/Lib/queue.py
index 25beb46e30d6bd..c90de8edc76c34 100644
--- a/Lib/queue.py
+++ b/Lib/queue.py
@@ -80,9 +80,6 @@ def task_done(self):
have been processed (meaning that a task_done() call was received
for every item that had been put() into the queue).
- shutdown(immediate=True) calls task_done() for each remaining item in
- the queue.
-
Raises a ValueError if called more times than there were items
placed in the queue.
'''
@@ -240,8 +237,8 @@ def shutdown(self, immediate=False):
'immediate' to True to make gets raise immediately instead.
All blocked callers of put() and get() will be unblocked. If
- 'immediate', a task is marked as done for each item remaining in
- the queue, which may unblock callers of join().
+ 'immediate', callers of join() are unblocked regardless of
+ the number of unfinished tasks.
'''
with self.mutex:
self.is_shutdown = True
pFad - Phonifier reborn
Pfad - The Proxy pFad of © 2024 Garber Painting. All rights reserved.
Note: This service is not intended for secure transactions such as banking, social media, email, or purchasing. Use at your own risk. We assume no liability whatsoever for broken pages.
Alternative Proxies:
Alternative Proxy
pFad Proxy
pFad v3 Proxy
pFad v4 Proxy