Note that tp_clear and m_clear are not always called (GH-27581)

diff --git a/Doc/c-api/module.rst b/Doc/c-api/module.rst
index a2541afb685c30e2142cc728a6161a9b4c24f9da..94c8d9f981713f820eb502253d90e9eb4c080668 100644 (file)
--- a/Doc/c-api/module.rst
+++ b/Doc/c-api/module.rst
@@ -221,6 +221,12 @@ or request "multi-phase initialization" by returning the definition struct itsel
       than 0 and the module state (as returned by :c:func:`PyModule_GetState`)
       is ``NULL``.
 
+      Like :c:member:`PyTypeObject.tp_clear`, this function is not *always*
+      called before a module is deallocated. For example, when reference
+      counting is enough to determine that an object is no longer used,
+      the cyclic garbage collector is not involved and
+      :c:member:`~PyModuleDef.m_free` is called directly.
+
       .. versionchanged:: 3.9
          No longer called before the module state is allocated.
 

diff --git a/Doc/c-api/typeobj.rst b/Doc/c-api/typeobj.rst
index b18e3852be3ad0b9fdacabc0c0aafcba34e2fea2..b17fb22b694951afa042250383616e057b6aa145 100644 (file)
--- a/Doc/c-api/typeobj.rst
+++ b/Doc/c-api/typeobj.rst
@@ -1381,6 +1381,12 @@ and :c:type:`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.
 
+   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
+   collector is not involved and :c:member:`~PyTypeObject.tp_dealloc` is
+   called directly.
+
    Because the goal of :c:member:`~PyTypeObject.tp_clear` functions is to break reference cycles,
    it's not necessary to clear contained objects like Python strings or Python
    integers, which can't participate in reference cycles. On the other hand, it may