# `gc` --- ガベージコレクターインターフェース

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

The `gc` module provides the following functions:

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` is the total number of objects which were found to be uncollectable (and were therefore moved to the `garbage` list) inside this generation;

  - `candidates` is the total number of objects in this generation which were considered for collection and traversed;

  - `duration` is the total time in seconds spent in collections for this generation.

  Added in version 3.4.

  バージョン 3.15 で変更: Add `duration` and `candidates`.

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

  > "candidates": When phase is "stop", the total number of objects in this generation which were considered for collection and traversed.

  > "duration": When phase is "stop", the time in seconds spent in the collection.

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

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

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

  Added in version 3.3.

  バージョン 3.15 で変更: Add "duration" and "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` と同じ）。