From c1bcb5db012e0aa0e24a869609385c379ac3190d Mon Sep 17 00:00:00 2001 From: Laurie O Date: Fri, 23 Feb 2024 12:02:01 +1000 Subject: [PATCH 1/4] Remove incorrect queue-shutdown doc --- Doc/library/queue.rst | 6 +----- Lib/queue.py | 10 +++------- 2 files changed, 4 insertions(+), 12 deletions(-) diff --git a/Doc/library/queue.rst b/Doc/library/queue.rst index 1421fc2e552f0e..76999726599ac9 100644 --- a/Doc/library/queue.rst +++ b/Doc/library/queue.rst @@ -188,9 +188,7 @@ fully processed by daemon consumer threads. that had been :meth:`put` into 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. + the queue, or after an immediate shutdown. .. method:: Queue.join() @@ -202,8 +200,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 467ff4fcecb134..ffc4c4cf77a579 100644 --- a/Lib/queue.py +++ b/Lib/queue.py @@ -73,9 +73,7 @@ def task_done(self): for every item that had been put() into 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. + placed in the queue, or after an immediate shutdown. ''' with self.all_tasks_done: unfinished = self.unfinished_tasks - 1 @@ -93,8 +91,6 @@ def join(self): 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,13 +223,13 @@ def get_nowait(self): 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 From 100b64f6feea59f61a787263fe2fb50b9f4efb8a Mon Sep 17 00:00:00 2001 From: Laurie O Date: Sun, 25 Feb 2024 14:42:52 +1000 Subject: [PATCH 2/4] Remove unnecessary q-size get --- Lib/queue.py | 1 - 1 file changed, 1 deletion(-) diff --git a/Lib/queue.py b/Lib/queue.py index ffc4c4cf77a579..55cf2d737be716 100644 --- a/Lib/queue.py +++ b/Lib/queue.py @@ -234,7 +234,6 @@ def shutdown(self, immediate=False): with self.mutex: self.is_shutdown = True if immediate: - n_items = self._qsize() while self._qsize(): self._get() if self.unfinished_tasks > 0: From 6bab995afcd2e19ab6b3e7a64c7f12386cff3784 Mon Sep 17 00:00:00 2001 From: Laurie O Date: Sun, 25 Feb 2024 14:48:01 +1000 Subject: [PATCH 3/4] Precise documentation for task_done on shutdown --- Doc/library/queue.rst | 5 ++++- Lib/queue.py | 5 ++++- 2 files changed, 8 insertions(+), 2 deletions(-) diff --git a/Doc/library/queue.rst b/Doc/library/queue.rst index 76999726599ac9..0a93eb12f2ee03 100644 --- a/Doc/library/queue.rst +++ b/Doc/library/queue.rst @@ -187,8 +187,11 @@ 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). + :meth:`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, or after an immediate shutdown. + the queue. .. method:: Queue.join() diff --git a/Lib/queue.py b/Lib/queue.py index 55cf2d737be716..18fad8df08e469 100644 --- a/Lib/queue.py +++ b/Lib/queue.py @@ -72,8 +72,11 @@ 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, or after an immediate shutdown. + placed in the queue. ''' with self.all_tasks_done: unfinished = self.unfinished_tasks - 1 From 6c28c09ef7bea546c515765d8ee606e0da31a0f3 Mon Sep 17 00:00:00 2001 From: Guido van Rossum Date: Sun, 25 Feb 2024 08:30:16 -0800 Subject: [PATCH 4/4] Fix markup in Doc/library/queue.rst --- Doc/library/queue.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Doc/library/queue.rst b/Doc/library/queue.rst index 0a93eb12f2ee03..f2a6dbf589fd87 100644 --- a/Doc/library/queue.rst +++ b/Doc/library/queue.rst @@ -187,7 +187,7 @@ 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). - :meth:`shutdown(immediate=True)` calls :meth:`task_done` for each remaining item + ``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