_debugmallocstats() undercounts bytes in type-specific free lists

[tim-one]

Bug report

Bug description:

Toward the tail end of sys._debugmallocstats() output there's an account of bytes sitting in various type-specific free lists, like so:|

           62 free PyDictObjects * 48 bytes each =                2,976
       77 free PyDictKeysObjects * 32 bytes each =                2,464
           6 free PyFloatObjects * 24 bytes each =                  144
           60 free PyListObjects * 40 bytes each =                2,400
 231 free 1-sized PyTupleObjects * 40 bytes each =                9,240
...

However, for the container types that participate in cyclic gc (dict, list, tuple), the "bytes each" figurers are too small. Like:

Python 3.14.1 (tags/v3.14.1:57e0d17, Dec  2 2025, 14:05:07) [MSC v.1944 64 bit (AMD64)] on win32
Type "help", "copyright", "credits" or "license" for more information.
>>> import sys
>>> sys.getsizeof([])
56

56 > 40, by 16. Same 16 missing for dicts and tuples. I suspect (but don't know) that they're missing the two pointers (before the PYObject's type pointer) used by cyclic gc to link together the members of a generation.

Labeling as "easy", because it has to 😉 be shallow. A good exercise for somene to sharpen their archeological skills.

CPython versions tested on:

3.14

Operating systems tested on:

Windows

Linked PRs

• GH-148189: Fix miscalculation of type-specific free list memory use #148190

[verysleepylemon]

The 16-byte discrepancy is exactly sizeof(PyGC_Head) — the two Py_uintptr_t fields (_gc_next and _gc_prev) that the cyclic GC prepends before the object header for every container type that participates in cycle collection (dict, list, tuple, set, etc.).

sys.getsizeof([]) returns 56, but the free-list table reports "40 bytes each":

• 40 bytes = sizeof(PyListObject) alone
• 16 bytes = sizeof(PyGC_Head) (two pointer-sized fields on 64-bit)
• 56 = 40 + 16 ✓

The fix is in the C code that prints the free-list accounting (around Objects/listobject.c or wherever _PyList_DebugMallocStats is defined) — it should add sizeof(PyGC_Head) to the per-object size for any type that has Py_TPFLAGS_HAVE_GC set, since those objects actually occupy that extra memory when alive.

Worth checking: floatobject does not participate in cyclic GC, so 24 bytes for PyFloatObject in the output is correct. Only the container types (dict, list, tuple) need the +16 correction.

[MazinSharaf]

Isn't the tuple supposed to remain unchanged though? And also why are you using AI to write the comment?

[tim-one]

I believe the analysis is correct, but the "fix" is off. The code should follow what the sys.siseof() implementation does instead. For lists, that's

static PyObject *
list___sizeof___impl(PyListObject *self)
/*[clinic end generated code: output=3417541f95f9a53e input=b8030a5d5ce8a187]*/
{
    size_t res = _PyObject_SIZE(Py_TYPE(self));
#ifdef Py_GIL_DISABLED
    PyObject **ob_item = _Py_atomic_load_ptr(&self->ob_item);
    if (ob_item != NULL) {
        res += list_capacity(ob_item) * sizeof(PyObject *);
    }
#else
    res += (size_t)self->allocated * sizeof(PyObject *);
#endif
    return PyLong_FromSize_t(res);

_PyObject_SIZE() already knows everything, and will be updated as needed if/when things change.

@MazinSharaf. yes, tuples are immutable, but that isn't relevant. They still participate in cyclic gc, because they can appear in cycles, like

>>> L = []
>>> t = L,
>>> t
([],)
>>> L.append(t)
>>> t
([(...)],)

So tuple objects also have a GC head prefix.

[MazinSharaf]

Alright then I'll change calculation of the tuple in the PR I made.

[tim-one]

Good! The high-order bit is to use _PyObject_SIZE(Py_TYPE(self)), which already knows total object struct sizes, gc or not. It's a macro that reads up the tp_basicsize member of a type object. To check results, make sure "bytes each" output matches sys.getsizeof() output.