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

Trước tiên, hãy đọc phần triển khai threading.Semaphore, sau đó so sánh các mục tài liệu về acquire() và release() được liên kết trong issue. Cập nhật tài liệu để cả hai mô tả nhất quán với phần triển khai, bao gồm cả release(n) khi có ít thread đang chờ hơn, và kiểm tra cách diễn đạt trong tài liệu của các phiên bản được hỗ trợ.