gh-143300: implement PyUnstable_SetImmortal

[kumaraditya303]

• Issue: Add an unstable C API for immortalizing objects #143300

---

📚 Documentation preview 📚: https://cpython-previews--144543.org.readthedocs.build/

[ZeroIntensity]

I think we also need to document the guarantees regarding which objects may be made immortal. For example, the following results in an assertion failure:

from ctypes import pythonapi, py_object, c_int

set_immortal = pythonapi.PyUnstable_SetImmortal
set_immortal.argtypes = (py_object,)
set_immortal.restype = c_int

print(set_immortal("Hello world"))

[ZeroIntensity]

Looks pretty good.

Bikeshedding: Should this be named PyUnstable_Object_SetImmortal? The Py[Unstable]_ prefix is generally reserved for runtime operations (though it seems PyUnstable_TryIncRef didn't follow that rule).

[ZeroIntensity]

Up to you, but it's likely worth mentioning that this is useful for avoiding reference count contention.

[kumaraditya303]

Should this be named PyUnstable_Object_SetImmortal?

I'd like to keep it aligned with PyObject_IsImmortal and avoid introducing the Object in between.

[ZeroIntensity]

Oh, we also need to note that op will be GC-untracked if it's tracked.

[kumaraditya303]

Isn't it the same as never garbage collected?

[ZeroIntensity]

I don't think that's immediately clear. Something can be "never garbage collected" while still being GC-tracked without being immortal (such as with a reference leak). It'd be nice for users to know that they don't need to call PyObject_GC_UnTrack themselves.