Profiling and tracing
*********************

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

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

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

   The type of the trace function registered using
   "PyEval_SetProfile()" and "PyEval_SetTrace()". The first parameter
   is the object passed to the registration function as *obj*, *frame*
   is the frame object to which the event pertains, *what* is one of
   the constants "PyTrace_CALL", "PyTrace_EXCEPTION", "PyTrace_LINE",
   "PyTrace_RETURN", "PyTrace_C_CALL", "PyTrace_C_EXCEPTION",
   "PyTrace_C_RETURN", or "PyTrace_OPCODE", and *arg* depends on the
   value of *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 バイトコードに制御の委譲 (control transfer) が起こらないため
   報告されないので注意してください。

int PyTrace_EXCEPTION

   The value of the *what* parameter to a "Py_tracefunc" function when
   an exception has been raised.  The callback function is called with
   this value for *what* when after any bytecode is processed after
   which the exception becomes set within the frame being executed.
   The effect of this is that as exception propagation causes the
   Python stack to unwind, the callback is called upon return to each
   frame as the exception propagates.  Only trace functions receive
   these events; they are not needed by the profiler.

int PyTrace_LINE

   The value passed as the *what* parameter to a "Py_tracefunc"
   function (but not a profiling function) when a line-number event is
   being reported. It may be disabled for a frame by setting
   "f_trace_lines" to *0* on that frame.

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

   The value for the *what* parameter to "Py_tracefunc" functions (but
   not profiling functions) when a new opcode is about to be executed.
   This event is not emitted by default: it must be explicitly
   requested by setting "f_trace_opcodes" to *1* on the frame.

void PyEval_SetProfile(Py_tracefunc func, PyObject *obj)

   Set the profiler function to *func*.  The *obj* parameter is passed
   to the function as its first parameter, and may be any Python
   object, or "NULL".  If the profile function needs to maintain
   state, using a different value for *obj* for each thread provides a
   convenient and thread-safe place to store it.  The profile function
   is called for all monitored events except "PyTrace_LINE"
   "PyTrace_OPCODE" and "PyTrace_EXCEPTION".

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

   The caller must have an *attached thread state*.

void PyEval_SetProfileAllThreads(Py_tracefunc func, PyObject *obj)

   Like "PyEval_SetProfile()" but sets the profile function in all
   running threads belonging to the current interpreter instead of the
   setting it only on the current thread.

   The caller must have an *attached thread state*.

   As "PyEval_SetProfile()", this function ignores any exceptions
   raised while setting the profile functions in all threads.

Added in version 3.12.

void PyEval_SetTrace(Py_tracefunc func, PyObject *obj)

   Set the tracing function to *func*.  This is similar to
   "PyEval_SetProfile()", except the tracing function does receive
   line-number events and per-opcode events, but does not receive any
   event related to C function objects being called.  Any trace
   function registered using "PyEval_SetTrace()" will not receive
   "PyTrace_C_CALL", "PyTrace_C_EXCEPTION" or "PyTrace_C_RETURN" as a
   value for the *what* parameter.

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

   The caller must have an *attached thread state*.

void PyEval_SetTraceAllThreads(Py_tracefunc func, PyObject *obj)

   Like "PyEval_SetTrace()" but sets the tracing function in all
   running threads belonging to the current interpreter instead of the
   setting it only on the current thread.

   The caller must have an *attached thread state*.

   As "PyEval_SetTrace()", this function ignores any exceptions raised
   while setting the trace functions in all threads.

Added in version 3.12.


Reference tracing
*****************

Added in version 3.13.

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

   The type of the trace function registered using
   "PyRefTracer_SetTracer()". The first parameter is a Python object
   that has been just created (when **event** is set to
   "PyRefTracer_CREATE") or about to be destroyed (when **event** is
   set to "PyRefTracer_DESTROY"). The **data** argument is the opaque
   pointer that was provided when "PyRefTracer_SetTracer()" was
   called.

   If a new tracing function is registered replacing the current one,
   a call to the trace function will be made with the object set to
   **NULL** and **event** set to "PyRefTracer_TRACKER_REMOVED". This
   will happen just before the new function is registered.

Added in version 3.13.

int PyRefTracer_CREATE

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

int PyRefTracer_DESTROY

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

int PyRefTracer_TRACKER_REMOVED

   The value for the *event* parameter to "PyRefTracer" functions when
   the current tracer is about to be replaced by a new one.

   Added in version 3.14.

int PyRefTracer_SetTracer(PyRefTracer tracer, void *data)

   Register a reference tracer function. The function will be called
   when a new Python object has been created or when an object is
   going to be destroyed. If **data** is provided it must be an opaque
   pointer that will be provided when the tracer function is called.
   Return "0" on success. Set an exception and return "-1" on error.

   Note that tracer functions **must not** create Python objects
   inside or otherwise the call will be re-entrant. The tracer also
   **must not** clear any existing exception or set an exception.  A
   *thread state* will be active every time the tracer function is
   called.

   There must be an *attached thread state* when calling this
   function.

   If another tracer function was already registered, the old function
   will be called with **event** set to "PyRefTracer_TRACKER_REMOVED"
   just before the new function is registered.

Added in version 3.13.

PyRefTracer PyRefTracer_GetTracer(void **data)

   Get the registered reference tracer function and the value of the
   opaque data pointer that was registered when
   "PyRefTracer_SetTracer()" was called. If no tracer was registered
   this function will return NULL and will set the **data** pointer to
   NULL.

   There must be an *attached thread state* when calling this
   function.

Added in version 3.13.
