プロファイリングとトレース
**************************

Python インタプリタは、プロファイル: 分析 (profile) や実行のトレース:
追跡 (trace) といった機能を組み込むために低水準のサポートを提供してい
ます。このサポートは、プロファイルやデバッグ、適用範囲分析 (coverage
analysis) ツールなどに使われます。

この C インターフェースは、プロファイルやトレース作業時に、Python レベ
ルの呼び出し可能オブジェクトが呼び出されることによるオーバヘッドを避け
、直接 C 関数呼び出しが行えるようにしています。プロファイルやトレース
機能の本質的な特性は変わっていません; インターフェースではトレース関数
をスレッドごとにインストールでき、トレース関数に報告される基本イベント
(basic event) は以前のバージョンにおいて Python レベルのトレース関数で
報告されていたものと同じです。

typedef int (*Py_tracefunc)(PyObject *obj, PyFrameObject *frame, int what, PyObject *arg)

   "PyEval_SetProfile()" と "PyEval_SetTrace()" で登録するトレース関数
   の型です。 第 1 引数は登録関数に "obj" として渡したオブジェクト、
   "frame" はイベントの対象のフレームオブジェクトです。 "what" は定数
   "PyTrace_CALL"、"PyTrace_EXCEPTION"、"PyTrace_LINE"、
   "PyTrace_RETURN"、"PyTrace_C_CALL"、"PyTrace_C_EXCEPTION"、
   "PyTrace_C_RETURN"、"PyTrace_OPCODE" のいずれかで、"arg" は "what"
   の値によって異なります。

   +---------------------------------+------------------------------------------+
   | *what* の値                     | *arg* の意味                             |
   |=================================|==========================================|
   | "PyTrace_CALL"                  | 常に "Py_None" 。                        |
   +---------------------------------+------------------------------------------+
   | "PyTrace_EXCEPTION"             | "sys.exc_info()" の返す例外情報です。    |
   +---------------------------------+------------------------------------------+
   | "PyTrace_LINE"                  | 常に "Py_None" 。                        |
   +---------------------------------+------------------------------------------+
   | "PyTrace_RETURN"                | 呼び出し側に返される予定の値か、例外によ |
   |                                 | って関数を抜ける場合は "NULL" です。     |
   +---------------------------------+------------------------------------------+
   | "PyTrace_C_CALL"                | 呼び出される関数オブジェクト。           |
   +---------------------------------+------------------------------------------+
   | "PyTrace_C_EXCEPTION"           | 呼び出される関数オブジェクト。           |
   +---------------------------------+------------------------------------------+
   | "PyTrace_C_RETURN"              | 呼び出される関数オブジェクト。           |
   +---------------------------------+------------------------------------------+
   | "PyTrace_OPCODE"                | 常に "Py_None" 。                        |
   +---------------------------------+------------------------------------------+

int PyTrace_CALL

   関数やメソッドの新たな呼び出し、またはジェネレータへの新たな進入を
   報告するときに、"Py_tracefunc" 関数の "what" 引数に渡される値です。
   ジェネレータ関数からイテレータを作成する時点では、対応するフレーム
   内の Python バイトコードに制御が移らないため、このイベントは報告さ
   れません。

int PyTrace_EXCEPTION

   例外が送出されたときに "Py_tracefunc" 関数の "what" 引数に渡される
   値です。 バイトコードの処理後に実行中のフレーム内で例外が設定される
   と、この値を "what" に指定してコールバックが呼び出されます。 このた
   め、例外の伝播によって Python のスタックが巻き戻される際には、伝播
   先の各フレームに戻るたびにコールバックが呼び出されます。 このイベン
   トを受け取るのはトレース関数だけで、プロファイラには不要です。

int PyTrace_LINE

   行番号のイベントを報告するときに、"Py_tracefunc" 関数 (プロファイリ
   ング関数を除く) の "what" 引数に渡される値です。 フレームの
   "f_trace_lines" を *0* に設定すると、そのフレームでは無効にできます
   。

int PyTrace_RETURN

   呼び出しが返るときに "Py_tracefunc" 関数に *what* 引数として渡す値
   です。

int PyTrace_C_CALL

   C関数を呼び出す直前に "Py_tracefunc" 関数の *what* 引数として渡す値
   です。

int PyTrace_C_EXCEPTION

   C関数が例外を送出したときに "Py_tracefunc" 関数の *what* 引数として
   渡す値です。

int PyTrace_C_RETURN

   C関数から戻るときに "Py_tracefunc" 関数の *what* 引数として渡す値で
   す。

int PyTrace_OPCODE

   新しいオペコードを実行しようとするときに、"Py_tracefunc" 関数 (プロ
   ファイリング関数を除く) の "what" 引数に渡される値です。 このイベン
   トはデフォルトでは発生しません。 フレームの "f_trace_opcodes" を
   *1* に設定して明示的に要求する必要があります。

void PyEval_SetProfile(Py_tracefunc func, PyObject *obj)

   プロファイラ関数を "func" に設定します。 "obj" はその関数の第 1 引
   数として渡され、任意の Python オブジェクトまたは "NULL" を指定でき
   ます。 プロファイラ関数が状態を保持する必要がある場合は、スレッドご
   とに異なる "obj" を使うと、便利でスレッドセーフな保存先になります。
   プロファイラ関数は "PyTrace_LINE"、"PyTrace_OPCODE"、
   "PyTrace_EXCEPTION" を除くすべての監視対象イベントについて呼び出さ
   れます。

   "sys.setprofile()" 関数も参照してください。

   呼び出し元には *アタッチされたスレッド状態* が必要です。

void PyEval_SetProfileAllThreads(Py_tracefunc func, PyObject *obj)

   "PyEval_SetProfile()" と同様ですが、現在のスレッドだけでなく、現在
   のインタープリタに属する実行中のすべてのスレッドにプロファイラ関数
   を設定します。

   呼び出し元には *アタッチされたスレッド状態* が必要です。

   "PyEval_SetProfile()" と同様に、すべてのスレッドにプロファイラ関数
   を設定する際に発生した例外を無視します。

Added in version 3.12.

void PyEval_SetTrace(Py_tracefunc func, PyObject *obj)

   トレース関数を "func" に設定します。 "PyEval_SetProfile()" と同様で
   すが、トレース関数は行番号のイベントとオペコードごとのイベントを受
   け取り、C 関数オブジェクトの呼び出しに関連するイベントは受け取りま
   せん。 "PyEval_SetTrace()" で登録したトレース関数には、"what" 引数
   として "PyTrace_C_CALL"、"PyTrace_C_EXCEPTION"、"PyTrace_C_RETURN"
   が渡されることはありません。

   "sys.settrace()" 関数も参照してください。

   呼び出し元には *アタッチされたスレッド状態* が必要です。

void PyEval_SetTraceAllThreads(Py_tracefunc func, PyObject *obj)

   "PyEval_SetTrace()" と同様ですが、現在のスレッドだけでなく、現在の
   インタープリタに属する実行中のすべてのスレッドにトレース関数を設定
   します。

   呼び出し元には *アタッチされたスレッド状態* が必要です。

   "PyEval_SetTrace()" と同様に、すべてのスレッドにトレース関数を設定
   する際に発生した例外を無視します。

Added in version 3.12.


参照のトレース
**************

Added in version 3.13.

typedef int (*PyRefTracer)(PyObject*, int event, void *data)

   "PyRefTracer_SetTracer()" で登録するトレース関数の型です。 第 1 引
   数は、作成されたばかりの Python オブジェクト ("event" が
   "PyRefTracer_CREATE" の場合)、またはこれから破棄されるオブジェクト
   ("event" が "PyRefTracer_DESTROY" の場合) です。 "data" 引数は
   "PyRefTracer_SetTracer()" の呼び出し時に渡した不透明なポインタです
   。

   現在のトレース関数を置き換える新しい関数が登録される場合、新しい関
   数の登録直前に、オブジェクトを "NULL"、"event" を
   "PyRefTracer_TRACKER_REMOVED" として現在のトレース関数が呼び出され
   ます。

Added in version 3.13.

int PyRefTracer_CREATE

   Python オブジェクトが作成されたときに、"PyRefTracer" 関数の "event"
   引数に渡される値です。

int PyRefTracer_DESTROY

   The value for the *event* parameter to "PyRefTracer" functions when
   a Python object has been destroyed.

int PyRefTracer_TRACKER_REMOVED

   現在のトレーサが新しいトレーサに置き換えられる直前に、"PyRefTracer"
   関数の "event" 引数に渡される値です。

   Added in version 3.14.

int PyRefTracer_SetTracer(PyRefTracer tracer, void *data)

   参照トレーサ関数を登録します。 この関数は、Python オブジェクトが新
   しく作成されたときと、これから破棄されるときに呼び出されます。
   "data" を指定する場合は不透明なポインタでなければならず、トレーサ関
   数の呼び出し時に渡されます。 成功した場合は "0" を返します。 エラー
   の場合は例外を設定して "-1" を返します。

   トレーサ関数の内部では Python オブジェクトを作成しては **いけません
   **。 作成すると、トレーサ関数が再入されてしまいます。 また、既存の
   例外をクリアしたり、新しい例外を設定したりしては **いけません**。
   トレーサ関数が呼び出されるときは、常に *スレッド状態* が有効です。

   この関数の呼び出し時には *スレッド状態がアタッチされている* 必要が
   あります。

   別のトレーサ関数がすでに登録されている場合、新しい関数の登録直前に
   、"event" を "PyRefTracer_TRACKER_REMOVED" として古い関数が呼び出さ
   れます。

Added in version 3.13.

PyRefTracer PyRefTracer_GetTracer(void **data)

   登録された参照トレーサ関数と、"PyRefTracer_SetTracer()" の呼び出し
   時に登録された不透明なデータポインタの値を取得します。 トレーサが登
   録されていない場合は NULL を返し、"data" ポインタを NULL に設定しま
   す。

   この関数の呼び出し時には *スレッド状態がアタッチされている* 必要が
   あります。

Added in version 3.13.


パフォーマンス統計
******************

PYSTATS_MAX_UOP_ID

   CPython がパフォーマンス統計用カウンタを割り当てるマイクロ命令の識
   別子の最大値。 "--enable-pystats" で構成したビルドでのみ利用できま
   す。

   この定数は内部専用で、拡張モジュールには役立ちません。

   バージョン 3.15.2 で ソフト非推奨 <Soft deprecated>.
