gh-96471: Correct documentation for asyncio queue shutdown (#117621)

diff --git a/Doc/library/asyncio-queue.rst b/Doc/library/asyncio-queue.rst
index 030d4310942d7af9d334519589a89feb70c7e32e..9b579cc1d5fdfe5a6fb51c243e6096aab11ec9a6 100644 (file)
--- a/Doc/library/asyncio-queue.rst
+++ b/Doc/library/asyncio-queue.rst
@@ -106,9 +106,10 @@ Queue
       raise once the queue is empty. Set *immediate* to true to make
       :meth:`~Queue.get` raise immediately instead.
 
-      All blocked callers of :meth:`~Queue.put` will be unblocked. If
-      *immediate* is true, also unblock callers of :meth:`~Queue.get`
-      and :meth:`~Queue.join`.
+      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`.
 
       .. versionadded:: 3.13
 

diff --git a/Doc/whatsnew/3.13.rst b/Doc/whatsnew/3.13.rst
index 9e40bf04c49bfa6f049d02f7e412f281ec28aee7..0fe2dafbfd6f023bac8675bc5bd7e3048cee1f10 100644 (file)
--- a/Doc/whatsnew/3.13.rst
+++ b/Doc/whatsnew/3.13.rst
@@ -298,7 +298,7 @@ asyncio
 
 * Add :meth:`asyncio.Queue.shutdown` (along with
   :exc:`asyncio.QueueShutDown`) for queue termination.
-  (Contributed by Laurie Opperman in :gh:`104228`.)
+  (Contributed by Laurie Opperman and Yves Duprat in :gh:`104228`.)
 
 base64
 ------

diff --git a/Lib/asyncio/queues.py b/Lib/asyncio/queues.py
index b8156704b8fc23622f5fafb8bd79a16ff96921c5..2f3865114a84f95eb29113b1efc015bc5db12551 100644 (file)
--- a/Lib/asyncio/queues.py
+++ b/Lib/asyncio/queues.py
@@ -256,8 +256,9 @@ class Queue(mixins._LoopBoundMixin):
         By default, gets will only raise once the queue is empty. Set
         'immediate' to True to make gets raise immediately instead.
 
-        All blocked callers of put() will be unblocked, and also get()
-        and join() if 'immediate'.
+        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().
         """
         self._is_shutdown = True
         if immediate:
@@ -267,6 +268,7 @@ class Queue(mixins._LoopBoundMixin):
                     self._unfinished_tasks -= 1
             if self._unfinished_tasks == 0:
                 self._finished.set()
+        # All getters need to re-check queue-empty to raise ShutDown
         while self._getters:
             getter = self._getters.popleft()
             if not getter.done():