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

.. module:: gc
   :synopsis: 循環検出ガベージコレクタのインターフェース。
.. moduleauthor:: Neil Schemenauer <nas@arctrix.com>
.. sectionauthor:: Neil Schemenauer <nas@arctrix.com>


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

:mod:`gc` モジュールは、以下の関数を提供しています。


.. function:: enable()

   自動ガベージコレクションを有効にします。


.. function:: disable()

   自動ガベージコレクションを無効にします。


.. function:: isenabled()

   自動ガベージコレクションが有効なら真を返します。


.. function:: collect([generation])

   引数を指定しない場合は、全ての検出を行います。オプションの引数 *generation* は、どの世代を検出するかを (0 から 2 までの)
   整数値で指定します。無効な世代番号を指定した場合は :exc:`ValueError` が発生します。検出した到達不可オブジェクトの数を返します。

   .. versionchanged:: 2.5
      オプションの引数 *generation* が追加されました.

   .. .. versionchanged:: 2.6
      The free lists maintained for a number of builtin types are cleared
      whenever a full collection or collection of the highest generation (2)
      is run.  Not all items in some free lists may be freed due to the
      particular implementation, in particular :class:`int` and :class:`float`.

   .. versionchanged:: 2.6
      幾つかの組み込み型のフリーリストは、最高(第二)世代のGC、あるいはフルGCが
      実行されるたびにクリアされます。
      幾つかの型(特に :class:`int` と :class:`float`)では、実装によっては、
      フリーリスト内の全てのオブジェクトが開放されるとは限りません。


.. function:: set_debug(flags)

   ガベージコレクションのデバッグフラグを設定します。デバッグ情報は ``sys.stderr`` に出力されます。
   デバッグフラグは、下の値の組み合わせを指定する事ができます。


.. function:: get_debug()

   現在のデバッグフラグを返します。


.. function:: get_objects()

   現在追跡しているオブジェクトのリストを返します。このリストには、戻り値のリスト自身は含まれていません。

   .. versionadded:: 2.2


.. function:: set_threshold(threshold0[, threshold1[, threshold2]])

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

   GCは、オブジェクトを走査された回数に従って3世代に分類します。
   新しいオブジェクトは最も若い(``0`` 世代)に分類されます。
   もし、そのオブジェクトがガベージコレクションで削除されなければ、次に古い世代に分類されます。
   もっとも古い世代は ``2`` 世代で、この世代に属するオブジェクトは他の世代に移動しません。
   ガベージコレクタは、最後に検出を行ってから生成・削除したオブジェクトの数をカウントしており、この数によって検出を開始します。
   オブジェクトの生成数 - 削除数が *threshold0* より大きくなると、検出を開始します。
   最初は ``0`` 世代のオブジェクトのみが検査されます。 ``0`` 世代の検査が ``threshold1`` 回実行されると、
   ``1`` 世代のオブジェクトの検査を行います。
   同様に、 ``1`` 世代が ``threshold2`` 回検査されると、 ``2`` 世代の検査を行います。


.. function:: get_count()

   現在の検出数を、 ``(count0, count1, count2)`` のタプルで返します。

   .. versionadded:: 2.5


.. function:: get_threshold()

   現在の検出閾値を、 ``(threshold0, threshold1, threshold2)`` のタプルで返します。


.. function:: get_referrers(*objs)

   objsで指定したオブジェクトのいずれかを参照しているオブジェクトのリストを返します。この関数では、ガベージコレクションをサポートしているコンテナの
   みを返します。他のオブジェクトを参照していても、ガベージコレクションをサポートしていない拡張型は含まれません。

   尚、戻り値のリストには、すでに参照されなくなっているが、循環参照の一部でまだガベージコレクションで回収されていないオブジェクトも含まれるので注意
   が必要です。有効なオブジェクトのみを取得する場合、 :func:`get_referrers` の前に :func:`collect` を呼び出してください。

   :func:`get_referrers` から返されるオブジェクトは作りかけや利用できない状態である場合があるので、利用する際には注意が必要です。
   :func:`get_referrers` をデバッグ以外の目的で利用するのは避けてください。

   .. versionadded:: 2.2


.. function:: get_referents(*objs)

   引数で指定したオブジェクトのいずれかから参照されている、全てのオブジェクトのリストを返します。参照先のオブジェクトは、引数で指定したオブジェクトの
   Cレベルメソッド :attr:`tp_traverse` で取得し、全てのオブジェクトが直接到達
   可能な全てのオブジェクトを返すわけではありません。 :attr:`tp_traverse` は
   ガベージコレクションをサポートするオブジェクトのみが実装しており、ここで取得できるオブジェクトは循環参照の一部となる可能性のあるオブジェクトのみ
   です。従って、例えば整数オブジェクトが直接到達可能であっても、このオブジェクトは戻り値には含まれません。

   .. versionadded:: 2.3

以下の変数は読み込み専用です。(変更することはできますが、再バインドする事はできません。）


.. data:: garbage

   到達不能であることが検出されたが、解放する事ができないオブジェクトのリスト（回収不能オブジェクト）。デフォルトでは、 :meth:`__del__` メソッドを
   持つオブジェクトのみが格納されます。  [#]_

   :meth:`__del__` メソッドを持つオブジェクトが循環参照に含まれている場合、その循環参照全体と、循環参照からのみ到達する事ができるオブジェクトは
   回収不能となります。このような場合には、Pythonは安全に :meth:`__del__`
   を呼び出す順番を決定する事ができないため、自動的に解放することはできません。もし安全な解放順序がわかるのであれば、 *garbage* リストを参照して
   循環参照を破壊する事ができます。循環参照を破壊した後でも、そのオブジェクトは *garbage* リストから参照されているため、解放されません。解放する
   ためには、循環参照を破壊した後、 ``del gc.garbage[:]`` のように *garbage* からオブジェクトを削除する必要があります。一般的には
   :meth:`__del__` を持つオブジェクトが循環参照の一部とはならないように配
   慮し、 *garbage* はそのような循環参照が発生していない事を確認するために利用する方が良いでしょう。

   :const:`DEBUG_SAVEALL` が設定されている場合、全ての到達不能オブジェクトは解放されずにこのリストに格納されます。

以下は :func:`set_debug` に指定することのできる定数です。


.. data:: DEBUG_STATS

   検出中に統計情報を出力します。この情報は、検出頻度を最適化する際に有益です。


.. data:: DEBUG_COLLECTABLE

   見つかった回収可能オブジェクトの情報を出力します。


.. data:: DEBUG_UNCOLLECTABLE

   見つかった回収不能オブジェクト（到達不能だが、ガベージコレクションで解放する事ができないオブジェクト）の情報を出力します。回収不能オブジェクト
   は、 ``garbade`` リストに追加されます。


.. data:: DEBUG_INSTANCES

   :const:`DEBUG_COLLECTABLE` か :const:`DEBUG_UNCOLLECTABLE` が設定されて
   いる場合、見つかったインスタンスオブジェクトの情報を出力します。


.. data:: DEBUG_OBJECTS

   :const:`DEBUG_COLLECTABLE` か :const:`DEBUG_UNCOLLECTABLE` が設定されて
   いる場合、見つかったインスタンスオブジェクト以外のオブジェクトの情報を出力します。


.. data:: DEBUG_SAVEALL

   設定されている場合、全ての到達不能オブジェクトは解放されずに *garbage* に追加されます。これはプログラムのメモリリークをデバッグするときに便利です。


.. data:: DEBUG_LEAK

   プログラムのメモリリークをデバッグするときに指定します。（ ``DEBUG_COLLECTABLE | DEBUG_UNCOLLECTABLE |
   DEBUG_INSTANCES |  DEBUG_OBJECTS | DEBUG_SAVEALL`` と同じ。）

.. rubric:: Footnotes

.. [#] Python 2.2より前のバージョンでは、 :meth:`__del__` メソッドを持つオブジェクトだけでなく、全ての到達不能オブジェクトが格納されてい
   た。）

