參照計數

本節中的巨集用於管理 Python 物件的參照計數。

void Py_INCREF(PyObject *o)

表示为对象 o 获取一个新的 strong reference,指明该对象正在被使用且不应被销毁。

此函式通常用於將借用參照原地 (in-place) 轉換為強參照Py_NewRef() 函式可用於建立新的強參照

当对象使用完毕后,可调用 Py_DECREF() 释放它。

該物件不能為 NULL;如果你不確定它不是 NULL,請使用 Py_XINCREF()

Do not expect this function to actually modify o in any way.

void Py_XINCREF(PyObject *o)

Py_INCREF() 类似,但对象 o 可以为 NULL,在这种情况下此函数将没有任何效果。

另請見 Py_XNewRef()

PyObject *Py_NewRef(PyObject *o)
属于 稳定 ABI 自 3.10 版开始.

为对象创建一个新的 strong reference: 在 o 上调用 Py_INCREF() 并返回对象 o

当不再需要这个 strong reference 时,应当在其上调用 Py_DECREF() 来释放引用。

物件 o 不能為 NULL;如果 o 可以為 NULL,則使用 Py_XNewRef()

舉例來說:

Py_INCREF(obj);
self->attr = obj;

可以寫成:

self->attr = Py_NewRef(obj);

另請參閱 Py_INCREF()

在 3.10 版新加入.

PyObject *Py_XNewRef(PyObject *o)
属于 稳定 ABI 自 3.10 版开始.

Py_NewRef() 類似,但物件 o 可以為 NULL。

如果物件 oNULL,則該函式僅回傳 NULL

在 3.10 版新加入.

void Py_DECREF(PyObject *o)

释放一个指向对象 ostrong reference,表明该引用不再被使用。

当最后一个 strong reference 被释放时 (即对象的引用计数变为 0),将会发起调用该对象所属类型的 deallocation 函数 (它必须不为 NULL)。

此函式通常用於在退出作用域之前刪除強參照

該物件不能為 NULL;如果你不確定它不是 NULL,請改用 Py_XDECREF()

Do not expect this function to actually modify o in any way.

警告

释放函数会导致任意 Python 代码被发起调用(例如当一个带有 __del__() 方法的类实例被释放时就是如此)。 虽然这些代码中的异常不会被传播,但被执行的代码能够自由访问所有 Python 全局变量。 这意味着在调用 Py_DECREF() 之前任何可通过全局变量获取的对象都应该处于完好的状态。 例如,从一个列表中删除对象的代码应该将被删除对象的引用拷贝到一个临时变量中,更新列表数据结构,然后再为临时变量调用 Py_DECREF()

void Py_XDECREF(PyObject *o)

Py_DECREF() 类似,但对象 o 可以为 NULL,在这种情况下此函数将没有任何效果。 来自 Py_DECREF() 的警告同样适用于此处。

void Py_CLEAR(PyObject *o)

释放一个指向对象 ostrong reference。 对象可以为 NULL,在此情况下该宏将没有任何效果;在其他情况下其效果与 Py_DECREF() 相同,区别在于其参数也会被设为 NULL。 针对 Py_DECREF() 的警告不适用于所传递的对象,因为该宏会细心地使用一个临时变量并在释放引用之前将参数设为 NULL

当需要释放指向一个在垃圾回收期间可能被会遍历的对象的引用时使用该宏是一个好主意。

void Py_IncRef(PyObject *o)
属于 稳定 ABI.

表示获取一个指向对象 o 的新 strong referencePy_XINCREF() 的函数版本。 它可被用于 Python 的运行时动态嵌入。

void Py_DecRef(PyObject *o)
属于 稳定 ABI.

释放一个指向对象 ostrong referencePy_XDECREF() 的函数版本。 它可被用于 Python 的运行时动态嵌入。

以下函式或巨集僅在直譯器核心內使用:_Py_Dealloc()_Py_ForgetReference()_Py_NewReference() 以及全域變數 _Py_RefTotal