threading.Semaphore documentation is not internally consistent

Documentation

threading.Semaphore has two methods, acquire() and release(). The documentation for acquire() states:

Exactly one thread will be awoken by each call to release().

The documentation for release() states:

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.

These statements cannot both be true. Which is correct? Technically, I suspect... neither. Though my guess is the latter is far closer to the truth.

The n parameter to release() was added in Python 3.9; before that development, the statement in acquire() would have been true. So I suspect the statement in the documentation for acquire() is simply old information, rendered obsolete by this new parameter.

However, the documentation for release() says it will wake up n threads. But what if fewer than n threads are waiting? It can't wake up threads that don't exist.

Someone should read the implementation of threading.Semaphore, figure out what its behavior actually is, and rewrite the documentation to accurately reflect that behavior. My suspicion is that this statement correctly describes its behavior:

If there are j threads blocked on acquire(), and you call release(n), release will wake up min(j, n) of those threads.

It might be nice to backport this change to all currently-supported versions, too.

Linked PRs

• gh-141243
• gh-141244

先阅读 threading.Semaphore 的实现，然后比较 issue 中链接的 acquire() 和 release() 文档条目。更新文档，使两处描述都与实现保持一致，包括等待中的线程少于 n 个时的 release(n) 行为，并核对受支持版本文档中的措辞。