gh-123619: Add an unstable C API function for enabling deferred reference counting

Doc/c-api/object.rst

@@ -575,3 +575,18 @@ Object Protocol
    has the :c:macro:`Py_TPFLAGS_MANAGED_DICT` flag set.
 
    .. versionadded:: 3.13
+
+.. c:function:: int PyUnstable_Object_SetDeferredRefcount(PyObject *obj)
+
+   Enable `deferred reference counting <https://peps.python.org/pep-0703/#deferred-reference-counting>`_ on *obj*.
+
+   *obj* must be an object tracked by the garbage collector (see :func:`gc.is_tracked`), must have been
+   created by the calling thread, and must not be in use by any existing threads.
+
+   If any of the above conditions are not met, this function returns a negative value
+   and sets an exception.
+
+   This function is a no-op on builds with the :term:`GIL` enabled.
+
+   .. versionadded:: 3.14
+

Include/cpython/object.h

@@ -526,3 +526,10 @@ typedef enum {
 typedef int (*PyRefTracer)(PyObject *, PyRefTracerEvent event, void *);
 PyAPI_FUNC(int) PyRefTracer_SetTracer(PyRefTracer tracer, void *data);
 PyAPI_FUNC(PyRefTracer) PyRefTracer_GetTracer(void**);
+
+/* Enable PEP-703 deferred reference counting on the object.
+ *
+ * If this is called on a build with the GIL enabled, this
+ * function does nothing.
+ */
+PyAPI_FUNC(int) PyUnstable_Object_SetDeferredRefcount(PyObject *);

Misc/NEWS.d/next/C_API/2024-09-03-13-33-33.gh-issue-123619.HhgUUI.rst

@@ -0,0 +1,2 @@
+Added the :c:func:`PyUnstable_Object_SetDeferredRefcount` function for
+enabling :pep:`703` deferred reference counting.

Objects/object.c

@@ -2482,6 +2482,37 @@ _PyObject_SetDeferredRefcount(PyObject *op)
 #endif
 }
 
+int
+PyUnstable_Object_SetDeferredRefcount(PyObject *op)
+{
+#ifdef Py_GIL_DISABLED
+    if (!PyType_IS_GC(Py_TYPE(op)))
+    {
+        PyErr_SetString(PyExc_TypeError,
+                     "object is not tracked by the garbage collector");
+        return -1;
+    }
+
+    if (!_Py_IsOwnedByCurrentThread(op))
+    {
+        PyErr_SetString(PyExc_ValueError,
+                        "object is not owned by this thread");
+        return -1;
+    }
+
+    if (op->ob_ref_shared != 0)
+    {
+        PyErr_SetString(PyExc_ValueError,
+                        "object is already in use by another thread");
+        return -1;
+    }
+
+    _PyObject_SET_GC_BITS(op, _PyGC_BITS_DEFERRED);
+    op->ob_ref_shared = _Py_REF_SHARED(_Py_REF_DEFERRED, 0);
+#endif
+    return 0;
+}
+
 void
 _Py_ResurrectReference(PyObject *op)
 {