The Python interpreter provides some low-level support for attaching
profiling and execution tracing facilities. These are used for
profiling, debugging, and coverage analysis tools.
Starting with Python 2.2, the implementation of this facility was
substantially revised, and an interface from C was added. This C
interface allows the profiling or tracing code to avoid the overhead
of calling through Python-level callable objects, making a direct C
function call instead. The essential attributes of the facility have
not changed; the interface allows trace functions to be installed
per-thread, and the basic events reported to the trace function are
the same as had been reported to the Python-level trace functions in
previous versions.
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,
or PyTrace_C_RETURN, and arg
depends on the value of what:
Value of what
Meaning of arg
PyTrace_CALL
Always NULL.
PyTrace_EXCEPTION
Exception information as returned by
sys.exc_info().
PyTrace_LINE
Always NULL.
PyTrace_RETURN
Value being returned to the caller.
PyTrace_C_CALL
Name of function being called.
PyTrace_C_EXCEPTION
Always NULL.
PyTrace_C_RETURN
Always NULL.
int PyTrace_CALL
The value of the what parameter to a Py_tracefunc
function when a new call to a function or method is being reported,
or a new entry into a generator. Note that the creation of the
iterator for a generator function is not reported as there is no
control transfer to the Python bytecode in the corresponding frame.
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 receives these events; they are not needed by the
profiler.
int PyTrace_LINE
The value passed as the what parameter to a trace function
(but not a profiling function) when a line-number event is being
reported.
int PyTrace_RETURN
The value for the what parameter to Py_tracefunc
functions when a call is returning without propagating an exception.
int PyTrace_C_CALL
The value for the what parameter to Py_tracefunc
functions when a C function is about to be called.
int PyTrace_C_EXCEPTION
The value for the what parameter to Py_tracefunc
functions when a C function has thrown an exception.
int PyTrace_C_RETURN
The value for the what parameter to Py_tracefunc
functions when a C function has returned.
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 the line-number events.
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.
