`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)¶

With no arguments, run a full 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.

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

インタープリタがすでに回収を行っている間に gc.collect() を呼び出した場合の動作は未定義です。

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 リストに移動した) オブジェクトの総数です。

Added in version 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

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

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

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

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 と同じ）。

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

前のトピックへ

次のトピックへ

このページ

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

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