參照計數¶
本節中的函式與巨集用於管理 Python 物件的參照計數。
- Py_ssize_tPy_REFCNT(PyObject*o)¶
取得物件o 的參照計數。
請注意，回傳的值可能實際上並不反映實際保存了多少對該物件的參照。例如，某些物件是「不滅的 (immortal)」，並且具有非常高的參照計數，不能反映實際的參照數量。因此，除了 0 或 1 以外，不要依賴回傳值的準確性。
使用
Py_SET_REFCNT()函式設定物件參照計數。在 3.10 版的變更:
Py_REFCNT()更改為行內靜態函式 (inline static function)。在 3.11 版的變更:參數型別不再是constPyObject*。
- voidPy_SET_REFCNT(PyObject*o,Py_ssize_trefcnt)¶
設定物件o 的參照計數。
OnPython build with Free Threading, ifrefcnt is larger than
UINT32_MAX, the object is madeimmortal.請注意，此函式對不滅的物件沒有影響。
在 3.9 版被加入.
在 3.12 版的變更:不滅的物件不會被修改。
- voidPy_INCREF(PyObject*o)¶
代表取得對於物件o 的新強參照，即它正在使用且不應被銷毀。
請注意，此函式對不滅的物件沒有影響。
此函式通常用於將借用參照原地 (in-place) 轉換為強參照。
Py_NewRef()函式可用於建立新的強參照。使用完該物件後，透過呼叫
Py_DECREF()來釋放它。該物件不能為
NULL；如果你不確定它不是NULL，請使用Py_XINCREF()。不要期望此函式會以任何方式實際修改o，至少對於某些物件來說，此函式沒有任何效果。
在 3.12 版的變更:不滅的物件不會被修改。
- voidPy_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 版被加入.
- voidPy_DECREF(PyObject*o)¶
釋放一個對物件o 的強參照，代表該參照不會再被使用。
請注意，此函式對不滅的物件沒有影響。
如果最後一個強參照被釋放（即物件的參照計數達到零），則觸發物件之型別的釋放函式 (deallocation function)（不得為
NULL）。此函式通常用於在退出作用域之前刪除強參照。
該物件不能為
NULL；如果你不確定它不是NULL，請改用Py_XDECREF()。不要期望此函式會以任何方式實際修改o，至少對於某些物件來說，此函式沒有任何效果。
警告
釋放函式可以導致任意 Python 程式碼被叫用（例如，當釋放具有
__del__()方法的類別實例時）。雖然此類程式碼中的例外不會被傳遞出來，但執行的程式碼可以自由存取所有 Python 全域變數。這意味著在叫用Py_DECREF()之前，可從全域變數存取的任何物件都應處於一致狀態。例如，從 list 中刪除物件的程式碼應將已刪除物件的參照複製到臨時變數中，更新 list 資料結構，然後為臨時變數呼叫Py_DECREF()。在 3.12 版的變更:不滅的物件不會被修改。
- voidPy_XDECREF(PyObject*o)¶
和
Py_DECREF()類似，但該物件可以是NULL，在這種情況下巨集不起作用。在這裡也會出現與Py_DECREF()相同的警告。
- voidPy_CLEAR(PyObject*o)¶
釋放對於物件o 的強參照。該物件可能是
NULL，在這種情況下巨集不起作用；否則，效果與Py_DECREF()相同，除非引數也設定為NULL。Py_DECREF()的警告不適用於傳遞的物件，因為巨集在釋放其參照之前小心地使用臨時變數並將引數設定為NULL。每當要釋放垃圾回收 (garbage collection) 期間可能被遍歷到之對於物件的參照時，使用此巨集是個好主意。
在 3.12 版的變更:巨集引數現在僅會被求值 (evaluate) 一次。如果引數有其他副作用，則不再重複作用。
- voidPy_IncRef(PyObject*o)¶
- 為穩定 ABI 的一部分.
代表取得對於物件o 的強參照。
Py_XINCREF()的函式版本。它可用於 Python 的 runtime 動態嵌入。
- voidPy_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 版的變更:巨集引數現在僅會被求值一次。如果引數有其他副作用，則不再重複作用。