Stowage/cpython
2
0
Fork 0
mirror of https://github.com/python/cpython.git synced 2026-01-06 15:32:22 +00:00
Code Issues Projects Releases Packages Wiki Activity

gh-107073: Make PyObject_VisitManagedDict() public (#108763)

Browse source 
Make PyObject_VisitManagedDict() and PyObject_ClearManagedDict()
functions public in Python 3.13 C API.

* Rename _PyObject_VisitManagedDict() to PyObject_VisitManagedDict().
* Rename _PyObject_ClearManagedDict() to PyObject_ClearManagedDict().
* Document these functions.
This commit is contained in:
Victor Stinner 2023-10-02 19:24:08 +02:00 • committed by GitHub
parent 6387b5313c
commit fc2cb86d21
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
12 changed files with 77 additions and 24 deletions
Download patch file Download diff file Expand all files Collapse all files

18
Doc/c-api/object.rst
View file

@ -489,3 +489,21 @@ Object Protocol
:c:macro:`Py_TPFLAGS_ITEMS_AT_END` set.
.. versionadded:: 3.12
.. c:function:: int PyObject_VisitManagedDict(PyObject *obj, visitproc visit, void *arg)
Visit the managed dictionary of *obj*.
This function must only be called in a traverse function of the type which
has the :c:macro:`Py_TPFLAGS_MANAGED_DICT` flag set.
.. versionadded:: 3.13
.. c:function:: void PyObject_ClearManagedDict(PyObject *obj)
Clear the managed dictionary of *obj*.
This function must only be called in a traverse function of the type which
has the :c:macro:`Py_TPFLAGS_MANAGED_DICT` flag set.
.. versionadded:: 3.13

28
Doc/c-api/typeobj.rst
View file

@ -1131,6 +1131,9 @@ and :c:data:`PyType_Type` effectively act as defaults.)
If this flag is set, :c:macro:`Py_TPFLAGS_HAVE_GC` should also be set.
The type traverse function must call :c:func:`PyObject_VisitManagedDict`
and its clear function must call :c:func:`PyObject_ClearManagedDict`.
.. versionadded:: 3.12
**Inheritance:**
@ -1368,6 +1371,23 @@ and :c:data:`PyType_Type` effectively act as defaults.)
debugging aid you may want to visit it anyway just so the :mod:`gc` module's
:func:`~gc.get_referents` function will include it.
Heap types (:c:macro:`Py_TPFLAGS_HEAPTYPE`) must visit their type with::
Py_VISIT(Py_TYPE(self));
It is only needed since Python 3.9. To support Python 3.8 and older, this
line must be conditionnal::
#if PY_VERSION_HEX >= 0x03090000
Py_VISIT(Py_TYPE(self));
#endif
If the :c:macro:`Py_TPFLAGS_MANAGED_DICT` bit is set in the
:c:member:`~PyTypeObject.tp_flags` field, the traverse function must call
:c:func:`PyObject_VisitManagedDict` like this::
PyObject_VisitManagedDict((PyObject*)self, visit, arg);
.. warning::
When implementing :c:member:`~PyTypeObject.tp_traverse`, only the
members that the instance *owns* (by having :term:`strong references
@ -1451,6 +1471,12 @@ and :c:data:`PyType_Type` effectively act as defaults.)
so that *self* knows the contained object can no longer be used. The
:c:func:`Py_CLEAR` macro performs the operations in a safe order.
If the :c:macro:`Py_TPFLAGS_MANAGED_DICT` bit is set in the
:c:member:`~PyTypeObject.tp_flags` field, the traverse function must call
:c:func:`PyObject_ClearManagedDict` like this::
PyObject_ClearManagedDict((PyObject*)self);
Note that :c:member:`~PyTypeObject.tp_clear` is not *always* called
before an instance is deallocated. For example, when reference counting
is enough to determine that an object is no longer used, the cyclic garbage
@ -1801,7 +1827,7 @@ and :c:data:`PyType_Type` effectively act as defaults.)
field is ``NULL`` then no :attr:`~object.__dict__` gets created for instances.
If the :c:macro:`Py_TPFLAGS_MANAGED_DICT` bit is set in the
:c:member:`~PyTypeObject.tp_dict` field, then
:c:member:`~PyTypeObject.tp_flags` field, then
:c:member:`~PyTypeObject.tp_dictoffset` will be set to ``-1``, to indicate
that it is unsafe to use this field.