gh-125053: Document that ob_mutex must only be used via critical section API #144599
+44
−0
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
|
All commit authors signed the Contributor License Agreement. |
bedevere-app
bot
added
awaiting review
docs
overlorde
force-pushed
the
doc-ob-mutex-warning
branch
from
0d37059 to
c1f0568
Compare
…l section API Add a warning in the free-threading extensions howto explaining that PyObject.ob_mutex is reserved for the critical section API and must not be locked directly with PyMutex_Lock, as this can cause deadlocks. Extension authors who need their own lock should add a separate PyMutex field to their object struct. Also add an ob_mutex member entry under PyObject in the C API reference (Doc/c-api/structures.rst) with a cross-reference to the howto.
overlorde
force-pushed
the
doc-ob-mutex-warning
branch
from
c1f0568 to
8c202f0
Compare
Author
|
Hello, hope this works, claiming this issue. Thanks! |
| :c:type:`PyMutex` is very lightweight — it is only one byte — so there is | ||
| negligible cost to having an additional one:: | ||
|
|
||
| /* WRONG — do not lock ob_mutex directly */ |
Contributor
There was a problem hiding this comment.
I don't think the example is needed, the explanation text seems sufficient.
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Summary
ob_mutex)" subsection to the free-threading extensions howto (Doc/howto/free-threading-extensions.rst) warning thatob_mutexis reserved for the critical section API and must not be locked directly withPyMutex_Lockob_mutexmember entry underPyObjectin the C API reference (Doc/c-api/structures.rst) with a cross-reference to the howtoInclude code examples showing wrong (direct lock) vs. right (critical section or separate mutex) approachesCloses #125053
Test plan
make htmlinDoc/builds with no warningsstructures.htmltofree-threading-extensions.html#per-object-locksrenders correctlyInclude/object.h,Include/cpython/pylock.h,Include/internal/pycore_critical_section.h)ob_mutexshould only be used with the critical section API #125053📚 Documentation preview 📚: https://cpython-previews--144599.org.readthedocs.build/