From 8b55bc3f93a655bc803bff79725d5fe3f124e2f0 Mon Sep 17 00:00:00 2001 From: Pablo Galindo Date: Sat, 29 May 2021 03:57:39 +0100 Subject: bpo-44263: Better explain the GC contract for PyType_FromSpecWithBases (GH-26442) --- Doc/c-api/gcsupport.rst | 11 +++++++++++ Doc/c-api/type.rst | 7 +++++++ 2 files changed, 18 insertions(+) diff --git a/Doc/c-api/gcsupport.rst b/Doc/c-api/gcsupport.rst index 55ed9d4..338365b 100644 --- a/Doc/c-api/gcsupport.rst +++ b/Doc/c-api/gcsupport.rst @@ -33,6 +33,17 @@ Constructors for container types must conform to two rules: #. Once all the fields which may contain references to other containers are initialized, it must call :c:func:`PyObject_GC_Track`. + .. warning:: + If a type adds the Py_TPFLAGS_HAVE_GC, then it *must* implement at least + a :c:member:`~PyTypeObject.tp_traverse` handler or explicitly use one + from its subclass or subclasses. + + Some APIs like :c:func:`PyType_FromSpecWithBases` or + :c:func:`PyType_FromSpec` will automatically populate the + :c:member:`~PyTypeObject.tp_flags`, :c:member:`~PyTypeObject.tp_traverse` + and :c:member:`~PyTypeObject.tp_clear` fields if the type inherits from a + class that implements the garbage collector protocol and the child class + does *not* include the :const:`Py_TPFLAGS_HAVE_GC` flag. .. c:function:: TYPE* PyObject_GC_New(TYPE, PyTypeObject *type) diff --git a/Doc/c-api/type.rst b/Doc/c-api/type.rst index bdb636d..9d24f39 100644 --- a/Doc/c-api/type.rst +++ b/Doc/c-api/type.rst @@ -169,6 +169,13 @@ The following functions and structs are used to create The associated module is not inherited by subclasses; it must be specified for each class individually. + If some of the bases in *bases* implements the GC protocol and the type being + created does not include the :const:`Py_TPFLAGS_HAVE_GC` in the flags included in + *spec*, then the GC protocol will be automatically implemented from its parents. On + the contrary, if the type being created does include :const:`Py_TPFLAGS_HAVE_GC` in + its flags then it *must* implement the GC protocol itself by at least including a slot + for :c:member:`~PyTypeObject.tp_traverse` in *spec*. + This function calls :c:func:`PyType_Ready` on the new type. .. versionadded:: 3.9 -- cgit v0.12