"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 で変更: The optional *generation* argument was
   added.

   バージョン 2.6 で変更: The free lists maintained for a number of
   built-in types are cleared whenever a full collection or collection
   of the highest generation (2) is run.  Not all items in some free
   lists may be freed due to the particular implementation, in
   particular "int" and "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" がガベージコレクタに管理されていたら "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 で追加.

The following variable is provided for read-only access (you can
mutate its value but should not rebind it):

gc.garbage

   A list of objects which the collector found to be unreachable but
   could not be freed (uncollectable objects).  By default, this list
   contains only objects with "__del__()" methods. [1] Objects that
   have "__del__()" methods and are part of a reference cycle cause
   the entire reference cycle to be uncollectable, including objects
   not necessarily in the cycle but reachable only from it. Python
   doesn’t collect such cycles automatically because, in general, it
   isn’t possible for Python to guess a safe order in which to run the
   "__del__()" methods.  If you know a safe order, you can force the
   issue by examining the *garbage* list, and explicitly breaking
   cycles due to your objects within the list.  Note that these
   objects are kept alive even so by virtue of being in the *garbage*
   list, so they should be removed from *garbage* too.  For example,
   after breaking cycles, do "del gc.garbage[:]" to empty the list.
   It’s generally better to avoid the issue by not creating cycles
   containing objects with "__del__()" methods, and *garbage* can be
   examined in that case to verify that no such cycles are being
   created.

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

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

gc.DEBUG_STATS

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

gc.DEBUG_COLLECTABLE

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

gc.DEBUG_UNCOLLECTABLE

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

gc.DEBUG_INSTANCES

   When "DEBUG_COLLECTABLE" or "DEBUG_UNCOLLECTABLE" is set, print
   information about instance objects found.

gc.DEBUG_OBJECTS

   When "DEBUG_COLLECTABLE" or "DEBUG_UNCOLLECTABLE" is set, print
   information about objects other than instance objects found.

gc.DEBUG_SAVEALL

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

gc.DEBUG_LEAK

   The debugging flags necessary for the collector to print
   information about a leaking program (equal to "DEBUG_COLLECTABLE |
   DEBUG_UNCOLLECTABLE | DEBUG_INSTANCES | DEBUG_OBJECTS |
   DEBUG_SAVEALL").

-[ Footnotes ]-

[1] Prior to Python 2.2, the list contained all instance objects
    in unreachable cycles,  not only those with "__del__()" methods.
