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() のドキュメント項目を比較してください。両方の説明が実装と一貫して一致するようにドキュメントを更新し、待機中のスレッドが少ない場合の release(n) も含めて、サポート対象バージョンのドキュメント全体で文言を確認してください。