gh-128844: Make _Py_TryIncref public as an unstable API.

[colesbury]

This exposes _Py_TryIncref as PyUnstable_TryIncref() and the helper function _PyObject_SetMaybeWeakref as PyUnstable_EnableTryIncRef.

These are helpers for dealing with unowned references in a safe way, particularly in the free threading build.

• Issue: Make _Py_TryIncref public as an unstable API as PyUnstable_TryIncref() #128844

---

📚 Documentation preview 📚: https://cpython-previews--128926.org.readthedocs.build/en/128926/c-api/object.html#c.PyUnstable_TryIncRef

[corona10]

Maybe void?

[vstinner]

LGTM. I just have a suggestion for the test.

[kumaraditya303]

This comment seems incomplete, can you elaborate it a bit more?

[kumaraditya303]

In C API docs the term borrowed reference is more common than unowned reference, can you use that?

There's a glossary entry for it so it can be linked to that.

[colesbury]

I'll update the term, but I don't love the use of "borrowed reference" here. This seems different to me than the typical use of "borrowed reference" -- there's not a particular reference that's borrowed here. It's more like a building block for weak reference like objects without using PyWeakReference.

cpython/Include/cpython/weakrefobject.h

Line 12 in d95ba9f

* Note that this is a stealth reference: wr_object's refcount is

[encukou]

Please don't merge yet, I'd like to try tweaking the docs wording, early next week

…

On January 18, 2025 6:57:08 AM GMT+01:00, Donghee Na ***@***.***> wrote: @corona10 approved this pull request. -- Reply to this email directly or view it on GitHub: #128926 (review) You are receiving this because your review was requested. Message ID: ***@***.***>

[encukou]

I think this should use weak reference, as a generic term. The “without the overhead” note implies that we don't mean the concrete PyWeakReference.
“Borrowed reference” has a specific meaning in CPython (in particular, obj of PyUnstable_TryIncRef is a borrowed reference).
“Unowned reference” would, IMO, need a definition.

I'd also warn that you typically need to control the deallocator (both TryIncRef and tp_dealloc need the same lock). Is that correct?

Suggested change

	This is intended as a building block for safely dealing with
	:term:`borrowed references <borrowed reference>` without the overhead of
	creating a :c:type:`!PyWeakReference`.
	This is intended as a building block for managing weak references without the overhead of
	creating a :c:type:`!PyWeakReference`.
	Typically, correct use of this function requires support from *obj*'s
	deallocator (:c:member:`~PyTypeObject.tp_dealloc`).

---

Here is a larger change, with an example adapted from the issue (itself based on pybind11). I personally didn't “get” the function before seeing the example, but I don't know if I'm the target audience. I'm also not sure if there are other use cases this doesn't cover.

[colesbury]

Thanks, I think this is better, especially with the example. I think we should also include the use of PyUnstable_EnableTryIncref in the example.

[encukou]

I've updated the branch.

[colesbury]

@encukou - would you please take another look at this when you get a chance?

[encukou]

Looks good, thank you!
One more nitpick.

[vstinner]

Congrats Sam! Honestly, this API is weird/surprising (trying to INCREF, hu?), but it looks useful for Free Threading. The doc is nice, thanks @encukou for the example.