From ea06ae5b5e7b335efbdff03c087fad9980a53f69 Mon Sep 17 00:00:00 2001 From: Raymond Hettinger Date: Fri, 25 Jul 2025 07:56:28 -0600 Subject: [PATCH] Fix Queue.shutdown docs for condition to unblock a join (gh-137088) --- Doc/library/asyncio-queue.rst | 7 ++++--- Doc/library/queue.rst | 7 ++++--- Lib/asyncio/queues.py | 8 +++++--- Lib/queue.py | 8 +++++--- 4 files changed, 18 insertions(+), 12 deletions(-) diff --git a/Doc/library/asyncio-queue.rst b/Doc/library/asyncio-queue.rst index 963bc1fb82c1..d481a1921d53 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 6dcf06aab002..1b75582f0cf4 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. diff --git a/Lib/asyncio/queues.py b/Lib/asyncio/queues.py index e5d6f2e4b61e..084fccaaff2f 100644 --- 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 c90de8edc76c..c0b359876543 100644 --- 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 -- 2.47.2