gh-133164: Add `PyUnstable_Object_IsUniqueReferencedTemporary` C API … · python/cpython@f237953 · GitHub
Skip to content

Commit f237953

Browse files
colesburyeendebakptYhg1smpagemarkshannon
authored
gh-133164: Add PyUnstable_Object_IsUniqueReferencedTemporary C API (gh-133170)
After gh-130704, the interpreter replaces some uses of `LOAD_FAST` with `LOAD_FAST_BORROW` which avoid incref/decrefs by "borrowing" references on the interpreter stack when the bytecode compiler can determine that it's safe. This change broke some checks in C API extensions that relied on `Py_REFCNT()` of `1` to determine if it's safe to modify an object in-place. Objects may have a reference count of one, but still be referenced further up the interpreter stack due to borrowing of references. This provides a replacement function for those checks. `PyUnstable_Object_IsUniqueReferencedTemporary` is more conservative: it checks that the object has a reference count of one and that it exists as a unique strong reference in the interpreter's stack of temporary variables in the top most frame. See also: * numpy/numpy#28681 Co-authored-by: Pieter Eendebak <pieter.eendebak@gmail.com> Co-authored-by: T. Wouters <thomas@python.org> Co-authored-by: mpage <mpage@cs.stanford.edu> Co-authored-by: Mark Shannon <mark@hotpy.org> Co-authored-by: Victor Stinner <vstinner@python.org>
1 parent 4701ff9 commit f237953

8 files changed

Lines changed: 109 additions & 0 deletions

File tree

‎Doc/c-api/object.rst‎

Lines changed: 32 additions & 0 deletions

‎Doc/c-api/refcounting.rst‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -23,6 +23,8 @@ of Python objects.
2323
2424
Use the :c:func:`Py_SET_REFCNT()` function to set an object reference count.
2525
26+
See also the function :c:func:`PyUnstable_Object_IsUniqueReferencedTemporary()`.
27+
2628
.. versionchanged:: 3.10
2729
:c:func:`Py_REFCNT()` is changed to the inline static function.
2830

‎Doc/whatsnew/3.14.rst‎

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -89,6 +89,10 @@ If you encounter :exc:`NameError`\s or pickling errors coming out of
8989
:mod:`multiprocessing` or :mod:`concurrent.futures`, see the
9090
:ref:`forkserver restrictions <multiprocessing-programming-forkserver>`.
9191

92+
The interpreter avoids some reference count modifications internally when
93+
it's safe to do so. This can lead to different values returned from
94+
:func:`sys.getrefcount` and :c:func:`Py_REFCNT` compared to previous versions
95+
of Python. See :ref:`below <whatsnew314-refcount>` for details.
9296

9397
New features
9498
============
@@ -2215,6 +2219,11 @@ New features
22152219
take a C integer and produce a Python :class:`bool` object. (Contributed by
22162220
Pablo Galindo in :issue:`45325`.)
22172221

2222+
* Add :c:func:`PyUnstable_Object_IsUniqueReferencedTemporary` to determine if an object
2223+
is a unique temporary object on the interpreter's operand stack. This can
2224+
be used in some cases as a replacement for checking if :c:func:`Py_REFCNT`
2225+
is ``1`` for Python objects passed as arguments to C API functions.
2226+
22182227

22192228
Limited C API changes
22202229
---------------------
@@ -2249,6 +2258,17 @@ Porting to Python 3.14
22492258
a :exc:`UnicodeError` object.
22502259
(Contributed by Bénédikt Tran in :gh:`127691`.)
22512260

2261+
.. _whatsnew314-refcount:
2262+
2263+
* The interpreter internally avoids some reference count modifications when
2264+
loading objects onto the operands stack by :term:`borrowing <borrowed reference>`
2265+
references when possible. This can lead to smaller reference count values
2266+
compared to previous Python versions. C API extensions that checked
2267+
:c:func:`Py_REFCNT` of ``1`` to determine if an function argument is not
2268+
referenced by any other code should instead use
2269+
:c:func:`PyUnstable_Object_IsUniqueReferencedTemporary` as a safer replacement.
2270+
2271+
22522272
* Private functions promoted to public C APIs:
22532273

22542274
* ``_PyBytes_Join()``: :c:func:`PyBytes_Join`.

‎Include/cpython/object.h‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -476,6 +476,11 @@ PyAPI_FUNC(PyRefTracer) PyRefTracer_GetTracer(void**);
476476
*/
477477
PyAPI_FUNC(int) PyUnstable_Object_EnableDeferredRefcount(PyObject *);
478478

479+
/* Determine if the object exists as a unique temporary variable on the
480+
* topmost frame of the interpreter.
481+
*/
482+
PyAPI_FUNC(int) PyUnstable_Object_IsUniqueReferencedTemporary(PyObject *);
483+
479484
/* Check whether the object is immortal. This cannot fail. */
480485
PyAPI_FUNC(int) PyUnstable_IsImmortal(PyObject *);
481486

‎Lib/test/test_capi/test_object.py‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,5 @@
11
import enum
2+
import sys
23
import textwrap
34
import unittest
45
from test import support
@@ -223,5 +224,17 @@ def __del__(self):
223224
obj = MyObj()
224225
_testinternalcapi.incref_decref_delayed(obj)
225226

227+
def test_is_unique_temporary(self):
228+
self.assertTrue(_testcapi.pyobject_is_unique_temporary(object()))
229+
obj = object()
230+
self.assertFalse(_testcapi.pyobject_is_unique_temporary(obj))
231+
232+
def func(x):
233+
# This relies on the LOAD_FAST_BORROW optimization (gh-130704)
234+
self.assertEqual(sys.getrefcount(x), 1)
235+
self.assertFalse(_testcapi.pyobject_is_unique_temporary(x))
236+
237+
func(object())
238+
226239
if __name__ == "__main__":
227240
unittest.main()

‎Misc/NEWS.d/next/C_API/2025-04-29-19-39-16.gh-issue-133164.W-XTU7.rst‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
Add :c:func:`PyUnstable_Object_IsUniqueReferencedTemporary` function for
2+
determining if an object exists as a unique temporary variable on the
3+
interpreter's stack. This is a replacement for some cases where checking
4+
that :c:func:`Py_REFCNT` is one is no longer sufficient to determine if it's
5+
safe to modify a Python object in-place with no visible side effects.

‎Modules/_testcapi/object.c‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -131,6 +131,13 @@ pyobject_enable_deferred_refcount(PyObject *self, PyObject *obj)
131131
return PyLong_FromLong(result);
132132
}
133133

134+
static PyObject *
135+
pyobject_is_unique_temporary(PyObject *self, PyObject *obj)
136+
{
137+
int result = PyUnstable_Object_IsUniqueReferencedTemporary(obj);
138+
return PyLong_FromLong(result);
139+
}
140+
134141
static int MyObject_dealloc_called = 0;
135142

136143
static void
@@ -478,6 +485,7 @@ static PyMethodDef test_methods[] = {
478485
{"pyobject_print_os_error", pyobject_print_os_error, METH_VARARGS},
479486
{"pyobject_clear_weakrefs_no_callbacks", pyobject_clear_weakrefs_no_callbacks, METH_O},
480487
{"pyobject_enable_deferred_refcount", pyobject_enable_deferred_refcount, METH_O},
488+
{"pyobject_is_unique_temporary", pyobject_is_unique_temporary, METH_O},
481489
{"test_py_try_inc_ref", test_py_try_inc_ref, METH_NOARGS},
482490
{"test_xincref_doesnt_leak",test_xincref_doesnt_leak, METH_NOARGS},
483491
{"test_incref_doesnt_leak", test_incref_doesnt_leak, METH_NOARGS},

‎Objects/object.c‎

Lines changed: 24 additions & 0 deletions

0 commit comments

Comments
 (0)