From 6691a23bf5519dcae5264ec1d89da96b3ab8a14d Mon Sep 17 00:00:00 2001 From: Raymond Hettinger Date: Thu, 24 Jul 2025 14:35:21 -0600 Subject: [PATCH 1/2] Join only unblocks with zero unfinished tasks --- Doc/library/asyncio-queue.rst | 7 ++++--- Doc/library/queue.rst | 7 ++++--- 2 files changed, 8 insertions(+), 6 deletions(-) diff --git a/Doc/library/asyncio-queue.rst b/Doc/library/asyncio-queue.rst index 963bc1fb82c12f..d481a1921d532b 100644 --- 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 6dcf06aab00295..1b75582f0cf45b 100644 --- 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. From 5f7ae25e7f1f6ea7f6d4b368e377c7ac3daa88dc Mon Sep 17 00:00:00 2001 From: Raymond Hettinger Date: Thu, 24 Jul 2025 14:58:50 -0600 Subject: [PATCH 2/2] Update docstrings as well --- Lib/asyncio/queues.py | 8 +++++--- Lib/queue.py | 8 +++++--- 2 files changed, 10 insertions(+), 6 deletions(-) diff --git a/Lib/asyncio/queues.py b/Lib/asyncio/queues.py index e5d6f2e4b61e17..084fccaaff2ff7 100644 --- a/Lib/asyncio/queues.py +++ b/Lib/asyncio/queues.py @@ -253,9 +253,11 @@ def shutdown(self, immediate=False): 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 c90de8edc76c34..c0b359876543f7 100644 --- a/Lib/queue.py +++ b/Lib/queue.py @@ -236,9 +236,11 @@ def shutdown(self, immediate=False): 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