"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.collect()" を呼び出
   した場合の動作は未定義です。

   バージョン 3.14 で変更: "generation=1" は回収を段階的に進めるように
   なりました。

   バージョン 3.14.5 で変更: "generation=1" は中間の世代を回収するよう
   になりました。

gc.set_debug(flags)

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

gc.get_debug()

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

gc.get_objects(generation=None)

   ガベージコレクタが追跡しているすべてのオブジェクトのリストを返しま
   す。 返すリスト自体は含まれません。 *generation* が "None" でない場
   合は、その世代に属する追跡対象のオブジェクトだけを返します。

   警告:

     "get_objects()" が返すオブジェクトには、まだ構築中で一時的に不正
     な状態にあるものも含まれ得るため、使用時には注意が必要です。
     "get_objects()" をデバッグ以外の目的で使うことは避けてください。

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

   バージョン 3.14 で変更: 世代 1 が削除されました。

   バージョン 3.14.5 で変更: 3.13 の GC の動作を維持するために、世代 1
   が再導入されました。

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

gc.get_stats()

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

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

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

   * "uncollectable" は、この世代で回収不能と判定された (そのため
     "garbage" リストに移された) オブジェクトの総数です。

   * "candidates" は、この世代で回収の候補として参照をたどったオブジェ
     クトの総数です。

   * "duration" は、この世代の回収に費やした合計時間 (秒) です。

   Added in version 3.4.

   バージョン 3.15 で変更: "duration" と "candidates" が追加されました
   。

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

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

   GC は、何回の回収を生き残ったかに応じてオブジェクトを 3 つの世代に
   分類します。 新しいオブジェクトは最も若い世代 (世代 "0") に置かれま
   す。 回収を生き残ったオブジェクトは、1 つ古い世代に移されます。 世
   代 "2" が最も古い世代なので、その世代のオブジェクトは回収後も同じ世
   代に残ります。 ガベージコレクタは、実行する時期を決めるために、前回
   の回収以降のオブジェクトの割り当て数と解放数を記録しています。 割り
   当て数から解放数を引いた値が *threshold0* を超えると回収を開始しま
   す。 最初は世代 "0" だけを調べます。 世代 "1" を最後に調べてから世
   代 "0" を調べた回数が *threshold1* を超えると、世代 "1" も調べます
   。 3 番目の世代の処理は少し複雑です。 詳しくは 最も古い世代の回収
   を参照してください。

   詳しくは ガベージコレクタの設計 を参照してください。

   バージョン 3.14 で変更: *threshold2* が無視されるようになりました。

   バージョン 3.14.5 で変更: Python 3.13 の動作に合わせて *threshold2*
   が復活しました。

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})
      True

   Added in version 3.1.

gc.is_finalized(obj)

   指定したオブジェクトがガベージコレクタによってファイナライズ済みの
   場合は "True"、そうでなければ "False" を返します。

      >>> 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

   Added in version 3.9.

gc.freeze()

   ガベージコレクタが追跡しているすべてのオブジェクトを凍結します。 こ
   れらのオブジェクトは永続世代に移され、以降のすべての回収で無視され
   ます。

   プロセスが "exec()" を行わずに "fork()" する場合、子プロセスで不要
   なコピーオンライトを避けることで、メモリ共有を最大限に活用し、全体
   のメモリ使用量を減らせます。 そのためには、親プロセスのメモリページ
   内に解放済みの「穴」ができることを避けるとともに、子プロセスの GC
   が、親プロセス由来の長寿命オブジェクトの "gc_refs" カウンタに触れな
   いようにする必要があります。 両方を実現するには、親プロセスの早い段
   階で "gc.disable()"、"fork()" の直前に "gc.freeze()"、子プロセスの
   早い段階で "gc.enable()" を呼び出します。

   Added in version 3.7.

gc.unfreeze()

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

   Added in version 3.7.

gc.get_freeze_count()

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

   Added in version 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" リストに入れられたオブジェクトの数。

      "candidates": *phase* が "stop" の場合、この世代で回収の候補とし
      て参照をたどったオブジェクトの総数。

      "duration": *phase* が "stop" の場合、回収に費やした時間 (秒)。

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

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

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

   Added in version 3.3.

   バージョン 3.15 で変更: "duration" と "candidates" が追加されました
   。

以下は "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" と同じ）
   。
