第四章 引用计数

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

• void Py_INCREF(PyObject *o)
  增加对象 o 的引用计数。
  此函数通常被用来将borrowed reference 原地转换为strong reference。Py_NewRef() 函数可被用来创建新的strong reference。
  此对象必须不为 NULL；如果你不能确定它不为 NULL，请使用Py_XINCREF()。
• void Py_XINCREF(PyObject *o)
  增加对象 o 的引用计数。对象可以为 NULL，在此情况下该宏不产生任何效果。
  另请参阅Py_XNewRef()。
• PyObject *Py_NewRef(PyObject *o)
  Part of the Stable ABI since version 3.10. 新建指向一个对象的strong reference: 增加对象 o 的引用计数并返回对象 o。
  当不再需要这个strong reference 时，应当在对象上调用Py_DECREF() 来有减少该对象的引用计数。
  对象 o 必须不为 NULL；如果 o 可以为 NULL 则应改用Py_XNewRef()。
  例如：

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

可以写成:

self->attr = Py_NewRef(obj);
1

另请参阅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 的引用计数。
  如果引用计数达到零，则会发起调用对象类型的撤销分配函数 (该函数必须不为 NULL)。
  此函数通常被用于在退出作用域之前删除一个strong reference。
  此对象必须不为 NULL；如果你不能确定它不为 NULL，请使用Py_XDECREF()。

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

• void Py_XDECREF(PyObject *o)
  减少对象 o 的引用计数。对象可以为 NULL，在此情况下该宏不产生任何效果；在其他情况下其效果与Py_DECREF() 相同，并会应用同样的警告。
• void Py_CLEAR(PyObject *o)
  减少对象 o 的引用计数。对象可以为 NULL，在此情况下该宏不产生任何效果；在其他情况下其效果与Py_DECREF() 相同，区别在于其参数也会被设为 NULL。针对Py_DECREF() 的警告不适用于所传递的对象，因为该宏会细心地使用一个临时变量并在减少其引用计数之前将参数设为 NULL。
  每当要减少在垃圾回收期间可能会被遍历的对象的引用计数时，使用该宏是一个好主意。
• void Py_IncRef(PyObject *o)
  这是稳定的ABI的一部分。增加对象o的引用计数。Py_XINCREF()的一个函数版本。它可以用于Python的运行时动态嵌入。
• void Py_DecRef(PyObject *o)
  这是稳定的ABI的一部分。减少对象o的引用计数。Py_XDECREF()的一个函数版本。它可以用于Python的运行时动态嵌入。

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