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

   Perform a collection.  The optional argument *generation* may be an
   integer specifying which generation to collect (from 0 to 2).  A
   "ValueError" is raised if the generation number is invalid. The sum
   of collected objects and uncollectable objects is returned.

   Calling "gc.collect(0)" will perform a GC collection on the young
   generation.

   Calling "gc.collect(1)" will perform a GC collection on the young
   generation and an increment of the old generation.

   Calling "gc.collect(2)" or "gc.collect()" performs a full
   collection

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

   The effect of calling "gc.collect()" while the interpreter is
   already performing a collection is undefined.

   バージョン 3.14 で変更: "generation=1" performs an increment of
   collection.

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 as follows:

   * 0: All objects in the young generation

   * 1: No objects, as there is no generation 1 (as of Python 3.14)

   * 2: All objects in the old generation

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

   バージョン 3.14 で変更: Generation 1 is removed

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

gc.get_stats()

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

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

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

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

   Added in version 3.4.

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

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

   The GC classifies objects into two generations depending on whether
   they have survived a collection. New objects are placed in the
   young generation. If an object survives a collection it is moved
   into the old generation.

   In order to decide when to run, the collector keeps track of the
   number of object allocations and deallocations since the last
   collection.  When the number of allocations minus the number of
   deallocations exceeds *threshold0*, collection starts. For each
   collection, all the objects in the young generation and some
   fraction of the old generation is collected.

   In the free-threaded build, the increase in process memory usage is
   also checked before running the collector.  If the memory usage has
   not increased by 10% since the last collection and the net number
   of object allocations has not exceeded 40 times *threshold0*, the
   collection is not run.

   The fraction of the old generation that is collected is
   **inversely** proportional to *threshold1*. The larger *threshold1*
   is, the slower objects in the old generation are collected. For the
   default value of 10, 1% of the old generation is scanned during
   each collection.

   *threshold2* is ignored.

   See Garbage collector design for more information.

   バージョン 3.14 で変更: *threshold2* is ignored

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)

   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

   Added in version 3.9.

gc.freeze()

   Freeze all the objects tracked by the garbage collector; move them
   to a permanent generation and ignore them in all the future
   collections.

   If a process will "fork()" without "exec()", avoiding unnecessary
   copy-on-write in child processes will maximize memory sharing and
   reduce overall memory usage. This requires both avoiding creation
   of freed "holes" in memory pages in the parent process and ensuring
   that GC collections in child processes won't touch the "gc_refs"
   counter of long-lived objects originating in the parent process. To
   accomplish both, call "gc.disable()" early in the parent process,
   "gc.freeze()" right before "fork()", and "gc.enable()" early in
   child processes.

   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 で変更: Following **PEP 442**, objects with a
   "__del__()" method don't end up in "gc.garbage" anymore.

gc.callbacks

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

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

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

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

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

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

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

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

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

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

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

   Added in version 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" と同じ）
   。
