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

Lee primero la implementación de threading.Semaphore y, después, compara las entradas de documentación de acquire() y release() enlazadas en el issue. Actualiza la documentación para que ambas descripciones coincidan de forma coherente con la implementación, incluido release(n) cuando haya menos hilos esperando, y verifica la redacción en la documentación de las versiones compatibles.