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

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

ここで説明しているインタフェースの使い方を示した例は、 Python の拡張と埋め込み の ``循環参照の収集をサポートする'' にあります。 コンテナ型を作るには、型オブジェクトの tp_flags フィールド にPy_TPFLAGS_HAVE_GC フラグがなくてはならず、 tp_traverse ハンドラの実装を提供しなければなりません。 実装する型のインスタンスを変更可能なオブジェクトにするなら、 tp_clear の実装も提供しなければなりません。

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

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

  1. オブジェクトのメモリは PyObject_GC_New() または PyObject_GC_VarNew() で確保しなければなりません。

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

TYPEPyObject_GC_New(TYPE, PyTypeObject *type)
PyObject_New() に似ていますが、 Py_TPFLAGS_HAVE_GC のセットされたコンテナオブジェクト 用です。

TYPEPyObject_GC_NewVar(TYPE, PyTypeObject *type, int size)
PyObject_NewVar() に似ていますが、 Py_TPFLAGS_HAVE_GC のセットされたコンテナオブジェクト 用です。

PyVarObject * PyObject_GC_Resize(PyVarObject *op, int)
PyObject_NewVar() が確保したオブジェクトのメモリを リサイズします。リサイズされたオブジェクトを返します。 失敗すると NULL を返します。

void PyObject_GC_Track(PyObject *op)
ガベージコレクタが追跡しているコンテナオブジェクトの集合に オブジェクト op を追加します。ガベージコレクタの動作する 回数は予測不能なので、追加対象にするオブジェクトは追跡されている 間ずっと有効なオブジェクトでなければなりません。 この関数は、通常コンストラクタの最後付近で、tp_traverse ハンドラ以降の全てのフィールドが有効な値になった時点で呼び出さねば なりません。

void _PyObject_GC_TRACK(PyObject *op)
PyObject_GC_Track() のマクロ版です。拡張モジュールに 使ってはなりません。

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

  1. 他のコンテナを参照しているフィールドを無効化する前に、 PyObject_GC_UnTrack() を呼び出さねばなりません。
  2. オブジェクトのメモリは PyObject_GC_Del() で解放しなければなりません。

void PyObject_GC_Del(PyObject *op)
PyObject_GC_New()PyObject_GC_NewVar() を使って確保されたメモリを解放します。

void PyObject_GC_UnTrack(PyObject *op)
ガベージコレクタが追跡しているコンテナオブジェクトの集合から オブジェクト op を除去します。PyObject_GC_Track() を呼び出して、除去したオブジェクトを再度追跡対象セットに追加 できるので注意してください。メモリ解放関数 (deallocator, tp_dealloc ハンドラ) は、tp_traverse ハンドラが 使用しているフィールドのいずれかが無効化されるよりも 以前にオブジェクトに対して呼び出されていなければなりません。

void _PyObject_GC_UNTRACK(PyObject *op)
PyObject_GC_UnTrack() のマクロ版です。拡張モジュールに 使ってはなりません。

tp_traverse ハンドラは以下の型を持つ関数を引数の一つとして とります:

int (*visitproc)(PyObject *object, void *arg)
tp_traverse ハンドラに渡すビジタ関数 (visitor function) の型です。この関数は追跡すべきオブジェクトを object に、 tp_traverse ハンドラの第三引数を arg にして呼び出され ます。Python のコア部分では、ガベージコレクションの実装に複数の ビジタ関数を使っています。ユーザが独自にビジタ関数を書く必要がある とは想定されていません。

tp_traverse ハンドラは以下の型でなければなりません:

int (*traverseproc)(PyObject *self, visitproc visit, void *arg)
コンテナオブジェクトのためのトラバーサル関数 (traversal function) です。 実装では、self に直接入っている各オブジェクトに対してvisit 関数を呼び出さねばなりません。このとき、visit へのパラメタは コンテナに入っている各オブジェクトと、このハンドラに渡された arg の値です。visit 関数は NULL オブジェクトを引数に 渡して呼び出してはなりません。visit が非ゼロの値を返す場合、 エラーが発生し、戻り値をそのまま返すようににしなければなりません。

tp_traverse ハンドラの作成を単純化するため、Py_VISIT() マクロが提供されています。このマクロを使うには、tp_traverse の 実装で、引数を visit および arg という名前にしておかねば なりません:

void Py_VISIT(PyObject *o)
引数 o および arg を使ってvisit コールバックを呼び出し ます。visit が非ゼロの値を返した場合、その値をそのまま返します。 このマクロを使えば、tp_traverse ハンドラは以下のようになります:

static int
my_traverse(Noddy *self, visitproc visit, void *arg)
{
    Py_VISIT(self->foo);
    Py_VISIT(self->bar);
    return 0;
}

バージョン 2.4 で 新たに追加 された仕様です。

tp_clear ハンドラは inquiry 型にするか、 オブジェクトが変更不能の場合には NULL にしなければなりません。 NULL if the object is immutable.

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

ご意見やご指摘をお寄せになりたい方は、 このドキュメントについて... をご覧ください。