gh-128844: Make _Py_TryIncref public as an unstable API.
#128926
Conversation
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.
| return _Py_TryIncref(op); | ||
| } | ||
|
|
||
| void |
There was a problem hiding this comment.
According to the documentation, it should return int type :)
c:function:: int PyUnstable_EnableTryIncRef(PyObject *obj)
or you should fix the docs.
There was a problem hiding this comment.
I changed the return type in the docs.
Doc/c-api/object.rst
Outdated
|
|
||
| .. versionadded:: 3.14 | ||
|
|
||
| .. c:function:: int PyUnstable_EnableTryIncRef(PyObject *obj) |
| } | ||
| Py_DECREF(op); // undo try-incref | ||
| Py_DECREF(op); // dealloc | ||
| assert(MyObject_dealloc_called == 1); |
There was a problem hiding this comment.
Can you reset the counter to 0 at the start of the function, so the function can be called multiple times?
Modules/_testcapi/object.c
Outdated
|
|
||
| PyUnstable_EnableTryIncRef(op); | ||
| #ifdef Py_GIL_DISABLED | ||
| // PyUnstable_EnableTryIncRef sets the shared flags to *at least* |
There was a problem hiding this comment.
This comment seems incomplete, can you elaborate it a bit more?
Doc/c-api/object.rst
Outdated
| This is intended as a building block for safely dealing with unowned | ||
| references without the overhead of creating a :c:type:`!PyWeakReference`. |
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
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
|
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: ***@***.***>
|
This exposes
_Py_TryIncrefasPyUnstable_TryIncref()and the helper function_PyObject_SetMaybeWeakrefasPyUnstable_EnableTryIncRef.These are helpers for dealing with unowned references in a safe way, particularly in the free threading build.
_Py_TryIncrefpublic as an unstable API asPyUnstable_TryIncref()#128844📚 Documentation preview 📚: https://cpython-previews--128926.org.readthedocs.build/en/128926/c-api/object.html#c.PyUnstable_TryIncRef