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

======================================================================

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

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

gc.enable()

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

gc.disable()

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

gc.isenabled()

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

gc.collect(generation=2)

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

   ビルトイン型が持っている free list は、フルGCか最高世代(2)のGCの時
   にクリアされます。 "float" など、実装によって幾つかの free list で
   は全ての要素が解放されるわけではありません。

gc.set_debug(flags)

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

gc.get_debug()

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

gc.get_objects(generation=None)

   Returns a list of all objects tracked by the collector, excluding
   the list returned. If *generation* is not None, return only the
   objects tracked by the collector that are in that generation.

   バージョン 3.8 で変更: 新しい *generation* パラメータ。

   引数 "generation" で 監査イベント "gc.get_objects" を送出します。

gc.get_stats()

   インタプリタが開始してからの、世代ごと回収統計を持つ辞書の、3 世代
   ぶんのリストを返します。キーの数は将来変わるかもしれませんが、現在
   のところそれぞれの辞書には以下の項目が含まれています:

   * "collections" は、この世代が検出を行った回数です;

   * "collected" は、この世代内で回収されたオブジェクトの総数です;

   * "uncollectable" は、この世代内で回収不能であることがわかった (そ
     してそれゆえに "garbage" リストに移動した) オブジェクトの総数です
     。

   バージョン 3.4 で追加.

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

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

   The GC classifies objects into three generations depending on how
   many collection sweeps they have survived.  New objects are placed
   in the youngest generation (generation "0").  If an object survives
   a collection it is moved into the next older generation.  Since
   generation "2" is the oldest generation, objects in that generation
   remain there after a collection.  In order to decide when to run,
   the collector keeps track of the number object allocations and
   deallocations since the last collection.  When the number of
   allocations minus the number of deallocations exceeds *threshold0*,
   collection starts.  Initially only generation "0" is examined.  If
   generation "0" has been examined more than *threshold1* times since
   generation "1" has been examined, then generation "1" is examined
   as well. With the third generation, things are a bit more
   complicated, see Collecting the oldest generation for more
   information.

gc.get_count()

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

gc.get_threshold()

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

gc.get_referrers(*objs)

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

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

   警告:

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

   引数 "objs" を指定して 監査イベント "gc.get_referrers" を送出します
   。

gc.get_referents(*objs)

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

   引数 "objs" を指定して 監査イベント "gc.get_referents" を送出します
   。

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

   バージョン 3.1 で追加.

gc.is_finalized(obj)

   Returns "True" if the given object has been finalized by the
   garbage collector, "False" otherwise.

      >>> x = None
      >>> class Lazarus:
      ...     def __del__(self):
      ...         global x
      ...         x = self
      ...
      >>> lazarus = Lazarus()
      >>> gc.is_finalized(lazarus)
      False
      >>> del lazarus
      >>> gc.is_finalized(x)
      True

   バージョン 3.9 で追加.

gc.freeze()

   Freeze all the objects tracked by gc - move them to a permanent
   generation and ignore all the future collections. This can be used
   before a POSIX fork() call to make the gc copy-on-write friendly or
   to speed up collection. Also collection before a POSIX fork() call
   may free pages for future allocation which can cause copy-on-write
   too so it's advised to disable gc in parent process and freeze
   before fork and enable gc in child process.

   バージョン 3.7 で追加.

gc.unfreeze()

   Permanent世代領域にあるオブジェクトを解凍します。つまり、最も古い世
   代へ戻します。

   バージョン 3.7 で追加.

gc.get_freeze_count()

   Permanent世代領域にあるオブジェクトの数を返します。

   バージョン 3.7 で追加.

以下の変数は読み出し専用アクセスのために提供されています。(この変数を
操作することはできますが、その値は記憶されません):

gc.garbage

   到達不能であることが検出されたが、解放する事ができないオブジェクト
   のリスト（回収不能オブジェクト）。Python 3.4 からは、"NULL" でない
   "tp_del" スロットを持つ C 拡張型のインスタンスを使っている場合を除
   き、このリストはほとんど常に空であるはずです。

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

   バージョン 3.2 で変更: *インタプリタシャットダウン* 時にこのリスト
   が空でない場合、(デフォルトでは黙りますが) "ResourceWarning" が発行
   されます。 "DEBUG_UNCOLLECTABLE" がセットされていると、加えて回収不
   能オブジェクトを出力します。

   バージョン 3.4 で変更: **PEP 442** に従い、 "__del__()" メソッドを
   持つオブジェクトはもう "gc.garbage" に行き着くことはありません。

gc.callbacks

   ガベージコレクタの起動前と終了後に呼び出されるコールバック関数のリ
   スト。コールバックは *phase* と *info* の2つの引数で呼び出されます
   。

   *phase* は以下 2 つのいずれかです:

      "start": ガベージコレクションを始めます。

      "stop": ガベージコレクションが終了しました。

   *info* はコールバックに付加情報を提供する辞書です。現在のところ以下
   のキーが定義されています:

      "generation": 回収される最も古い世代。

      "collected": *phase* が "stop" のとき、正常に回収されたオブジェ
      クトの数。

      "uncollectable": *phase* が "stop" のとき、回収出来ずに
      "garbage" リストに入れられたオブジェクトの数。

   アプリケーションは自身のコールバックをこのリストに追加出来ます。基
   本的なユースケースは以下のようなものでしょう:

      世代が回収される頻度やガベージコレクションにかかった時間の長さと
      いった、ガベージコレクションの統計情報を集めます。

      "garbage" に回収できない独自の型のオブジェクトが現れたとき、アプ
      リケーションがそれらを特定し消去できるようにする。

   バージョン 3.3 で追加.

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

gc.DEBUG_STATS

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

gc.DEBUG_COLLECTABLE

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

gc.DEBUG_UNCOLLECTABLE

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

   バージョン 3.2 で変更: *インタプリタシャットダウン* 時に "garbage"
   リストが空でない場合に、その中身の出力も行います。

gc.DEBUG_SAVEALL

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

gc.DEBUG_LEAK

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