threading.Semaphore documentation is not internally consistent

[larryhastings]

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-141196: Fix threading.Semaphore documentation inconsistency #141243
• gh-141196: Fix threading.Semaphore documentation inconsistency #141244

[duaneg]

Someone should read the implementation of threading.Semaphore [and] figure out what its behavior actually is

Certainly: threading.Semaphore delegates to threading.Condition, which does as you say.