diff --git a/Doc/c-api/object.rst b/Doc/c-api/object.rst index efad4d215b1986..0fd159f1eb87f8 100644 --- a/Doc/c-api/object.rst +++ b/Doc/c-api/object.rst @@ -737,3 +737,21 @@ Object Protocol caller must hold a :term:`strong reference` to *obj* when calling this. .. versionadded:: 3.14 + +.. c:function:: int PyUnstable_Object_IsUniquelyReferenced(PyObject *op) + + Determine if *op* only has one reference. + + On GIL-enabled builds, this function is equivalent to + :c:expr:`Py_REFCNT(op) == 1`. + + On a :term:`free threaded ` build, this checks if *op*'s + :term:`reference count` is equal to one and additionally checks if *op* + is only used by this thread. :c:expr:`Py_REFCNT(op) == 1` is **not** + thread-safe on free threaded builds; prefer this function. + + The caller must hold an :term:`attached thread state`, despite the fact + that this function doesn't call into the Python interpreter. This function + cannot fail. + + .. versionadded:: 3.14 diff --git a/Doc/c-api/refcounting.rst b/Doc/c-api/refcounting.rst index 83febcf70a5548..b23f016f9b0a06 100644 --- a/Doc/c-api/refcounting.rst +++ b/Doc/c-api/refcounting.rst @@ -23,7 +23,14 @@ of Python objects. Use the :c:func:`Py_SET_REFCNT()` function to set an object reference count. - See also the function :c:func:`PyUnstable_Object_IsUniqueReferencedTemporary()`. + .. note:: + + On :term:`free threaded ` builds of Python, returning 1 + isn't sufficient to determine if it's safe to treat *o* as having no + access by other threads. Use :c:func:`PyUnstable_Object_IsUniquelyReferenced` + for that instead. + + See also the function :c:func:`PyUnstable_Object_IsUniqueReferencedTemporary()`. .. versionchanged:: 3.10 :c:func:`Py_REFCNT()` is changed to the inline static function. diff --git a/Doc/whatsnew/3.14.rst b/Doc/whatsnew/3.14.rst index 4b5515900cad41..56145b386b2a0e 100644 --- a/Doc/whatsnew/3.14.rst +++ b/Doc/whatsnew/3.14.rst @@ -2427,6 +2427,10 @@ New features be used in some cases as a replacement for checking if :c:func:`Py_REFCNT` is ``1`` for Python objects passed as arguments to C API functions. +* Add :c:func:`PyUnstable_Object_IsUniquelyReferenced` as a replacement for + ``Py_REFCNT(op) == 1`` on :term:`free threaded ` builds. + (Contributed by Peter Bierma in :gh:`133140`.) + Limited C API changes --------------------- diff --git a/Include/cpython/object.h b/Include/cpython/object.h index 3a4d65f7712c63..973d358ed8e4ec 100644 --- a/Include/cpython/object.h +++ b/Include/cpython/object.h @@ -489,3 +489,5 @@ PyAPI_FUNC(int) PyUnstable_IsImmortal(PyObject *); // before calling this function in order to avoid spurious failures. PyAPI_FUNC(int) PyUnstable_TryIncRef(PyObject *); PyAPI_FUNC(void) PyUnstable_EnableTryIncRef(PyObject *); + +PyAPI_FUNC(int) PyUnstable_Object_IsUniquelyReferenced(PyObject *); diff --git a/Lib/test/test_capi/test_object.py b/Lib/test/test_capi/test_object.py index 54a01ac7c4a7ae..127862546b1bce 100644 --- a/Lib/test/test_capi/test_object.py +++ b/Lib/test/test_capi/test_object.py @@ -174,6 +174,16 @@ def silly_func(obj): self.assertTrue(_testinternalcapi.has_deferred_refcount(silly_list)) +class IsUniquelyReferencedTest(unittest.TestCase): + """Test PyUnstable_Object_IsUniquelyReferenced""" + def test_is_uniquely_referenced(self): + self.assertTrue(_testcapi.is_uniquely_referenced(object())) + self.assertTrue(_testcapi.is_uniquely_referenced([])) + # Immortals + self.assertFalse(_testcapi.is_uniquely_referenced("spanish inquisition")) + self.assertFalse(_testcapi.is_uniquely_referenced(42)) + # CRASHES is_uniquely_referenced(NULL) + class CAPITest(unittest.TestCase): def check_negative_refcount(self, code): # bpo-35059: Check that Py_DECREF() reports the correct filename diff --git a/Misc/NEWS.d/next/C_API/2025-04-29-06-27-46.gh-issue-133140.IPGGc3.rst b/Misc/NEWS.d/next/C_API/2025-04-29-06-27-46.gh-issue-133140.IPGGc3.rst new file mode 100644 index 00000000000000..f73b7de2b5c7c2 --- /dev/null +++ b/Misc/NEWS.d/next/C_API/2025-04-29-06-27-46.gh-issue-133140.IPGGc3.rst @@ -0,0 +1,3 @@ +Add :c:func:`PyUnstable_Object_IsUniquelyReferenced` as a replacement for +``Py_REFNCT(op) == 1`` on :term:`free threaded ` +builds of Python. diff --git a/Modules/_testcapi/object.c b/Modules/_testcapi/object.c index 5c67adfee29dc1..798ef97c495aeb 100644 --- a/Modules/_testcapi/object.c +++ b/Modules/_testcapi/object.c @@ -478,6 +478,13 @@ clear_managed_dict(PyObject *self, PyObject *obj) } +static PyObject * +is_uniquely_referenced(PyObject *self, PyObject *op) +{ + return PyBool_FromLong(PyUnstable_Object_IsUniquelyReferenced(op)); +} + + static PyMethodDef test_methods[] = { {"call_pyobject_print", call_pyobject_print, METH_VARARGS}, {"pyobject_print_null", pyobject_print_null, METH_VARARGS}, @@ -503,6 +510,7 @@ static PyMethodDef test_methods[] = { {"test_py_is_macros", test_py_is_macros, METH_NOARGS}, {"test_py_is_funcs", test_py_is_funcs, METH_NOARGS}, {"clear_managed_dict", clear_managed_dict, METH_O, NULL}, + {"is_uniquely_referenced", is_uniquely_referenced, METH_O}, {NULL}, }; diff --git a/Objects/object.c b/Objects/object.c index 0974a231ec101a..ecf1500af2f00c 100644 --- a/Objects/object.c +++ b/Objects/object.c @@ -3249,3 +3249,11 @@ PyUnstable_IsImmortal(PyObject *op) assert(op != NULL); return _Py_IsImmortal(op); } + +int +PyUnstable_Object_IsUniquelyReferenced(PyObject *op) +{ + _Py_AssertHoldsTstate(); + assert(op != NULL); + return _PyObject_IsUniquelyReferenced(op); +}