classification
Title: Document that tp_dealloc handler must call PyObject_GC_UnTrack if Py_TPFLAGS_HAVE_GC is set
Type: Stage: resolved
Components: Documentation, Extension Modules Versions: Python 3.11, Python 3.10, Python 3.9
process
Status: closed Resolution: fixed
Dependencies: Superseder:
Assigned To: colesbury Nosy List: colesbury, docs@python, lukasz.langa, miss-islington
Priority: normal Keywords: patch

Created on 2016-11-18 16:47 by colesbury, last changed 2021-10-28 19:23 by lukasz.langa. This issue is now closed.

Pull Requests
URL Status Linked Edit
PR 29246 merged colesbury, 2021-10-27 17:03
PR 29248 merged miss-islington, 2021-10-27 19:15
PR 29249 merged colesbury, 2021-10-27 19:37
Messages (6)
msg281146 - (view) Author: Sam Gross (colesbury) * (Python triager) Date: 2016-11-18 16:47
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.
msg405112 - (view) Author: Sam Gross (colesbury) * (Python triager) Date: 2021-10-27 16:46
Antoine Pitrou already fixed the "noddy4" example (now renamed to "custom4") and updated the newtypes_tutorial, but I think it's still worth mentioning PyObject_GC_Untrack in a few additional places.
msg405120 - (view) Author: Łukasz Langa (lukasz.langa) * (Python committer) Date: 2021-10-27 19:15
New changeset 35e1ff38ee67ee543d9fcb268c3552c5397f9b3f by Sam Gross in branch 'main':
bpo-28737: Document when tp_dealloc should call PyObject_GC_UnTrack() (GH-29246)
https://github.com/python/cpython/commit/35e1ff38ee67ee543d9fcb268c3552c5397f9b3f
msg405232 - (view) Author: Łukasz Langa (lukasz.langa) * (Python committer) Date: 2021-10-28 19:23
New changeset 9e0012116ac9e8d26bf19ef8741deeecf2b6f72b by Sam Gross in branch '3.10':
[3.10] bpo-28737: Document when tp_dealloc should call PyObject_GC_UnTrack() (GH-29246) (GH-29249)
https://github.com/python/cpython/commit/9e0012116ac9e8d26bf19ef8741deeecf2b6f72b
msg405233 - (view) Author: Łukasz Langa (lukasz.langa) * (Python committer) Date: 2021-10-28 19:23
New changeset 193504acf3bfb7cff1edf7f568c2405b857fa1f7 by Miss Islington (bot) in branch '3.9':
bpo-28737: Document when tp_dealloc should call PyObject_GC_UnTrack() (GH-29246) (GH-29248)
https://github.com/python/cpython/commit/193504acf3bfb7cff1edf7f568c2405b857fa1f7
msg405234 - (view) Author: Łukasz Langa (lukasz.langa) * (Python committer) Date: 2021-10-28 19:23
Thanks, Sam! ✨ 🍰 ✨
History
Date User Action Args
2021-10-28 19:23:51lukasz.langasetstatus: open -> closed
versions: + Python 3.9, Python 3.10, Python 3.11, - Python 3.5
messages: + msg405234

resolution: fixed
stage: patch review -> resolved
2021-10-28 19:23:23lukasz.langasetmessages: + msg405233
2021-10-28 19:23:04lukasz.langasetmessages: + msg405232
2021-10-27 19:37:39colesburysetpull_requests: + pull_request27513
2021-10-27 19:15:30miss-islingtonsetnosy: + miss-islington
pull_requests: + pull_request27512
2021-10-27 19:15:25lukasz.langasetnosy: + lukasz.langa
messages: + msg405120
2021-10-27 17:03:45colesburysetkeywords: + patch
stage: patch review
pull_requests: + pull_request27510
2021-10-27 16:46:18colesburysetmessages: + msg405112
2021-10-27 15:44:34colesburysetassignee: docs@python -> colesbury
2016-11-18 16:47:36colesburycreate