28.12. "gc" --- ガベージコレクタインターフェース
************************************************

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

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

gc.enable()

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

gc.disable()

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

gc.isenabled()

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

gc.collect([generation])

   引数を指定しない場合は、全ての検出を行います。オプションの引数
   *generation* は、どの世代を検出するかを (0 から 2 までの) 整数値で
   指定します。無効な世代番号を指定した場合は "ValueError" が発生しま
   す。検出した到達不可オブジェクトの数を返します。

   バージョン 2.5 で変更: オプションの引数 *generation* が追加されまし
   た.

   バージョン 2.6 で変更: 幾つかの組み込み型のフリーリストは、最高(第
   二)世代のGC、あるいはフルGCが実行されるたびにクリアされます。幾つか
   の型(特に "int" と "float")では、実装によっては、フリーリスト内の全
   てのオブジェクトが解放されるとは限りません。

gc.set_debug(flags)

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

gc.get_debug()

   現在のデバッグフラグを返します。

gc.get_objects()

   現在追跡しているオブジェクトのリストを返します。このリストには、戻
   り値のリスト自身は含まれていません。

   バージョン 2.2 で追加.

gc.set_threshold(threshold0[, threshold1[, threshold2]])

   ガベージコレクションの閾値（検出頻度）を指定します。 *threshold0*
   を 0 にすると、検出は行われません。

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

gc.get_count()

   現在の検出数を、 "(count0, count1, count2)" のタプルで返します。

   バージョン 2.5 で追加.

gc.get_threshold()

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

gc.get_referrers(*objs)

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

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

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

   バージョン 2.2 で追加.

gc.get_referents(*objs)

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

   バージョン 2.3 で追加.

gc.is_tracked(obj)

   "obj" がGCに管理されていたら "True" を返し、それ以外の場合は
   "False" を返します。一般的なルールとして、アトミックな(訳注:他のオ
   ブジェクトを参照しないで単一で値を表す型。 int や str など)型のイン
   スタンスは管理されず、それ以外の型 (コンテナ型、ユーザー定義型など)
   のインスタンスは管理されます。しかし、いくつかの型では専用の最適化
   を行い、シンプルなインスタンスの場合に GCのオーバーヘッドを減らして
   います。 (例: 全ての key と value がアトミック型の値である dict)

      >>> gc.is_tracked(0)
      False
      >>> gc.is_tracked("a")
      False
      >>> gc.is_tracked([])
      True
      >>> gc.is_tracked({})
      False
      >>> gc.is_tracked({"a": 1})
      False
      >>> gc.is_tracked({"a": []})
      True

   バージョン 2.7 で追加.

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

gc.garbage

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

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

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

gc.DEBUG_STATS

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

gc.DEBUG_COLLECTABLE

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

gc.DEBUG_UNCOLLECTABLE

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

gc.DEBUG_INSTANCES

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

gc.DEBUG_OBJECTS

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

gc.DEBUG_SAVEALL

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

gc.DEBUG_LEAK

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

-[ 脚注 ]-

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