PyObject_CallFinalizerFromDealloc is not referenced in any documentation #78090

Activity

1. eric-wieser commented on Jun 20, 2018

   

   eric-wiesermannequin

   on Jun 20, 2018

   MannequinAuthor

   More actions

   PEP-442 states that:

   Two new C API functions are provided to ease calling of tp_finalize, especially from custom deallocators.

   But it does not give the names of these functions, nor do any python docs I can discover.

   From grepping for tp_finalize, it seems the functions in question are:

   • PyObject_CallFinalizerFromDealloc
   • PyObject_CallFinalizer

   It would be great if these could be documented, and perhaps even an example given of when it's appropriate to call each one.
2. eric-wieser

   added

   3.7 (EOL)end of lifeend of life

   3.8 (EOL)end of lifeend of life

   on Jun 20, 2018
3. eric-wieser

   assigned

   docspython

   on Jun 20, 2018
4. eric-wieser

   added

   docsDocumentation in the Doc dirDocumentation in the Doc dir

   on Jun 20, 2018
5. methane commented on Jun 21, 2018

   

   methane

   on Jun 21, 2018

   Member

   More actions

   I think I can describe what two function does/for.
   But I'm not good English writer. Would you write document instead?

   ---

   "Finalizer" is __del__ in Python and tp_finalize in C.

   Calling finalizer requires some tricks, including avoiding call twice.
   That is what PyObject_CallFinalizer() does. Use it instead of call type->tp_finalize(obj) directly.

   But finalizer is called from destructor (tp_dealloc) usually, and calling finalizer from destructor need more hack (e.g. temporary increment refcount). This is what PyObject_CallFinalizerFromDealloc does.

   Generally speaking, this API is used only when you want to use both of custom tp_dealloc and tp_finalize. This is very rare because you can write cleanup code in tp_dealloc and skip using tp_finalize.

   When you need really need both of tp_dealloc and tp_finalize, note that:

   • Finalizer may resurrect the object.
   • When the type is subclassed from Python, tp_finalize is called automatically. You must not call PyObject_CallFinalizerFromDealloc then.

   This is tp_dealloc of Future object in asyncio. This object uses both of tp_dealloc and tp_finalize for compatibility with Future object implemented in pure Python. This covers many edge cases of tp_dealloc.

   static void
   FutureObj_dealloc(PyObject *self)
   {
       FutureObj *fut = (FutureObj *)self;
   
       if (Future_CheckExact(fut)) {
           /* When fut is subclass of Future, finalizer is called from
            * subtype_dealloc.
            */
           if (PyObject_CallFinalizerFromDealloc(self) < 0) {
               // resurrected.
               return;
           }
       }
   
       // Weakref callback and finalizer of other objects may start GC.
       // So you need to untrack this object from GC before calling PyObject_ClearWeakRefs()
       // or any Py_DECREF()s
       // Otherwise, GC will cause segfault because refcount of this object is 0.
       PyObject_GC_UnTrack(self);
   
       // Handle weakrefs
       if (fut->fut_weakreflist != NULL) {
           PyObject_ClearWeakRefs(self);
       }
   
       // Reuse tp_clear() for clearing all members.
       (void)FutureObj_clear(fut);
   
       // Free this object at last.
       Py_TYPE(fut)->tp_free(fut);
   }
   
6. iritkatriel

   added

   3.9 (EOL)end of lifeend of life

   3.10 (EOL)end of lifeend of life

   3.11only security fixesonly security fixes

   and removed

   3.7 (EOL)end of lifeend of life

   3.8 (EOL)end of lifeend of life

   on Dec 3, 2021
7. ezio-melotti

   transferred this issue fromon Apr 10, 2022
8. rhansen commented on Oct 22, 2024

   

   rhansen

   on Oct 22, 2024

   Contributor

   More actions

   Duplicate of #75459
9. kumaraditya303

   closed this as a duplicateof PyObject_CallFinalizerFromDealloc is undocumented #75459 on Sep 10, 2025