# 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__()`メソッドを 持つオブジェクトのみが格納されます。 13

  `__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`と同じ。）

#### Footnotes

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