From 7ec656e13d75b589102c78ada8ccd9b60c58b095 Mon Sep 17 00:00:00 2001 From: mohsinm-dev Date: Sat, 8 Nov 2025 18:24:05 +0500 Subject: [PATCH] gh-141196: Fix threading.Semaphore documentation inconsistency The acquire() method documentation stated 'Exactly one thread will be awoken by each call to release()' which became incorrect when the n parameter was added to release() in Python 3.9. The release() method documentation was ambiguous about behavior when n > waiting_threads. Changes: - acquire(): Updated to reflect that release(n) wakes min(j,n) threads where j = waiting threads - release(): Clarified that it wakes 'up to n' threads, or all available if fewer than n are waiting The fix aligns documentation with actual implementation behavior in Lib/threading.py where release(n) calls Condition.notify(n). --- Doc/library/threading.rst | 11 +++++++---- 1 file changed, 7 insertions(+), 4 deletions(-) diff --git a/Doc/library/threading.rst b/Doc/library/threading.rst index 19cc4f191dff8d..b149a222115ec4 100644 --- a/Doc/library/threading.rst +++ b/Doc/library/threading.rst @@ -1144,9 +1144,11 @@ Semaphores also support the :ref:`context management protocol `. one and return ``True`` immediately. * If the internal counter is zero on entry, block until awoken by a call to :meth:`~Semaphore.release`. Once awoken (and the counter is greater - than 0), decrement the counter by 1 and return ``True``. Exactly one - thread will be awoken by each call to :meth:`~Semaphore.release`. The - order in which threads are awoken should not be relied on. + than 0), decrement the counter by 1 and return ``True``. Each call to + :meth:`~Semaphore.release` will wake up threads according to its *n* + parameter (default 1): if *j* threads are waiting and ``release(n)`` + is called, ``min(j, n)`` threads will be awoken. The order in which + threads are awoken should not be relied on. When invoked with *blocking* set to ``False``, do not block. If a call without an argument would block, return ``False`` immediately; otherwise, do @@ -1166,7 +1168,8 @@ Semaphores also support the :ref:`context management protocol `. Release a semaphore, incrementing the internal counter by *n*. When it was zero on entry and other threads are waiting for it to become larger - than zero again, wake up *n* of those threads. + than zero again, wake up to *n* of those threads (or all of them if + fewer than *n* are waiting). .. versionchanged:: 3.9 Added the *n* parameter to release multiple waiting threads at once.