参照カウント
************

このセクションにある関数とマクロは、 Python オブジェクトの参照カウント
の管理に使用されます。

Py_ssize_t Py_REFCNT(PyObject *o)
    * 次に属します: Stable ABI (バージョン 3.14 より).*

   Python オブジェクト *o* の参照カウントを取得します。

   戻り値は、実際に保持されているオブジェクトの参照の数を実際に反映し
   ているとは限らないことに注意してください。例えば、一部のオブジェク
   トは永続 (*immortal*) であり、実際の参照の数を反映しない非常に高い
   参照数を持ちます。したがって、 0 か 1 の値以外では、正確な戻り値に
   頼らないでください。

   オブジェクトの参照カウントを設定するためには、 "Py_SET_REFCNT()" 関
   数を使用してください。

   注釈:

     Python の *フリースレッドビルド* では、戻り値が 1 であるだけでは
     、ほかのスレッドから "o" へのアクセスがないものとして安全に扱える
     かどうかを判断できません。 その判断には
     "PyUnstable_Object_IsUniquelyReferenced()" を使ってください。
     "PyUnstable_Object_IsUniqueReferencedTemporary()" 関数も参照して
     ください。

   バージョン 3.10 で変更: "Py_REFCNT()" は static なインライン関数に
   変更されました。

   バージョン 3.11 で変更: 引数の型は const PyObject* ではなくなりまし
   た。

void Py_SET_REFCNT(PyObject *o, Py_ssize_t refcnt)
    * This macro is available when compiling for the Stable ABI (バー
   ジョン 3.9 より).*

   オブジェクト *o* の参照カウントを *refcnt* に設定します。

   フリースレッドな Python ビルド では、 *refcnt* が "UINT32_MAX" より
   大きい場合、オブジェクトは永続 (*immortal*) となります。

   この関数は永続 (*immortal*) オブジェクトには何もしません。

   Added in version 3.9.

   バージョン 3.12 で変更: 永続オブジェクトは変更されません。

void Py_INCREF(PyObject *o)
    * This macro is available when compiling for the Stable ABI.*

   オブジェクト *o* への新しい *強参照* を取得し、それが使用中で破棄さ
   れてはならないことを示します。

   この関数は永続 (*immortal*) オブジェクトには何もしません。

   この関数は通常、*借用参照* をその場で *強参照* に変換するために使い
   ます。 新しい *強参照* の作成には "Py_NewRef()" 関数を使えます。

   オブジェクトを使い終わったら、"Py_DECREF()" を呼び出して参照を解放
   します。

   オブジェクトが "NULL" であってはいけません。それが "NULL" ではない
   と確信が持てないならば、 "Py_XINCREF()" を使ってください。

   この関数が実際に "o" を変更するとは限りません。 少なくとも **一部の
   オブジェクト** に対しては、この関数は何もしません。

   バージョン 3.12 で変更: 永続オブジェクトは変更されません。

void Py_XINCREF(PyObject *o)
    * This macro is available when compiling for the Stable ABI.*

   "Py_INCREF()" と同様ですが、オブジェクト "o" は "NULL" でも構いませ
   ん。 その場合は何もしません。

   "Py_XNewRef()" も参照してください。

PyObject *Py_NewRef(PyObject *o)
    * 次に属します: Stable 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()" も参照してください。

   Added in version 3.10.

PyObject *Py_XNewRef(PyObject *o)
    * 次に属します: Stable ABI (バージョン 3.10 より).*

   "Py_NewRef()" と同様ですが、オブジェクト "o" は "NULL" でも構いませ
   ん。

   オブジェクト "o" が "NULL" の場合、この関数は単に "NULL" を返します
   。

   Added in version 3.10.

void Py_DECREF(PyObject *o)
    * This macro is available when compiling for the Stable ABI.*

   オブジェクト "o" への *強参照* を解放し、その参照をもう使わないこと
   を示します。

   この関数は永続 (*immortal*) オブジェクトには何もしません。

   最後の *強参照* が解放されると (つまり、オブジェクトの参照カウント
   が 0 になると)、そのオブジェクトの型の解放関数が呼び出されます。 こ
   の関数は "NULL" であってはいけません。

   この関数は通常、スコープを抜ける前に *強参照* を削除するために使い
   ます。

   オブジェクトが "NULL" であってはいけません。それが "NULL" ではない
   と確信が持てないならば、 "Py_XDECREF()" を使ってください。

   この関数が実際に "o" を変更するとは限りません。 少なくとも **一部の
   オブジェクト** に対しては、この関数は何もしません。

   警告:

     解放関数は任意の Python コードを呼び出すことがあります (例えば
     "__del__()" メソッドを持つクラスのインスタンスを解放するとき)。
     そのコード内の例外は伝播しませんが、実行されるコードは Python の
     すべてのグローバル変数に自由にアクセスできます。 このため、グロー
     バル変数から到達できるオブジェクトは、"Py_DECREF()" を呼び出す前
     に整合性の取れた状態にしておく必要があります。 例えば、リストから
     オブジェクトを削除するコードでは、そのオブジェクトへの参照を一時
     変数にコピーしてからリストのデータ構造を更新し、その後で一時変数
     に対して "Py_DECREF()" を呼び出すべきです。

   バージョン 3.12 で変更: 永続オブジェクトは変更されません。

void Py_XDECREF(PyObject *o)
    * This macro is available when compiling for the Stable ABI.*

   "Py_DECREF()" と同様ですが、オブジェクト "o" は "NULL" でも構いませ
   ん。 その場合は何もしません。 "Py_DECREF()" と同じ警告がここにも当
   てはまります。

void Py_CLEAR(PyObject *o)
    * This macro is available when compiling for the Stable ABI.*

   オブジェクト "o" への *強参照* を解放します。 オブジェクトは "NULL"
   でもよく、その場合は何もしません。 それ以外の場合は "Py_DECREF()"
   と同じ効果がありますが、引数も "NULL" に設定します。 このマクロは一
   時変数を使い、参照を解放する前に引数を "NULL" に設定するため、渡し
   たオブジェクトについては "Py_DECREF()" の警告は当てはまりません。

   ガベージコレクション中に走査される可能性のあるオブジェクトへの参照
   を解放するときは、このマクロを使うとよいでしょう。

   バージョン 3.12 で変更: マクロの引数を 1 回だけ評価するようになりま
   した。 引数に副作用がある場合も、それが重複して発生することはなくな
   りました。

void Py_IncRef(PyObject *o)
    * 次に属します: Stable ABI.*

   オブジェクト "o" への新しい *強参照* を取得することを示します。
   "Py_XINCREF()" の関数版です。 実行時に Python を動的に組み込むため
   に使えます。

void Py_DecRef(PyObject *o)
    * 次に属します: Stable ABI.*

   オブジェクト "o" への *強参照* を解放します。 "Py_XDECREF()" の関数
   版です。 実行時に Python を動的に組み込むために使えます。

Py_SETREF(dst, src)

   オブジェクト "dst" への *強参照* を安全に解放し、"dst" を "src" に
   設定するマクロです。

   "Py_CLEAR()" の場合と同様に、「当然」と思える次のコードは致命的な結
   果を招くことがあります。

      Py_DECREF(dst);
      dst = src;

   安全な書き方は次のとおりです。

      Py_SETREF(dst, src);

   これにより、*dst* の古い値への参照を解放する *前に*、*dst* に *src*
   が設定されます。 そのため、古いオブジェクトの破棄に伴って実行される
   コードが、*dst* はそのオブジェクトをまだ有効な状態で指していると誤
   認することを防げます。

   Added in version 3.6.

   バージョン 3.12 で変更: マクロの引数をそれぞれ 1 回だけ評価するよう
   になりました。 引数に副作用がある場合も、それが重複して発生すること
   はなくなりました。

Py_XSETREF(dst, src)

   "Py_DECREF()" の代わりに "Py_XDECREF()" を使う "Py_SETREF" マクロの
   変種です。

   Added in version 3.6.

   バージョン 3.12 で変更: マクロの引数をそれぞれ 1 回だけ評価するよう
   になりました。 引数に副作用がある場合も、それが重複して発生すること
   はなくなりました。
