From b275b8f34210bae2fc1e0af23515df5efe911c8e Mon Sep 17 00:00:00 2001 From: Peter Bierma Date: Mon, 5 May 2025 15:01:20 -0400 Subject: gh-133140: Add `PyUnstable_Object_IsUniquelyReferenced` for free-threading (#133144) --- Doc/c-api/object.rst | 18 ++++++++++++++++++ Doc/c-api/refcounting.rst | 9 ++++++++- Doc/whatsnew/3.14.rst | 4 ++++ Include/cpython/object.h | 2 ++ Lib/test/test_capi/test_object.py | 10 ++++++++++ .../2025-04-29-06-27-46.gh-issue-133140.IPGGc3.rst | 3 +++ Modules/_testcapi/object.c | 8 ++++++++ Objects/object.c | 8 ++++++++ 8 files changed, 61 insertions(+), 1 deletion(-) create mode 100644 Misc/NEWS.d/next/C_API/2025-04-29-06-27-46.gh-issue-133140.IPGGc3.rst diff --git a/Doc/c-api/object.rst b/Doc/c-api/object.rst index efad4d2..0fd159f 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 83febcf..b23f016 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 795403a..851611a 100644 --- a/Doc/whatsnew/3.14.rst +++ b/Doc/whatsnew/3.14.rst @@ -2469,6 +2469,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 818fc7d..36000c8 100644 --- a/Include/cpython/object.h +++ b/Include/cpython/object.h @@ -501,3 +501,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 54a01ac..1278625 100644 --- a/Lib/test/test_capi/test_object.py +++ b/Lib/test/test_capi/test_object.py @@ -174,6 +174,16 @@ class EnableDeferredRefcountingTest(unittest.TestCase): 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 0000000..f73b7de --- /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 5c67adf..798ef97 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 f5fe25e..e9a93f8 100644 --- a/Objects/object.c +++ b/Objects/object.c @@ -3275,3 +3275,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); +} -- cgit v0.12