gh-96471: Correct docs for queue shutdown (#115838)

diff --git a/Doc/library/queue.rst b/Doc/library/queue.rst
index 1421fc2e552f0e3461f1873f5419081d9f85b287..f2a6dbf589fd872388cbef1762fe4ed468de9ea9 100644 (file)
--- a/Doc/library/queue.rst
+++ b/Doc/library/queue.rst
@@ -187,11 +187,12 @@ 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.
 
-   Raises :exc:`ShutDown` if the queue has been shut down immediately.
-
 
 .. method:: Queue.join()
 
@@ -202,8 +203,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.
 
-   Raises :exc:`ShutDown` if the queue has been shut down immediately.
-
 
 Example of how to wait for enqueued tasks to be completed::
 

diff --git a/Lib/queue.py b/Lib/queue.py
index 467ff4fcecb1340194bf474bbfc0fa5337ce351d..18fad8df08e46968d56323aebd2739a10a4e742b 100644 (file)
--- a/Lib/queue.py
+++ b/Lib/queue.py
@@ -72,10 +72,11 @@ 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.
-
-        Raises ShutDown if the queue has been shut down immediately.
         '''
         with self.all_tasks_done:
             unfinished = self.unfinished_tasks - 1
@@ -93,8 +94,6 @@ class Queue:
         to indicate the item was retrieved and all work on it is complete.
 
         When the count of unfinished tasks drops to zero, join() unblocks.
-
-        Raises ShutDown if the queue has been shut down immediately.
         '''
         with self.all_tasks_done:
             while self.unfinished_tasks:
@@ -227,18 +226,17 @@ class Queue:
         return self.get(block=False)
 
     def shutdown(self, immediate=False):
-        '''Shut-down the queue, making queue gets and puts raise.
+        '''Shut-down the queue, making queue gets and puts raise ShutDown.
 
         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'. The ShutDown exception is raised.
+        and join() if 'immediate'.
         '''
         with self.mutex:
             self.is_shutdown = True
             if immediate:
-                n_items = self._qsize()
                 while self._qsize():
                     self._get()
                     if self.unfinished_tasks > 0: