python / python/cpython

Improve guidelines for GC protocol implementation for heap types

未關閉
#138,292 4 則留言 0 個 reaction 已指派 0 人 在 GitHub 檢視

還沒有人認領這個 Issue。

docs topic-C-API
主要語言
Python
星號
77.2k
分支
35.9k
PR 合併指標
PR 指標待擷取

描述

This is a follow-up to https://github.com/python/cpython/pull/125962 which added some guidelines:

  • Use type->tp_alloc instead of PyObject_New and PyObject_GC_New.
  • Use type->tp_free instead of PyObject_Free and PyObject_GC_Del.

Those 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).

Now, the docs should indicate that:

What I am actually worried about is:

Constructors for container types must conform to two rules:

Now, tp_alloc automatically calls PyObject_GC_Track so users won't be able to pre-initialize fields, so I suggest that we mention this.

Outdated discussion

If people need to first initialize fields, maybe we should recommend constructing them first:

static PyObject *
object_new(PyTypeObject *type)
{
    T *self = NULL;
    PyObject *f1, *f2, *f3;
    
    f1 = do1();
    if (f1 == NULL) { goto error_pre_init; }
    f2 = do2();
    if (f2 == NULL) { goto error_pre_init; }
    f3 = do3();
    if (f3 == NULL) { goto error_pre_init; }
    
    self = (T *)type->tp_alloc(type, 0);
    if (self == NULL) {
        goto error_pre_init;
    }
    self->f1 = f1;
    self->f2 = f2;
    self->f3 = f3;
    f1 = f2 = f3 = NULL;

    if (finalize(self) < 0) {
        goto error;
    }
    return (PyObject *)self;

error_pre_init:
    Py_XDECREF(f1);
    Py_XDECREF(f2);
    Py_XDECREF(f3);
    return NULL;

error_post_init:
    Py_DECREF(self);
    return NULL;
}

cc @ZeroIntensity

貢獻指南

開啟貢獻指南

從這裡開始

  1. 先讀完整個 Issue,再讀專案的貢獻指南。
  2. 在 Issue 下留言說明你要接手 —— 這能避免兩個人做同樣的事。
  3. Fork 儲存庫,在一個分支上完成修改。
  4. 送出 Pull Request,並在描述裡引用這個 Issue 編號。

研究方向

從 docs.python.org/3.14/c-api/gcsupport.html 中的 C API 垃圾回收支援文件開始,特別關注有關 tp_alloc、PyObject_GC_New 和 PyObject_GC_Track 的指引。更新指引,說明 tp_alloc 何時會追蹤物件,並在適當情況下使用 tp_alloc 而不是 PyObject_GC_New;當文件化的建構規則一致時即完成。

由索引模型根據 Issue 內容生成。

評估

技術堆疊
c, python
領域
documentation
Issue 類型
文件
難度
3/5
預估耗時
1-2 天
活躍度
停滯
描述清晰度
基本清楚
新手友好度
35/100

把新 issue 寄到你的電子郵件信箱

精選適合新手參與的 GitHub issue 摘要。