enhance docs for critical sections

[kumaraditya303]

---

📚 Documentation preview 📚: https://cpython-previews--137334.org.readthedocs.build/

[nascheme]

The other danger we might want to mention is what we have been calling "re-entrancy". That's not quite the accurate word for it since re-entrancy is only one type of problem of that kind. The more general problem is that you call a Python API and it ends up mutating state that you didn't expect to change. I.e. modifying "pre-conditions" your logic sequence is depending on. Also known as "changing things under you" or "spooky action at a distance".

In Python, there are many surprising ways this can happen. When I was working on thread-safety for typeobject.c, I discovered some that surprised me, even as a long-time Python user. A few examples:

• __hash__ methods on custom types that are used as dictionary keys
• comparison methods on custom types that somewhere get compared
• __getattr__ and __getattribute__ methods
• Py_DECREF(), due to finalizers

Using a critical section (kind of obviously) doesn't protect you from this kind of thing. Why would it when this same problem can happen even if you never have more than a single thread. If it did try to protect you then likely the program would deadlock.

I guess "potentially re-entrant" would be an okay description of this. I.e. if you call this API, it can basically do anything since it can start executing Python-level code (via a hash method, finalizer, etc). Then, it could very well re-enter the same function or method.

[kumaraditya303]

The other danger we might want to mention is what we have been calling "re-entrancy".

I have changed the wording now to just any calls to C API which covers this.

[miss-islington-app]

Thanks @kumaraditya303 for the PR 🌮🎉.. I'm working now to backport this PR to: 3.13, 3.14.
🐍🍒⛏🤖

[bedevere-app]

GH-138167 is a backport of this pull request to the 3.14 branch.

[bedevere-app]

GH-138168 is a backport of this pull request to the 3.13 branch.