gh-125053: Document that ob_mutex must only be used via critical 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.

Author: overlorde

Doc/c-api/structures.rst

@@ -48,6 +48,22 @@ under :ref:`reference counting <countingrefs>`.
       Do not use this field directly; use :c:macro:`Py_TYPE` and
       :c:func:`Py_SET_TYPE` instead.
 
+   .. c:member:: PyMutex ob_mutex
+
+      A per-object lock, present only in the :term:`free-threaded <free threading>`
+      build (when :c:macro:`Py_GIL_DISABLED` is defined).
+
+      This field is **reserved for use by the critical section API**
+      (:c:macro:`Py_BEGIN_CRITICAL_SECTION` / :c:macro:`Py_END_CRITICAL_SECTION`).
+      Do **not** lock it directly with ``PyMutex_Lock``; doing so can cause
+      deadlocks.  If you need your own lock, add a separate :c:type:`PyMutex`
+      field to your object struct.
+
+      See :ref:`per-object-locks` in the free-threading extension guide for
+      details.
+
+      .. versionadded:: 3.13
+
 
 .. c:type:: PyVarObject
 

Doc/howto/free-threading-extensions.rst

@@ -384,6 +384,55 @@ Important Considerations
   internal extension state, standard mutexes or other synchronization
   primitives might be more appropriate.
 
+.. _per-object-locks:
+
+Per-Object Locks (``ob_mutex``)
+...............................
+
+In the free-threaded build, each Python object contains a :c:member:`~PyObject.ob_mutex`
+field of type :c:type:`PyMutex`.  This mutex is **reserved for use by the
+critical section API** (:c:macro:`Py_BEGIN_CRITICAL_SECTION` /
+:c:macro:`Py_END_CRITICAL_SECTION`).
+
+.. warning::
+
+   Do **not** lock ``ob_mutex`` directly with ``PyMutex_Lock(&obj->ob_mutex)``.
+   Mixing direct ``PyMutex_Lock`` calls with the critical section API on the
+   same mutex can cause deadlocks, because the critical section implementation
+   may suspend and release its locks when contention is detected.
+
+Even if your own code never uses critical sections on a particular object type,
+**CPython internals may use the critical section API on any Python object**.
+For example, the garbage collector or other interpreter internals may enter a
+critical section on your object.  If your code holds ``ob_mutex`` directly at
+that point, a deadlock can occur.
+
+If your extension type needs its own lock, add a separate :c:type:`PyMutex`
+field (or another synchronization primitive) to your object struct.
+: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 */
+    PyMutex_Lock(&obj->ob_mutex);
+    ...
+    PyMutex_Unlock(&obj->ob_mutex);
+
+    /* RIGHT — use critical sections for ob_mutex */
+    Py_BEGIN_CRITICAL_SECTION(obj);
+    ...
+    Py_END_CRITICAL_SECTION();
+
+    /* RIGHT — use your own mutex for your own state */
+    typedef struct {
+        PyObject_HEAD
+        PyMutex my_mutex;   /* separate lock for extension state */
+        int my_data;
+    } MyObject;
+
+    PyMutex_Lock(&self->my_mutex);
+    self->my_data++;
+    PyMutex_Unlock(&self->my_mutex);
+
 
 Building Extensions for the Free-Threaded Build
 ===============================================

notes/gh-125053-ob-mutex-warning.md

@@ -0,0 +1,71 @@
+# gh-125053: Document `ob_mutex` usage warning
+
+**Issue:** https://github.com/python/cpython/issues/125053
+**Branch:** `doc-ob-mutex-warning`
+
+## Summary
+
+Added documentation warning that `PyObject.ob_mutex` must only be used via the
+critical section API (`Py_BEGIN_CRITICAL_SECTION` / `Py_END_CRITICAL_SECTION`).
+Directly locking it with `PyMutex_Lock(&obj->ob_mutex)` can cause deadlocks
+because the critical section implementation may also lock the same mutex on any
+Python object. Extension authors who need their own lock should create a
+separate `PyMutex` field.
+
+## Files changed
+
+### 1. `Doc/howto/free-threading-extensions.rst`
+
+**Location:** New subsection "Per-Object Locks (`ob_mutex`)" added after
+"Important Considerations" (after line 385), within the existing "Critical
+Sections" section.
+
+**What was added (49 lines):**
+
+- RST label `.. _per-object-locks:` for cross-referencing
+- Explanation that `ob_mutex` is a per-object `PyMutex` present in the
+  free-threaded build, reserved for the critical section API
+- A `.. warning::` admonition against locking `ob_mutex` directly with
+  `PyMutex_Lock`, explaining the deadlock risk
+- Note that CPython internals may use the critical section API on *any* Python
+  object (e.g., garbage collector), so even types that don't use critical
+  sections themselves are affected
+- Recommendation to add a separate `PyMutex` field (only 1 byte) for
+  extension-specific locking needs
+- Code examples showing:
+  - **WRONG:** direct `PyMutex_Lock(&obj->ob_mutex)`
+  - **RIGHT:** `Py_BEGIN_CRITICAL_SECTION(obj)` / `Py_END_CRITICAL_SECTION()`
+  - **RIGHT:** defining a custom `PyMutex my_mutex` field on your type struct
+
+### 2. `Doc/c-api/structures.rst`
+
+**Location:** New `.. c:member:: PyMutex ob_mutex` entry under `PyObject`,
+after the `ob_type` member (after line 49).
+
+**What was added (16 lines):**
+
+- Member documentation stating `ob_mutex` is a per-object lock present only in
+  the free-threaded build (`Py_GIL_DISABLED`)
+- Warning that it is reserved for the critical section API and must not be
+  locked directly
+- Cross-reference to `:ref:`per-object-locks`` in the free-threading howto
+- `.. versionadded:: 3.13` directive
+
+## Verification against source code
+
+All claims were verified against the actual CPython C headers:
+
+| Claim | Verified at |
+|---|---|
+| `ob_mutex` is a `PyMutex` field on `PyObject` | `Include/object.h:162` |
+| Only present in free-threaded build (`Py_GIL_DISABLED`) | `Include/object.h:126,150` — two separate `_object` struct defs gated on `#elif !defined(Py_GIL_DISABLED)` / `#else` |
+| Critical sections lock `ob_mutex` | `Include/internal/pycore_critical_section.h:113` — `_PyCriticalSection_BeginMutex(tstate, c, &op->ob_mutex)` |
+| `PyMutex` is 1 byte | `Include/cpython/pylock.h:33-35` — `typedef struct PyMutex { uint8_t _bits; } PyMutex;` |
+| `ob_mutex` introduced in 3.13 | Commit `6dfb8fe0236` first appears in tag `v3.13.0a2` |
+| Deadlock risk from mixing direct lock with critical sections | Critical section design suspends/releases its locks on contention (`Include/cpython/critical_section.h:22-25`), but a direct `PyMutex_Lock` holder does not participate in this protocol |
+
+## Build verification
+
+- `make html` in `Doc/` completed with **no warnings or errors**
+- `ob_mutex` appears in both generated HTML pages
+- Cross-reference from `structures.html` to `free-threading-extensions.html#per-object-locks` renders correctly