參照計數
********

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

Py_ssize_t Py_REFCNT(PyObject *o)
    * 為 穩定 ABI 的一部分 自 3.14 版本開始.*

   取得物件 *o* 的參照計數。

   請注意，回傳的值可能實際上並不反映實際保存了多少對該物件的參照。例
   如，某些物件是「*不滅的 (immortal)*」，並且具有非常高的參照計數，不
   能反映實際的參照數量。因此，除了 0 或 1 以外，不要依賴回傳值的準確
   性。

   使用 "Py_SET_REFCNT()" 函式設定物件參照計數。

   備註:

     On *free-threaded builds* of Python, returning 1 isn't sufficient
     to determine if it's safe to treat *o* as having no access by
     other threads. Use "PyUnstable_Object_IsUniquelyReferenced()" for
     that instead.See also the function
     "PyUnstable_Object_IsUniqueReferencedTemporary()".

   在 3.10 版的變更: "Py_REFCNT()" 更改為行內靜態函式 (inline static
   function)。

   在 3.11 版的變更: 參數型別不再是 const PyObject*。

void Py_SET_REFCNT(PyObject *o, Py_ssize_t refcnt)

   設定物件 *o* 的參照計數。

   在啟用自由執行緒的 Python 建置中，如果 *refcnt* 大於 "UINT32_MAX"，
   則該物件會被設為*不滅的 (immortal)*。

   請注意，此函式對*不滅的*物件沒有影響。

   在 3.9 版被加入.

   在 3.12 版的變更: 不滅的物件不會被修改。

void Py_INCREF(PyObject *o)

   代表取得對於物件 *o* 的新*強參照*，即它正在使用且不應被銷毀。

   請注意，此函式對*不滅的*物件沒有影響。

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

   使用完該物件後，透過呼叫 "Py_DECREF()" 來釋放它。

   該物件不能為 "NULL"；如果你不確定它不是 "NULL"，請使用
   "Py_XINCREF()"。

   不要期望此函式會以任何方式實際修改 *o*，至少對於**某些物件**來說，
   此函式沒有任何效果。

   在 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* 的*強參照*，代表該參照不會再被使用。

   請注意，此函式對*不滅的*物件沒有影響。

   如果最後一個*強參照*被釋放（即物件的參照計數達到零），則觸發物件之
   型別的釋放函式 (deallocation function)（不得為 "NULL"）。

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

   該物件不能為 "NULL"；如果你不確定它不是 "NULL"，請改用
   "Py_XDECREF()"。

   不要期望此函式會以任何方式實際修改 *o*，至少對於**某些物件**來說，
   此函式沒有任何效果。

   警告:

     釋放函式可以導致任意 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 版的變更: 巨集引數現在僅會被求值一次。如果引數有其他副作用
   ，則不再重複作用。
