[docs] [issue28737] Document that tp_dealloc handler must call PyObject_GC_UnTrack if Py_TPFLAGS_HAVE_GC is set

[Sam Gross]

New submission from Sam Gross:

In general, an a PyTypeObject that has Py_TPFLAGS_HAVE_GC set must call PyObject_GC_UnTrack() before it frees any PyObject* references it owns. The only reference to this requirement I found is in https://docs.python.org/3/c-api/gcsupport.html#c._PyObject_GC_TRACK.

This requirement should be documented in:

1. https://docs.python.org/3/c-api/typeobj.html#c.PyTypeObject.tp_dealloc
2. https://docs.python.org/3/extending/newtypes.html

A call to PyObject_GC_UnTrack() should also be added to he official "noddy4" example. Currently, the example is incorrect and can crash if a referred-to object triggers a GC from it's destructor. See the following example which segfaults:

https://github.com/colesbury/noddy

It may be worthwhile to have _Py_Dealloc call PyObject_GC_UnTrack() if the PyTypeObject has Py_TPFLAGS_HAVE_GC set. Considering that the official Python extension example is missing the call, it seems likely that extension writers often forget to include it.

----------
assignee: docs at python
components: Documentation, Extension Modules
messages: 281146
nosy: colesbury, docs at python
priority: normal
severity: normal
status: open
title: Document that tp_dealloc handler must call PyObject_GC_UnTrack if Py_TPFLAGS_HAVE_GC is set
versions: Python 3.5

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue28737>
_______________________________________