3.2 `gc` -- ガベージコレクタインターフェース

gcモジュールは、インタプリタのビルドオプションで循環ガベージコレクタを有効にした場合のみ使用することができます（デフォルトで有効）。もし無効になっている場合にこのモジュールをインポートすると、 ImportErrorが発生します。

このモジュールは、循環ガベージコレクタの無効化・検出頻度の調整・デバッグオブションの設定などを行うインターフェースを提供します。また、検出した到達不能オブジェクトのうち、解放する事ができないオブジェクトを参照する事もできます。循環ガベージコレクタはPyhonの参照カウントを補うためのものですので、もしプログラム中で循環参照が発生しない事が明らかな場合には検出をする必要はありません。自動検出は、gc.disable()で停止する事ができます。メモリリークをデバッグするときには、 gc.set_debug(gc.DEBUG_LEAK)とします。

gcモジュールは、以下の関数を提供しています。

enable( ): 自動ガベージコレクションを有効にします。

disable( ): 自動ガベージコレクションを無効にします。

isenabled( ): 自動ガベージコレクションが有効なら真を返します。

collect( ): 全ての検出を行います。全ての世代を検査し、検出した到達不可オブジェクトの数を返します。

set_debug( flags): ガベージコレクションのデバッグフラグを設定します。デバッグ情報は sys.stderrに出力されます。デバッグフラグは、下の値の組み合わせを指定する事ができます。

get_debug( ): 現在のデバッグフラグを返します。

get_objects( ): 現在、追跡しているオブジェクトのリストを返します。このリストには、戻り値のリスト自身は含まれていません。バージョン 2.2 で新たに追加された仕様です。

set_threshold( threshold0[, threshold1[, threshold2]]): ガベージコレクションの閾値（検出頻度）を指定します。threshold0を0 にすると、検出は行われません。
GCは、オブジェクトを、走査された回数に従って3世代に分類します。新しいオブジェクトは最も若い（0世代）に分類されます。もし、そのオブジェクトがガベージコレクションで削除されなければ、次に古い世代に分類されます。もっとも古い世代は2世代で、この世代に属するオブジェクトは他の世代に移動しません。ガベージコレクタは、最後に検出を行ってから生成・削除したオブジェクトの数をカウントしており、この数によって検出を開始します。オブジェクトの生成数 - 削除数がthreshold0より大きくなると、検出を開始します。最初は0世代のオブジェクトのみが検査されます。0世代の検査がthreshold1回実行されると、1世代のオブジェクトの検査を行います。同様に、1世代がthreshold2回検査されると、 2世代の検査を行います。

get_threshold( ): 現在の検出閾値を、(threshold0, threshold1, threshold2)のタプルで返します。

get_referrers( *objs)

objsで指定したオブジェクトのいずれかを参照しているオブジェクトのリストを返します。この関数では、ガベージコレクションをサポートしているコンテナのみを返します。他のオブジェクトを参照していても、ガベージコレクションをサポートしていない拡張型は含まれません。

尚、戻り値のリストには、すでに参照されなくなっているが、循環参照の一部でまだガベージコレクションで回収されていないオブジェクトも含まれるので注意が必要です。有効なオブジェクトのみを取得する場合、 get_referrers()の前にcollect()を呼び出してください。

get_referrers()から返されるオブジェクトは作りかけや利用できない状態である場合があるので、利用する際には注意が必要です。 get_referrers()をデバッグ以外の目的で利用するのは避けてください。

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

get_referents( *objs): 引数で指定したオブジェクトのいずれかから参照されている、全てのオブジェクトのリストを返します。参照先のオブジェクトは、引数で指定したオブジェクトの Cレベルメソッドtp_traverseで取得し、全てのオブジェクトが直接到達可能な全てのオブジェクトを返すわけではありません。tp_traverseはガベージコレクションをサポートするオブジェクトのみが実装しており、ここで取得できるオブジェクトは循環参照の一部となる可能性のあるオブジェクトのみです。従って、例えば整数オブジェクトが直接到達可能であっても、このオブジェクトは戻り値には含まれません。バージョン 2.3 で新たに追加された仕様です。

以下の変数は読み込み専用です。(変更することはできますが、再バインドする事はできません。）

garbage

到達不能であることが検出されたが、解放する事ができないオブジェクトのリスト（回収不能オブジェクト）。デフォルトでは、__del__()メソッドを持つオブジェクトのみが格納されます。 ^3.1

__del__()メソッドを持つオブジェクトが循環参照に含まれている場合、その循環参照全体と、循環参照からのみ到達する事ができるオブジェクトは回収不能となります。このような場合には、Pythonは安全に__del__() を呼び出す順番を決定する事ができないため、自動的に解放することはできません。もし安全な解放順序がわかるのであれば、garbageリストを参照して循環参照を破壊する事ができます。循環参照を破壊した後でも、そのオブジェクトはgarbageリストから参照されているため、解放されません。解放するためには、循環参照を破壊した後、del gc.garbage[:]のように garbageからオブジェクトを削除する必要があります。一般的には __del__()を持つオブジェクトが循環参照の一部とはならないように配慮し、garbageはそのような循環参照が発生していない事を確認するために利用する方が良いでしょう。

DEBUG_SAVEALLが設定されている場合、全ての到達不能オブジェクトは解放されずにこのリストに格納されます。

以下はset_debug()に指定することのできる定数です。

DEBUG_STATS: 検出中に統計情報を出力します。この情報は、検出頻度を最適化する際に有益です。

DEBUG_COLLECTABLE: 見つかった回収可能オブジェクトの情報を出力します。

DEBUG_UNCOLLECTABLE: 見つかった回収不能オブジェクト（到達不能だが、ガベージコレクションで解放する事ができないオブジェクト）の情報を出力します。回収不能オブジェクトは、garbadeリストに追加されます。

DEBUG_INSTANCES: DEBUG_COLLECTABLEかDEBUG_UNCOLLECTABLEが設定されている場合、見つかったインスタンスオブジェクトの情報を出力します。

DEBUG_OBJECTS: DEBUG_COLLECTABLEかDEBUG_UNCOLLECTABLEが設定されている場合、見つかったインスタンスオブジェクト以外のオブジェクトの情報を出力します。

DEBUG_SAVEALL: 設定されている場合、全ての到達不能オブジェクトは解放されずに garbageに追加されます。これはプログラムのメモリリークをデバッグするときに便利です。

DEBUG_LEAK: プログラムのメモリリークをデバッグするときに指定します。（DEBUG_COLLECTABLE | DEBUG_UNCOLLECTABLE | DEBUG_INSTANCES | DEBUG_OBJECTS | DEBUG_SAVEALLと同じ。）

... 持つオブジェクトのみが格納されます。^3.1: Python 2.2より前のバージョンでは、__del__()メソッドを持つオブジェクトだけでなく、全ての到達不能オブジェクトが格納されていた。）

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

3.2 gc -- ガベージコレクタ インターフェース

3.2 `gc` -- ガベージコレクタインターフェース