René's URL Explorer Experiment

{"@context":"https://schema.org","@type":"DiscussionForumPosting","headline":"Improve guidelines for GC protocol implementation for heap types","articleBody":"This is a follow-up to https://github.com/python/cpython/pull/125962 which added some guidelines:\n\n- Use `type-\u003etp_alloc` instead of `PyObject_New` and `PyObject_GC_New`.\n- Use `type-\u003etp_free` instead of `PyObject_Free` and `PyObject_GC_Del`.\n\nThose two recommendations were introduced to facilitate adding the `Py_TPFLAGS_HAVE_GC` flag to a heap type (those types must (should?) implement the GC protocol, at least according to the docs: https://docs.python.org/3/c-api/gcsupport.html#supporting-cycle-detection).\n\nNow, the docs should indicate that:\n\n- `type-\u003etp_alloc` may call `PyObject_GC_Track`, depending on `Py_TPFLAGS_HAVE_GC`. Some users could be surprised by this (like me in https://github.com/python/cpython/pull/138266).\n- https://docs.python.org/3.14/c-api/gcsupport.html#supporting-cycle-detection should be updated because it mentions using `PyObject_GC_New`, which itself mentions using `tp_alloc` directly. Better to just mention `tp_alloc`.\n\nWhat I am actually worried about is:\n\n\u003e Constructors for container types must conform to two rules:\n\u003e\n\u003e - The memory for the object must be allocated using [PyObject_GC_New](https://docs.python.org/3.14/c-api/gcsupport.html#c.PyObject_GC_New) or [PyObject_GC_NewVar](https://docs.python.org/3.14/c-api/gcsupport.html#c.PyObject_GC_NewVar).\n\u003e - Once all the fields which may contain references to other containers are initialized, it must call [PyObject_GC_Track()](https://docs.python.org/3.14/c-api/gcsupport.html#c.PyObject_GC_Track).\n\nNow, `tp_alloc` automatically calls `PyObject_GC_Track` so users won't be able to pre-initialize fields, so I suggest that we mention this.\n\n\u003cdetails\u003e\n\u003csummary\u003eOutdated discussion\u003c/summary\u003e\n\nIf people need to first initialize fields, maybe we should recommend constructing them first:\n\n```c\nstatic PyObject *\nobject_new(PyTypeObject *type)\n{\n    T *self = NULL;\n    PyObject *f1, *f2, *f3;\n    \n    f1 = do1();\n    if (f1 == NULL) { goto error_pre_init; }\n    f2 = do2();\n    if (f2 == NULL) { goto error_pre_init; }\n    f3 = do3();\n    if (f3 == NULL) { goto error_pre_init; }\n    \n    self = (T *)type-\u003etp_alloc(type, 0);\n    if (self == NULL) {\n        goto error_pre_init;\n    }\n    self-\u003ef1 = f1;\n    self-\u003ef2 = f2;\n    self-\u003ef3 = f3;\n    f1 = f2 = f3 = NULL;\n\n    if (finalize(self) \u003c 0) {\n        goto error;\n    }\n    return (PyObject *)self;\n\nerror_pre_init:\n    Py_XDECREF(f1);\n    Py_XDECREF(f2);\n    Py_XDECREF(f3);\n    return NULL;\n\nerror_post_init:\n    Py_DECREF(self);\n    return NULL;\n}\n```\n\u003c/details\u003e\n\ncc @ZeroIntensity ","author":{"url":"https://github.com/picnixz","@type":"Person","name":"picnixz"},"datePublished":"2025-08-31T13:19:21.000Z","interactionStatistic":{"@type":"InteractionCounter","interactionType":"https://schema.org/CommentAction","userInteractionCount":4},"url":"https://github.com/138292/cpython/issues/138292"}