[3.14] Fix docs for Queue.shutdown (gh-137028) (#137080)

Fix docs for Queue.shutdown (gh-137028)
(cherry picked from commit 245671555b)

Co-authored-by: Raymond Hettinger <rhettinger@users.noreply.github.com>
Co-authored-by: Zachary Ware <zach@python.org>
Co-authored-by: Serhiy Storchaka <storchaka@gmail.com>

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.
 

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.
 
-   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.
+   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.
 
-   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`.
+   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`.
+
+   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.
+
+   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
 

Lib/asyncio/queues.py

@@ -227,9 +227,6 @@ class Queue(mixins._LoopBoundMixin):
         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 @@ class Queue(mixins._LoopBoundMixin):
         '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:

Lib/queue.py

@@ -80,9 +80,6 @@ class Queue:
         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 @@ class Queue:
         '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