[3.14] Fix Queue.shutdown docs for condition to unblock a join (gh-137088) (#141073)

(cherry picked from commit ea06ae5b5e7b335efbdff03c087fad9980a53f69)

Co-authored-by: Raymond Hettinger <rhettinger@users.noreply.github.com>

diff --git a/Doc/library/asyncio-queue.rst b/Doc/library/asyncio-queue.rst
index 963bc1fb82c12f1b4e88a354a7ba6bca90d2ca63..d481a1921d532bbaa106cce62d16f419b1414a8d 100644 (file)
--- a/Doc/library/asyncio-queue.rst
+++ b/Doc/library/asyncio-queue.rst
@@ -120,9 +120,10 @@ Queue
       raise :exc:`QueueShutDown`.
 
       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`
+      The queue is drained to be completely empty and the count
+      of unfinished tasks is reduced by the number of tasks drained.
+      If unfinished tasks is zero, callers of :meth:`~Queue.join`
+      are unblocked.  Also, blocked callers of :meth:`~Queue.get`
       are unblocked and will raise :exc:`QueueShutDown` because the
       queue is empty.
 

diff --git a/Doc/library/queue.rst b/Doc/library/queue.rst
index 6dcf06aab002955f4623b0ab123ec91c66712fe4..1b75582f0cf45b872ceee8044348fd0679bc4962 100644 (file)
--- a/Doc/library/queue.rst
+++ b/Doc/library/queue.rst
@@ -256,9 +256,10 @@ until empty or terminated immediately with a hard shutdown.
    raise :exc:`ShutDown`.
 
    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`
+   The queue is drained to be completely empty and the count
+   of unfinished tasks is reduced by the number of tasks drained.
+   If unfinished tasks is zero, callers of :meth:`~Queue.join`
+   are unblocked.  Also, blocked callers of :meth:`~Queue.get`
    are unblocked and will raise :exc:`ShutDown` because the
    queue is empty.
 

diff --git a/Lib/asyncio/queues.py b/Lib/asyncio/queues.py
index e5d6f2e4b61e174c7b2218373837c991dcf19965..084fccaaff2ff7cf7c33d6de230a6048f9836443 100644 (file)
--- a/Lib/asyncio/queues.py
+++ b/Lib/asyncio/queues.py
@@ -253,9 +253,11 @@ 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() and get() will be unblocked. If
-        'immediate', unblock callers of join() regardless of the
-        number of unfinished tasks.
+        All blocked callers of put() and get() will be unblocked.
+
+        If 'immediate', the queue is drained and unfinished tasks
+        is reduced by the number of drained tasks.  If unfinished tasks
+        is reduced to zero, callers of Queue.join are unblocked.
         """
         self._is_shutdown = True
         if immediate:

diff --git a/Lib/queue.py b/Lib/queue.py
index c90de8edc76c34b1d040ca3ce6591db414619aa2..c0b359876543f7b0159f7432c52ce667e56e4245 100644 (file)
--- a/Lib/queue.py
+++ b/Lib/queue.py
@@ -236,9 +236,11 @@ class Queue:
         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() and get() will be unblocked. If
-        'immediate', callers of join() are unblocked regardless of
-        the number of unfinished tasks.
+        All blocked callers of put() and get() will be unblocked.
+
+        If 'immediate', the queue is drained and unfinished tasks
+        is reduced by the number of drained tasks.  If unfinished tasks
+        is reduced to zero, callers of Queue.join are unblocked.
         '''
         with self.mutex:
             self.is_shutdown = True