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.13 で変更: 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.13)

• 2: All objects in the old generation

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

バージョン 3.13 で変更: 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.

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.13 で変更: 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})
False
>>> gc.is_tracked({"a": []})
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 と同じ）。