Feb 11, 2026 · Feb 6, 2026 · Feb 6, 2026 · Feb 7, 2026 · Feb 10, 2026 · Feb 10, 2026
diff --git a/Doc/c-api/object.rst b/Doc/c-api/object.rst
   cannot fail.

   .. versionadded:: 3.14

 .. c:function:: int PyUnstable_SetImmortal(PyObject *op)

   Marks the object *op* :term:`immortal`. The argument should be uniquely referenced by
   the calling thread. This is intended to be used for reducing reference counting contention
   in the :term:`free-threaded build` for objects which are shared across threads.

   This is a one-way process: objects can only be made immortal; they cannot be
   made mortal once again. Immortal objects do not participate in reference counting
   and will never be garbage collected. If the object is GC-tracked, it is untracked.

   This function is intended to be used soon after *op* is created, by the code that
   creates it, such as in the object's :c:member:`~PyTypeObject.tp_new` slot.
   Returns 1 if the object was made immortal and returns 0 if it was not.
   This function cannot fail.

   .. versionadded:: next
diff --git a/Include/cpython/object.h b/Include/cpython/object.h
 PyAPI_FUNC(void) PyUnstable_EnableTryIncRef(PyObject *);

 PyAPI_FUNC(int) PyUnstable_Object_IsUniquelyReferenced(PyObject *);

 PyAPI_FUNC(int) PyUnstable_SetImmortal(PyObject *op);
diff --git a/Misc/NEWS.d/next/Core_and_Builtins/2026-02-11-13-30-11.gh-issue-143300.yjB63-.rst b/Misc/NEWS.d/next/Core_and_Builtins/2026-02-11-13-30-11.gh-issue-143300.yjB63-.rst
 Add :c:func:`PyUnstable_SetImmortal` C-API function to mark objects as :term:`immortal`.
diff --git a/Modules/_testcapi/object.c b/Modules/_testcapi/object.c
    Py_RETURN_NONE;
 }

 static PyObject *
 test_py_set_immortal(PyObject *self, PyObject *unused)
 {
    // the object is allocated on C stack as otherwise,
    // it would trip the refleak checker when the object
    // is made immortal and leak memory, for the same
    // reason we cannot call PyObject_Init() on it.
    PyObject object = {0};
 #ifdef Py_GIL_DISABLED
    object.ob_tid = _Py_ThreadId();
    object.ob_gc_bits = 0;
    object.ob_ref_local = 1;
    object.ob_ref_shared = 0;
 #else
    object.ob_refcnt = 1;
 #endif
    object.ob_type = &PyBaseObject_Type;

    assert(!PyUnstable_IsImmortal(&object));
    int rc = PyUnstable_SetImmortal(&object);
    assert(rc == 1);
    assert(PyUnstable_IsImmortal(&object));
    Py_DECREF(&object);  // should not dealloc
    assert(PyUnstable_IsImmortal(&object));

    // Check already immortal object
    rc = PyUnstable_SetImmortal(&object);
    assert(rc == 0);

    // Check unicode objects
    PyObject *unicode = PyUnicode_FromString("test");
    assert(!PyUnstable_IsImmortal(unicode));
    rc = PyUnstable_SetImmortal(unicode);
    assert(rc == 0);
    assert(!PyUnstable_IsImmortal(unicode));
    Py_DECREF(unicode);
    Py_RETURN_NONE;
 }

 static PyObject *
 _test_incref(PyObject *ob)
    {"pyobject_is_unique_temporary", pyobject_is_unique_temporary, METH_O},
    {"pyobject_is_unique_temporary_new_object", pyobject_is_unique_temporary_new_object, METH_NOARGS},
    {"test_py_try_inc_ref", test_py_try_inc_ref, METH_NOARGS},
    {"test_py_set_immortal", test_py_set_immortal, METH_NOARGS},
    {"test_xincref_doesnt_leak",test_xincref_doesnt_leak,        METH_NOARGS},
    {"test_incref_doesnt_leak", test_incref_doesnt_leak,         METH_NOARGS},
    {"test_xdecref_doesnt_leak",test_xdecref_doesnt_leak,        METH_NOARGS},
diff --git a/Objects/object.c b/Objects/object.c
 #endif
 }

 int
 PyUnstable_SetImmortal(PyObject *op)
 {
    assert(op != NULL);
    if (!_PyObject_IsUniquelyReferenced(op) || PyUnicode_Check(op)) {
        return 0;
    }
    _Py_SetImmortal(op);
    return 1;
 }

 void
 _Py_ResurrectReference(PyObject *op)
 {
Original file line number	Diff line number	Diff line change
Expand Up		@@ -801,3 +801,20 @@ Object Protocol
		cannot fail.

		.. versionadded:: 3.14

		.. c:function:: int PyUnstable_SetImmortal(PyObject *op)

		Marks the object op :term:`immortal`. The argument should be uniquely referenced by
		the calling thread. This is intended to be used for reducing reference counting contention
		in the :term:`free-threaded build` for objects which are shared across threads.

		This is a one-way process: objects can only be made immortal; they cannot be
		made mortal once again. Immortal objects do not participate in reference counting
		and will never be garbage collected. If the object is GC-tracked, it is untracked.

		This function is intended to be used soon after op is created, by the code that
		creates it, such as in the object's :c:member:`~PyTypeObject.tp_new` slot.
		Returns 1 if the object was made immortal and returns 0 if it was not.
		This function cannot fail.

kumaraditya303 marked this conversation as resolved. Show resolvedHide resolved
		.. versionadded:: next
Original file line number	Diff line number	Diff line change
Expand Up		@@ -493,3 +493,5 @@ PyAPI_FUNC(int) PyUnstable_TryIncRef(PyObject *);
		PyAPI_FUNC(void) PyUnstable_EnableTryIncRef(PyObject *);

		PyAPI_FUNC(int) PyUnstable_Object_IsUniquelyReferenced(PyObject *);

		PyAPI_FUNC(int) PyUnstable_SetImmortal(PyObject *op);
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1 @@
		Add :c:func:`PyUnstable_SetImmortal` C-API function to mark objects as :term:`immortal`.
Original file line number	Diff line number	Diff line change
Expand Up		@@ -201,6 +201,44 @@ test_py_try_inc_ref(PyObject self, PyObject unused)
		Py_RETURN_NONE;
		}

		static PyObject *
		test_py_set_immortal(PyObject self, PyObject unused)
		{
		// the object is allocated on C stack as otherwise,
		// it would trip the refleak checker when the object
		// is made immortal and leak memory, for the same
		// reason we cannot call PyObject_Init() on it.
		PyObject object = {0};
		#ifdef Py_GIL_DISABLED
		object.ob_tid = _Py_ThreadId();
		object.ob_gc_bits = 0;
		object.ob_ref_local = 1;
		object.ob_ref_shared = 0;
		#else
		object.ob_refcnt = 1;
		#endif
		object.ob_type = &PyBaseObject_Type;

		assert(!PyUnstable_IsImmortal(&object));
		int rc = PyUnstable_SetImmortal(&object);
		assert(rc == 1);
		assert(PyUnstable_IsImmortal(&object));
		Py_DECREF(&object); // should not dealloc
		assert(PyUnstable_IsImmortal(&object));

		// Check already immortal object
		rc = PyUnstable_SetImmortal(&object);
		assert(rc == 0);

		// Check unicode objects
		PyObject *unicode = PyUnicode_FromString("test");
		assert(!PyUnstable_IsImmortal(unicode));
		rc = PyUnstable_SetImmortal(unicode);
		assert(rc == 0);
		assert(!PyUnstable_IsImmortal(unicode));
		Py_DECREF(unicode);
		Py_RETURN_NONE;
		}

		static PyObject *
		_test_incref(PyObject *ob)
Expand DownExpand Up		@@ -528,6 +566,7 @@ static PyMethodDef test_methods[] = {
		{"pyobject_is_unique_temporary", pyobject_is_unique_temporary, METH_O},
		{"pyobject_is_unique_temporary_new_object", pyobject_is_unique_temporary_new_object, METH_NOARGS},
		{"test_py_try_inc_ref", test_py_try_inc_ref, METH_NOARGS},
		{"test_py_set_immortal", test_py_set_immortal, METH_NOARGS},
		{"test_xincref_doesnt_leak",test_xincref_doesnt_leak, METH_NOARGS},
		{"test_incref_doesnt_leak", test_incref_doesnt_leak, METH_NOARGS},
		{"test_xdecref_doesnt_leak",test_xdecref_doesnt_leak, METH_NOARGS},
Expand Down
Original file line number	Diff line number	Diff line change
Expand Up		@@ -2839,6 +2839,17 @@ PyUnstable_EnableTryIncRef(PyObject *op)
		#endif
		}

		int
		PyUnstable_SetImmortal(PyObject *op)
		{
kumaraditya303 marked this conversation as resolved. Show resolvedHide resolved
		assert(op != NULL);
		if (!_PyObject_IsUniquelyReferenced(op) \|\| PyUnicode_Check(op)) {
		return 0;
		}
		_Py_SetImmortal(op);
kumaraditya303 marked this conversation as resolved. Show resolvedHide resolved
		return 1;
		}

		void
		_Py_ResurrectReference(PyObject *op)
		{
Expand Down