René's URL Explorer Experiment

{"@context":"https://schema.org","@type":"DiscussionForumPosting","headline":"threading.Semaphore documentation is not internally consistent","articleBody":"# Documentation\n\n[threading.Semaphore](https://docs.python.org/3/library/threading.html#threading.Semaphore) has two methods, `acquire()` and `release()`.  The documentation for `acquire()` states:\n\n\u003e Exactly one thread will be awoken by each call to [release()](https://docs.python.org/3/library/threading.html#threading.Semaphore.release).\n\nThe documentation for `release()` states:\n\n\u003e 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.\n\nThese statements cannot both be true.  Which is correct?  Technically, I suspect... neither.  Though my guess is the latter is far closer to the truth.\n\nThe _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.\n\nHowever, 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.\n\nSomeone 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:\n\n\u003e If there are _j_ threads blocked on `acquire()`, and you call `release(n)`, release will wake up `min(j, n)` of those threads.\n\nIt might be nice to backport this change to all currently-supported versions, too.\n\n\u003c!-- gh-linked-prs --\u003e\n### Linked PRs\n* gh-141243\n* gh-141244\n\u003c!-- /gh-linked-prs --\u003e\n","author":{"url":"https://github.com/larryhastings","@type":"Person","name":"larryhastings"},"datePublished":"2025-11-07T13:57:18.000Z","interactionStatistic":{"@type":"InteractionCounter","interactionType":"https://schema.org/CommentAction","userInteractionCount":1},"url":"https://github.com/141196/cpython/issues/141196"}