參照計數

本节介绍的宏被用于管理 Python 对象的引用计数。

void Py_INCREF(PyObject *o)

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

此函数通常被用来将 borrowed reference 原地转换为 strong reference。 Py_NewRef() 函数可被用来创建新的 strong reference。

当对象使用完毕后，可调用 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)

Part of the Stable ABI since version 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)

Part of the Stable ABI since version 3.10.

类似于 Py_NewRef()，但对象 o 可以为 NULL。

如果对象 o 为 NULL，该函数也·将返回 NULL。

3.10 版新加入.

void Py_DECREF(PyObject *o)

释放一个指向对象 o 的 strong reference，表明该引用不再被使用。

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

此函数通常被用于在退出作用域之前删除一个 strong reference。

此对象必须不为 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)

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

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

void Py_IncRef(PyObject *o)

Part of the Stable ABI.

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

void Py_DecRef(PyObject *o)

Part of the Stable ABI.

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

以下函数或宏仅可在解释器核心内部使用: _Py_Dealloc(), _Py_ForgetReference(), _Py_NewReference() 以及全局变量 _Py_RefTotal。