diff --git a/pep-0630.rst b/pep-0630.rst index 27b4eb4e4a1..db1428fe23f 100644 --- a/pep-0630.rst +++ b/pep-0630.rst @@ -362,6 +362,46 @@ The class should generally be stored in *both* the module state (for safe access from C) and the module's ``__dict__`` (for access from Python code). + +Garbage Collection Protocol +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Instances of heap types hold a reference to their type. +This ensures that the type isn't destroyed before its instance, +but may result in reference cycles that need to be broken by the +garbage collector. + +To avoid memory leaks, instances of heap types must implement the +garbage collection protocol. +That is, heap types should: + +- Have the ``Py_TPFLAGS_HAVE_GC`` flag, +- Define a traverse function using ``Py_tp_traverse``, which + visits the type (e.g. using ``Py_VISIT(Py_TYPE(self));``). + +Please refer to the documentation of ``Py_TPFLAGS_HAVE_GC`` and +``tp_traverse`` for additional considerations. + +If your traverse function delegates to ``tp_traverse`` of its base class +(or another type), ensure that ``Py_TYPE(self)`` is visited only once. +Note that only heap type are expected to visit the type in ``tp_traverse``. + +For example, if your traverse function includes:: + + base->tp_traverse(self, visit, arg) + +...and ``base`` may be a static type, then it should also include:: + + if (base->tp_flags & Py_TPFLAGS_HEAPTYPE) { + // a heap type's tp_traverse already visited Py_TYPE(self) + } else { + Py_VISIT(Py_TYPE(self)); + } + +It is not necessary to handle the type's reference count in ``tp_new`` +and ``tp_clear``. + + Module State Access from Classes ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -494,6 +534,21 @@ module. C memory layout. +Lifetime of the Module State +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +When a module object is garbage-collected, its module state is freed. +For each pointer to (a part of) the module state, you must hold a reference +to the module object. + +Usually this is not an issue, because types created with +``PyType_FromModuleAndSpec``, and their instances, hold a reference +to the module. +However, you must be careful in reference counting when you reference +module state from other places, such as callbacks for external +libraries. + + Open Issues -----------