循環参照ガベージコレクションをサポートする
******************************************

Python が循環参照を含むガベージの検出とコレクションをサポートするには
、他のオブジェクトに対する "コンテナ" (他のオブジェクトには他のコンテ
ナも含みます) となるオブジェクト型によるサポートが必要です。他のオブジ
ェクトに対する参照を記憶しないオブジェクトや、(数値や文字列のような)
アトム型 (atomic type) への参照だけを記憶するような型では、ガベージコ
レクションに際して特別これといったサポートを提供する必要はありません。

コンテナ型を作成するには、型オブジェクトの "tp_flags" フィールドに
"Py_TPFLAGS_HAVE_GC" を含め、"tp_traverse" ハンドラを実装する必要があ
ります。 型のインスタンスが変更可能な場合は、"tp_clear" も実装する必要
があります。

"Py_TPFLAGS_HAVE_GC"
   このフラグをセットした型のオブジェクトは、この節に述べた規則に適合
   しなければなりません。簡単のため、このフラグをセットした型のオブジ
   ェクトをコンテナオブジェクトと呼びます。

コンテナ型のコンストラクタは以下の二つの規則に適合しなければなりません
:

1. オブジェクトのメモリは "PyObject_GC_New" または
   "PyObject_GC_NewVar" で割り当てなければなりません。

2. 他のコンテナへの参照が入るかもしれないフィールドが全て初期化された
   ら、すぐに "PyObject_GC_Track()" を呼び出さなければなりません。

同様に、オブジェクトのメモリ解放関数も以下の二つの規則に適合しなければ
なりません:

1. 他のコンテナを参照しているフィールドを無効化する前に、
   "PyObject_GC_UnTrack()" を呼び出さなければなりません。

2. オブジェクトのメモリは "PyObject_GC_Del()" で解放しなければなりませ
   ん。

   警告:

     If a type adds the Py_TPFLAGS_HAVE_GC, then it *must* implement
     at least a "tp_traverse" handler or explicitly use one from its
     subclass or subclasses."PyType_Ready()"、または
     "PyType_FromSpecWithBases()" や "PyType_FromSpec()" など間接的に
     この関数を呼び出す API を使った際、 ガベージコレクタのプロトコル
     を実装するクラスを継承しており、派生クラスに "Py_TPFLAGS_HAVE_GC"
     フラグが含まれて *いない* 場合は、 インタープリタが "tp_flags"、
     "tp_traverse"、"tp_clear" フィールドを自動的に設定します。

PyObject_GC_New(TYPE, typeobj)

   "PyObject_New" と同様ですが、"Py_TPFLAGS_HAVE_GC" フラグが設定され
   たコンテナオブジェクト用です。

   オブジェクトのメモリを割り当てるためにこれを直接呼び出してはいけま
   せん。 代わりに型の "tp_alloc" スロットを呼び出してください。

   型の "tp_alloc" スロットには、このマクロを呼び出すだけの独自の関数
   よりも "PyType_GenericAlloc()" を設定することが推奨されます。

   このマクロで割り当てたメモリは "PyObject_GC_Del()" で解放しなければ
   なりません (通常はオブジェクトの "tp_free" スロットを介して呼び出し
   ます)。

   参考:

     * "PyObject_GC_Del()"

     * "PyObject_New"

     * "PyType_GenericAlloc()"

     * "tp_alloc"

PyObject_GC_NewVar(TYPE, typeobj, size)

   "PyObject_NewVar" と同様ですが、"Py_TPFLAGS_HAVE_GC" フラグが設定さ
   れたコンテナオブジェクト用です。

   オブジェクトのメモリを割り当てるためにこれを直接呼び出してはいけま
   せん。 代わりに型の "tp_alloc" スロットを呼び出してください。

   型の "tp_alloc" スロットには、このマクロを呼び出すだけの独自の関数
   よりも "PyType_GenericAlloc()" を設定することが推奨されます。

   このマクロで割り当てたメモリは "PyObject_GC_Del()" で解放しなければ
   なりません (通常はオブジェクトの "tp_free" スロットを介して呼び出し
   ます)。

   参考:

     * "PyObject_GC_Del()"

     * "PyObject_NewVar"

     * "PyType_GenericAlloc()"

     * "tp_alloc"

PyObject *PyUnstable_Object_GC_NewWithExtraData(PyTypeObject *type, size_t extra_size)

   *これは Unstable APIです。マイナーリリースで予告なく変更されること
   があります。*

   "PyObject_GC_New" と同様ですが、オブジェクトの末尾 (オフセット
   "tp_basicsize") に *extra_size* バイトを割り当てます。 割り当てたメ
   モリは "Python オブジェクトのヘッダー" を除いてゼロで初期化されます
   。

   追加データはオブジェクトとともに解放されますが、それ以外の管理は
   Python では行いません。

   この関数で割り当てたメモリは "PyObject_GC_Del()" で解放しなければな
   りません (通常はオブジェクトの "tp_free" スロットを介して呼び出しま
   す)。

   警告:

     インスタンスの後ろに追加データを確保する最終的な仕組みが未定のた
     め、この関数は不安定とされています。 可変個数のフィールドを割り当
     てるには、代わりに "PyVarObject" と "tp_itemsize" を使うことが推
     奨されます。

   Added in version 3.12.

PyObject_GC_Resize(TYPE, op, newsize)

   Resize an object allocated by "PyObject_NewVar". Returns the
   resized object of type "TYPE*" (refers to any C type) or "NULL" on
   failure.

   *op* の型は PyVarObject* でなければならず、まだコレクタの追跡対象に
   なっていてはいけません。 *newsize* の型は "Py_ssize_t" でなければな
   りません。

void PyObject_GC_Track(PyObject *op)
    * 次に属します: Stable ABI.*

   オブジェクト *op* を、コレクタが追跡するコンテナオブジェクトの集合
   に追加します。 コレクタは予期しないタイミングで実行される可能性があ
   るため、追跡中のオブジェクトは有効な状態でなければなりません。
   "tp_traverse" ハンドラがたどるすべてのフィールドが有効になった時点
   で、通常はコンストラクタの終わり近くで呼び出してください。

int PyObject_IS_GC(PyObject *obj)

   オブジェクトがガベージコレクタのプロトコルを実装している場合はゼロ
   以外、そうでなければ 0 を返します。

   この関数が 0 を返す場合、そのオブジェクトをガベージコレクタの追跡対
   象にはできません。

int PyObject_GC_IsTracked(PyObject *op)
    * 次に属します: Stable ABI (バージョン 3.9 より).*

   *op* の型が GC プロトコルを実装しており、*op* が現在ガベージコレク
   タに追跡されている場合は 1 を、それ以外の場合は 0 を返します。

   Python の "gc.is_tracked()" 関数に相当します。

   Added in version 3.9.

int PyObject_GC_IsFinalized(PyObject *op)
    * 次に属します: Stable ABI (バージョン 3.9 より).*

   *op* の型が GC プロトコルを実装しており、*op* がガベージコレクタに
   よってすでにファイナライズされている場合は 1 を、それ以外の場合は 0
   を返します。

   Python の "gc.is_finalized()" 関数に相当します。

   Added in version 3.9.

void PyObject_GC_Del(void *op)
    * 次に属します: Stable ABI.*

   "PyObject_GC_New" または "PyObject_GC_NewVar" でオブジェクトに割り
   当てたメモリを解放します。

   オブジェクトのメモリを解放するためにこれを直接呼び出してはいけませ
   ん。 代わりに型の "tp_free" スロットを呼び出してください。

   "PyObject_New"、"PyObject_NewVar"、または関連する割り当て関数で割り
   当てたメモリには使わないでください。 代わりに "PyObject_Free()" を
   使ってください。

   参考:

     * "PyObject_Free()" はこの関数の非 GC 版です。

     * "PyObject_GC_New"

     * "PyObject_GC_NewVar"

     * "PyType_GenericAlloc()"

     * "tp_free"

void PyObject_GC_UnTrack(void *op)
    * 次に属します: Stable ABI.*

   オブジェクト *op* を、コレクタによって追跡されるオブジェクトの集合
   から除去します。このオブジェクトに対して "PyObject_GC_Track()" を再
   度呼び出して、追跡されるオブジェクトの集合に戻すことも可能です。
   "tp_traverse" ハンドラの対象となるフィールドが正しくない状態になる
   前に、デアロケータ ("tp_dealloc" ハンドラ) はオブジェクトに対して、
   この関数を呼び出すべきです。

バージョン 3.8 で変更: "_PyObject_GC_TRACK()" マクロと
"_PyObject_GC_UNTRACK()" マクロは、公開 C API から削除されました。

"tp_traverse" ハンドラはこの型の関数パラメータを受け取ります:

typedef int (*visitproc)(PyObject *object, void *arg)
    * 次に属します: Stable ABI.*

   "tp_traverse" ハンドラに渡されるビジター関数 (visitor function) の
   型です。この関数は、探索するオブジェクトを *object* として、
   "tp_traverse" ハンドラの第 3 引数を *arg* として呼び出します。
   Python のコアはいくつかのビジター関数を使って、ゴミとなった循環参照
   を検出する仕組みを実装します; ユーザが自身のためにビジター関数を書
   く必要が出てくることはないでしょう。

"tp_clear" ハンドラは "inquiry" 型であるか、オブジェクトが不変
(immutable) な場合は "NULL" でなければなりません。

typedef int (*inquiry)(PyObject *self)
    * 次に属します: Stable ABI.*

   循環参照を形成しているとおぼしき参照群を放棄します。変更不可能なオ
   ブジェクトは循環参照を直接形成することが決してないので、この関数を
   定義する必要はありません。このメソッドを呼び出した後でもオブジェク
   トは有効なままでなければならないので注意してください (参照に対して
   "Py_DECREF()" を呼ぶだけにしないでください)。ガベージコレクタは、オ
   ブジェクトが循環参照を形成していることを検出した際にこのメソッドを
   呼び出します。


巡回
====

"tp_traverse" ハンドラは次の型を持っていなければなりません:

typedef int (*traverseproc)(PyObject *self, visitproc visit, void *arg)
    * 次に属します: Stable ABI.*

   Traversal function for a garbage-collected object, used by the
   garbage collector to detect reference cycles. Implementations must
   call the *visit* function for each object directly contained by
   *self*, with the parameters to *visit* being the contained object
   and the *arg* value passed to the handler.  The *visit* function
   must not be called with a "NULL" object argument.  If *visit*
   returns a non-zero value, that value should be returned
   immediately. Otherwise, return zero.

   典型的な "tp_traverse" 関数は、インスタンスが所有する Python オブジ
   ェクトのメンバーそれぞれに対して、便利なマクロ "Py_VISIT()" を呼び
   出します。 例えば、次は "threading.local" クラスの巡回関数です (や
   や古い実装です)。

      static int
      local_traverse(PyObject *op, visitproc visit, void *arg)
      {
          localobject *self = (localobject *) op;
          Py_VISIT(Py_TYPE(self));
          Py_VISIT(self->args);
          Py_VISIT(self->kw);
          Py_VISIT(self->dict);
          return 0;
      }

   注釈:

     "Py_VISIT()" を使うには、"local_traverse()" の *visit* 引数と
     *arg* 引数を正確にこの名前にする必要があります。 任意の名前を付け
     てはいけません。

   ヒープに割り当てられた型 のインスタンスは、自分の型への参照を保持し
   ます。 したがって、その巡回関数では型も巡回する必要があります。

      Py_VISIT(Py_TYPE(self));

   代わりに、ヒープに割り当てられた基底クラス (または適切であれば他の
   ヒープに割り当てられた型) の "tp_traverse" を呼び出して、この処理を
   委譲することもできます。 どちらも行わない場合、型オブジェクトがガベ
   ージコレクションで回収されない可能性があります。

   "tp_flags" フィールドに "Py_TPFLAGS_MANAGED_DICT" ビットが設定され
   ている場合、巡回関数は次のように "PyObject_VisitManagedDict()" を呼
   び出す必要があります。

      int err = PyObject_VisitManagedDict((PyObject*)self, visit, arg);
      if (err) {
          return err;
      }

   Only the members that the instance *owns* (by having *strong
   references* to them) must be visited. For instance, if an object
   supports weak references via the "tp_weaklist" slot, the pointer
   supporting the linked list (what *tp_weaklist* points to) must
   **not** be visited as the instance does not directly own the weak
   references to itself.

   巡回関数には次の制約があります。

   警告:

     巡回関数は副作用を起こしてはいけません。 実装では、直接的にも間接
     的にも、Python オブジェクトの参照カウントを変更したり、Python オ
     ブジェクトを作成または破棄したりしてはいけません。

   つまり、Python C API の *ほとんど* の関数は使用できません。 新しい
   例外を送出したり、結果のオブジェクトへの新しい参照を返したり、内部
   処理で副作用を起こしたりするためです。 また、特に明記されていない限
   り、たまたま副作用がない関数でも、将来のバージョンで予告なく副作用
   を起こすようになる可能性があります。

   安全に使える関数の一覧は、後述の 専用の節 を参照してください。

   If an error occurs during traversal, ignore it and return 0. If
   "tp_traverse" fails to visit some strong references, garbage
   reference cycles involving the skipped references will not be
   reliably broken, but correctness won't be affected. For example, if
   traversal requires a lock that cannot be acquired promptly, skip
   the traversal. The garbage collector will visit your object again
   in a future pass.

   注釈:

     循環参照に関与しないことを証明できるメンバーについては、
     "Py_VISIT()" の呼び出しを省略できます。 上の "local_traverse" の
     例には "self->key" メンバーもありますが、この値は "NULL" または
     Python の文字列に限られるので、循環参照の一部にはなりません。一方
     、メンバーが循環参照の一部にならないと分かっていても、デバッグの
     ために巡回しておくと、"gc" モジュールの "get_referents()" 関数の
     結果にそのメンバーを含められます。

   注釈:

     "tp_traverse" 関数は、どのスレッドからも呼び出される可能性があり
     ます。

     ガベージコレクションは「stop-the-world」の操作です。 *フリースレ
     ッド* ビルドでも、"tp_traverse" ハンドラの実行中に *アタッチされ
     ている* スレッド状態は 1 つだけです。

   バージョン 3.9 で変更: ヒープに割り当てられた型は、"tp_traverse" で
   "Py_TYPE(self)" を巡回することが期待されます。 以前のバージョンの
   Python では、バグ 40217 によって、この処理がサブクラスのクラッシュ
   を引き起こす場合があります。

"tp_traverse" ハンドラを簡単に記述できるように、"Py_VISIT()" マクロが
用意されています。 このマクロを使うには、"tp_traverse" の実装で引数の
名前を正確に *visit* と *arg* にする必要があります。

Py_VISIT(o)

   PyObject* 型の *o* が "NULL" でなければ、*o* と *arg* を引数として
   *visit* コールバックを呼び出します。 *visit* がゼロ以外の値を返した
   場合は、その値を返します。

   おおむね次のコードに相当します。

      #define Py_VISIT(o)                             \
         if (o) {                                    \
            int visit_result = visit(o, arg);         \
            if (visit_result != 0) {                  \
               return visit_result;                   \
            }                                         \
         }


巡回中に安全に使える関数
------------------------

次の関数とマクロは "tp_traverse" ハンドラ内で安全に使えます。

* "tp_traverse" に渡された *visit* 関数

* "Py_VISIT()"

* "Py_SIZE()"

* "Py_TYPE()": "tp_traverse" ハンドラから呼び出した場合、"Py_TYPE()"
  の結果はそのハンドラの呼び出し中ずっと有効です

* "PyObject_VisitManagedDict()"

* "PyObject_TypeCheck()", "PyType_IsSubtype()", "PyType_HasFeature()"

* "Py*<type>*_Check" と "Py*<type>*_CheckExact"。 例えば
  "PyTuple_Check()"

* 「DuringGC」関数


「DuringGC」関数
----------------

次の関数は "tp_traverse" ハンドラ内で *のみ* 使うべきです。 他の文脈で
呼び出すと、意図しない結果を招く可能性があります。

これらの関数は "_DuringGC" サフィックスのない対応する関数と同様に動作
しますが、副作用を起こさないことが保証され、失敗しても例外を設定せず、
個別の説明に記載されているとおり *借用参照* を返す、または設定します。

これらの関数は失敗する ("NULL" または "-1" を返す) ことがありますが、
例外を設定しないのでエラー情報は得られません。 場合によっては、失敗と
成功時の "NULL" の結果を区別できません。

void *PyObject_GetTypeData_DuringGC(PyObject *o, PyTypeObject *cls)
void *PyObject_GetItemData_DuringGC(PyObject *o)
void *PyType_GetModuleState_DuringGC(PyTypeObject *type)
void *PyModule_GetState_DuringGC(PyObject *module)
int PyModule_GetToken_DuringGC(PyObject *module, void **result)
    * 次に属します: Stable ABI (バージョン 3.15 より).*

   共通の情報は 「DuringGC」関数 を参照してください。

   Added in version 3.15.

   参考:

     "PyObject_GetTypeData()", "PyObject_GetItemData()",
     "PyType_GetModuleState()", "PyModule_GetState()",
     "PyModule_GetToken()", "PyType_GetBaseByToken()"

int PyType_GetBaseByToken_DuringGC(PyTypeObject *type, void *tp_token, PyTypeObject **result)
    * 次に属します: Stable ABI (バージョン 3.15 より).*

   共通の情報は 「DuringGC」関数 を参照してください。

   **result* には強参照ではなく *借用参照* を設定します。 この参照は
   "tp_traverse" ハンドラの呼び出し中ずっと有効です。

   Added in version 3.15.

   参考: "PyType_GetBaseByToken()"

PyObject *PyType_GetModule_DuringGC(PyTypeObject *type)
PyObject *PyType_GetModuleByToken_DuringGC(PyTypeObject *type, const void *mod_token)
    *戻り値: 借用参照。** 次に属します: Stable ABI (バージョン 3.15 よ
   り).*

   共通の情報は 「DuringGC」関数 を参照してください。

   これらの関数は *借用参照* を返します。 この参照は "tp_traverse" ハ
   ンドラの呼び出し中ずっと有効です。

   Added in version 3.15.

   参考: "PyType_GetModule()", "PyType_GetModuleByToken()"


ガベージコレクタの状態を制御する
================================

C API は、ガベージコレクションの実行を制御するために次の関数を提供しま
す。

Py_ssize_t PyGC_Collect(void)
    * 次に属します: Stable ABI.*

   ガベージコレクタが有効な場合に、完全なガベージコレクションを実行し
   ます ("gc.collect()" は無条件に実行する点に注意してください)。

   回収したオブジェクト数と、到達不能なのに回収できないオブジェクト数
   の合計を返します。 ガベージコレクタが無効か、すでに回収を実行してい
   る場合は、直ちに "0" を返します。 ガベージコレクション中のエラーは
   "sys.unraisablehook" に渡されます。 この関数は例外を送出しません。

int PyGC_Enable(void)
    * 次に属します: Stable ABI (バージョン 3.10 より).*

   ガベージコレクタを有効にします。 "gc.enable()" に相当します。 以前
   の状態を返し、無効だった場合は 0、有効だった場合は 1 です。

   Added in version 3.10.

int PyGC_Disable(void)
    * 次に属します: Stable ABI (バージョン 3.10 より).*

   ガベージコレクタを無効にします。 "gc.disable()" に相当します。 以前
   の状態を返し、無効だった場合は 0、有効だった場合は 1 です。

   Added in version 3.10.

int PyGC_IsEnabled(void)
    * 次に属します: Stable ABI (バージョン 3.10 より).*

   ガベージコレクタの状態を問い合わせます。 "gc.isenabled()" に相当し
   ます。 現在の状態を返し、無効の場合は 0、有効の場合は 1 です。

   Added in version 3.10.


ガベージコレクタの状態を問い合わせる
====================================

C API は、ガベージコレクタの情報を問い合わせるために次のインターフェー
スを提供します。

void PyUnstable_GC_VisitObjects(gcvisitobjects_t callback, void *arg)

   *これは Unstable APIです。マイナーリリースで予告なく変更されること
   があります。*

   生存しているすべての GC 対応オブジェクトに対して、指定された
   *callback* を実行します。 *callback* を呼び出すたびに *arg* をその
   まま渡します。

   警告:

     コールバックがオブジェクトを割り当てたり解放したりした場合、それ
     らのオブジェクトが巡回されるかどうかは未定義です。処理中はガベー
     ジコレクションが無効になります。 コールバック内で明示的にコレクシ
     ョンを実行すると、同じオブジェクトを複数回巡回したり、まったく巡
     回しなかったりするなど、未定義の動作を引き起こす可能性があります
     。

   Added in version 3.12.

typedef int (*gcvisitobjects_t)(PyObject *object, void *arg)

   "PyUnstable_GC_VisitObjects()" に渡すビジター関数の型です。 *arg*
   は "PyUnstable_GC_VisitObjects" に渡された *arg* と同じです。 反復
   処理を続けるには "1"、停止するには "0" を返してください。 その他の
   戻り値は現在予約されており、これら以外の値を返した場合の動作は未定
   義です。

   Added in version 3.12.
