`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 でない場合は、その世代に属する追跡対象のオブジェクトだけを返します。

警告

Care must be taken when using objects returned by get_objects() because some of them could still be under construction and hence in a temporarily invalid state. Avoid using get_objects() for any purpose other than debugging.

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

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

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

引数 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.

Added in version 3.4.

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

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

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

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.

See Garbage collector design for more information.

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

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

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

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` --- ガベージコレクターインターフェース¶