參照計數¶
本節中的函式與巨集用於管理 Python 物件的參照計數。
-
Py_ssize_t Py_REFCNT(PyObject *o)¶
取得物件 o 的參照計數。
Note that the returned value may not actually reflect how many references to the object are actually held. For example, some objects are immortal and have a very high refcount that does not reflect the actual number of references. Consequently, do not rely on the returned value to be accurate, other than a value of 0 or 1.
使用
Py_SET_REFCNT()
函式設定物件參照計數。在 3.10 版的變更:
Py_REFCNT()
更改為行內靜態函式 (inline static function)。在 3.11 版的變更: 參數型別不再是 const PyObject*。
-
void Py_SET_REFCNT(PyObject *o, Py_ssize_t refcnt)¶
設定物件 o 的參照計數。
On Python build with Free Threading, if refcnt is larger than
UINT32_MAX
, the object is made immortal.This function has no effect on immortal objects.
在 3.9 版被加入.
在 3.12 版的變更: 不滅的物件不會被修改。
-
void Py_INCREF(PyObject *o)¶
代表取得對於物件 o 的新強參照,即它正在使用且不應被銷毀。
This function has no effect on immortal objects.
此函式通常用於將借用參照原地 (in-place) 轉換為強參照。
Py_NewRef()
函式可用於建立新的強參照。When done using the object, release is by calling
Py_DECREF()
.該物件不能為
NULL
;如果你不確定它不是NULL
,請使用Py_XINCREF()
。Do not expect this function to actually modify o in any way. For at least some objects, this function has no effect.
在 3.12 版的變更: 不滅的物件不會被修改。
-
void Py_XINCREF(PyObject *o)¶
與
Py_INCREF()
類似,但物件 o 可以為NULL
,在這種情況下這就不會有任何效果。另請見
Py_XNewRef()
。
-
PyObject *Py_NewRef(PyObject *o)¶
- 為 穩定 ABI 的一部分 自 3.10 版本開始.
建立對物件的新強參照:於 o 呼叫
Py_INCREF()
並回傳物件 o。當不再需要強參照時,應對其呼叫
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。如果物件 o 為
NULL
,則該函式僅回傳NULL
。在 3.10 版被加入.
-
void Py_DECREF(PyObject *o)¶
釋放一個對物件 o 的強參照,代表該參照不會再被使用。
This function has no effect on immortal objects.
如果最後一個強參照被釋放(即物件的參照計數達到零),則觸發物件之型別的釋放函式 (deallocation function)(不得為
NULL
)。此函式通常用於在退出作用域之前刪除強參照。
該物件不能為
NULL
;如果你不確定它不是NULL
,請改用Py_XDECREF()
。Do not expect this function to actually modify o in any way. For at least some objects, this function has no effect.
警告
釋放函式可以導致任意 Python 程式碼被調用(例如,當釋放具有
__del__()
方法的類別實例時)。雖然此類程式碼中的例外不會被傳遞出來,但執行的程式碼可以自由存取所有 Python 全域變數。這意味著在調用Py_DECREF()
之前,可從全域變數存取的任何物件都應處於一致狀態。例如,從 list 中刪除物件的程式碼應將已刪除物件的參照複製到臨時變數中,更新 list 資料結構,然後為臨時變數呼叫Py_DECREF()
。在 3.12 版的變更: 不滅的物件不會被修改。
-
void Py_XDECREF(PyObject *o)¶
和
Py_DECREF()
類似,但該物件可以是NULL
,在這種情況下巨集不起作用。在這裡也會出現與Py_DECREF()
相同的警告。
-
void Py_CLEAR(PyObject *o)¶
釋放對於物件 o 的強參照。該物件可能是
NULL
,在這種情況下巨集不起作用;否則,效果與Py_DECREF()
相同,除非引數也設定為NULL
。Py_DECREF()
的警告不適用於傳遞的物件,因為巨集在釋放其參照之前小心地使用臨時變數並將引數設定為NULL
。每當要釋放垃圾回收 (garbage collection) 期間可能被遍歷到之對於物件的參照時,使用此巨集是個好主意。
在 3.12 版的變更: 巨集引數現在僅會被求值 (evaluate) 一次。如果引數有其他副作用,則不再重複作用。
-
void Py_IncRef(PyObject *o)¶
- 為 穩定 ABI 的一部分.
代表取得對於物件 o 的強參照。
Py_XINCREF()
的函式版本。它可用於 Python 的 runtime 動態嵌入。
-
void Py_DecRef(PyObject *o)¶
- 為 穩定 ABI 的一部分.
釋放對物件 o 的強參照。
Py_XDECREF()
的函式版本。它可用於 Python 的 runtime 動態嵌入。
-
Py_SETREF(dst, src)¶
巨集安全地釋放對於物件 dst 的強參照並將 dst 設定為 src。
與
Py_CLEAR()
的情況一樣,「明顯的」程式碼可能是致命的:Py_DECREF(dst); dst = src;
安全的方法是:
Py_SETREF(dst, src);
這會在釋放對 dst 舊值的參照_之前_將 dst 設定為 src,使得因 dst 被拆除而觸發的任何副作用 (side-effect) 之程式碼不會相信 dst 是指向一個有效物件。
在 3.6 版被加入.
在 3.12 版的變更: 巨集引數現在僅會被求值一次。如果引數有其他副作用,則不再重複作用。
-
Py_XSETREF(dst, src)¶
Py_SETREF
巨集的變體,請改用Py_XDECREF()
而非Py_DECREF()
。在 3.6 版被加入.
在 3.12 版的變更: 巨集引數現在僅會被求值一次。如果引數有其他副作用,則不再重複作用。