Clarify that tp_dealloc must decref for heap allocated type

[ammaraskar]

BPO	38206
Nosy	@ammaraskar, @miss-islington
PRs	bpo-38206: Clarify tp_dealloc requirements for heap allocated types. #16248 [3.8] bpo-38206: Clarify tp_dealloc requirements for heap allocated types. (GH-16248) #16436

^{Note: these values reflect the state of the issue at the time it was migrated and might not reflect the current state.}

Show more details

GitHub fields:

assignee = None
closed_at = <Date 2019-09-27.16:49:33.332>
created_at = <Date 2019-09-17.23:27:39.940>
labels = ['type-feature', '3.9', 'docs']
title = 'Clarify that tp_dealloc must decref for heap allocated type'
updated_at = <Date 2019-09-27.16:49:33.332>
user = 'https://github.com/ammaraskar'

bugs.python.org fields:

activity = <Date 2019-09-27.16:49:33.332>
actor = 'ammar2'
assignee = 'docs@python'
closed = True
closed_date = <Date 2019-09-27.16:49:33.332>
closer = 'ammar2'
components = ['Documentation']
creation = <Date 2019-09-17.23:27:39.940>
creator = 'ammar2'
dependencies = []
files = []
hgrepos = []
issue_num = 38206
keywords = ['patch']
message_count = 3.0
messages = ['352672', '353354', '353355']
nosy_count = 3.0
nosy_names = ['docs@python', 'ammar2', 'miss-islington']
pr_nums = ['16248', '16436']
priority = 'normal'
resolution = 'fixed'
stage = 'resolved'
status = 'closed'
superseder = None
type = 'enhancement'
url = 'https://bugs.python.org/issue38206'
versions = ['Python 3.9']

[ammaraskar]

When dealing with a heap allocated type (https://docs.python.org/3/c-api/typeobj.html#Py_TPFLAGS_HEAPTYPE / PyType_FromSpec), if the type has a custom tp_dealloc function then it MUST decrement the references to the type object itself due to this code block:

cpython/Objects/typeobject.c

Lines 1189 to 1192 in 4a12a17

	/* Only decref if the base type is not already a heap allocated type.
	Otherwise, basedealloc should have decref'd it already */
	if (type->tp_flags & Py_TPFLAGS_HEAPTYPE && !(base->tp_flags & Py_TPFLAGS_HEAPTYPE))
	Py_DECREF(type);

The only mention of this is within the whatsnew entry for 3.8: 364f0b0#diff-77c703d9a958f6a4b0dc2f692b3fd5b3

This error was made in #16127 (review) and #16071 (review)

It seems like a common pitfall, let's add a note about this in the doc.

[miss-islington]

New changeset 5faff97 by Miss Islington (bot) (Ammar Askar) in branch 'master':
bpo-38206: Clarify tp_dealloc requirements for heap allocated types. (GH-16248)
5faff97

[miss-islington]

New changeset 14ddca7 by Miss Islington (bot) in branch '3.8':
bpo-38206: Clarify tp_dealloc requirements for heap allocated types. (GH-16248)
14ddca7