Add Doc section in free-threaded ext howto for critical sections #132531
Conversation
nascheme
added
docs
There was a problem hiding this comment.
I think an example with a type that extends PyObject might help. Critical sections are a pretty natural thing to use when you're managing internal state on such an object, which the extension should have complete control over so the caveats of critical sections can be worked around.
| - For locking two objects simultaneously | ||
|
|
||
| These macros are no-ops in non-free-threaded builds, so they can be safely | ||
| added to code that needs to support both build types. |
There was a problem hiding this comment.
Maybe worth adding you can only lock one or two objects at a time, not three or more.
There was a problem hiding this comment.
That is mentioned lower down, in the "Important Considerations" section.
|
|
||
| * Critical sections operate on a per-object basis rather than globally | ||
|
|
||
| * Critical sections follow a stack discipline within each thread |
There was a problem hiding this comment.
I'm not sure what "follow a stack discipline" means
There was a problem hiding this comment.
I added the comment: the "begin" and "end" macros enforce this since they must be paired and within the same scope. Hopefully that makes it clear enough. I think in this context "stack discipline" means you can only push and pop critical sections, in LIFO fashion.
Since the critical section macros are intended to be used by extensions, it would be good to have more documentation about how they work. These docs are based on the comments in
Include/cpython/critical_section.hand my own reading of the source code.📚 Documentation preview 📚: https://cpython-previews--132531.org.readthedocs.build/