docs: ob_mutex should only be used with the critical section API #125053

The ob_mutex field in the experimental free threading build should only be used by the critical section API. It should not be locked directly (i.e., no PyMutex_Lock(&obj->ob_mutex)).

It's not safe to lock the same mutex using the critical section API and the plain mutex API because it may deadlock. Even if you never use the critical section API on instances of your type, it's possible that other code uses the critical section API on generic Python objects.

PyMutex objects are cheap -- just add a new one to your object if necessary.

We should document this somewhere.

Linked PRs

• gh-125053: Document that ob_mutex must only be used via critical section API #144599