<!DOCTYPE html PUBLIC
"-//W3C//DTD HTML 4.0 Transitional//EN">
<link rel=
"STYLESHEET" href=
"api.css" type='text/css'
/>
<link rel=
"SHORTCUT ICON" href=
"../icons/pyfav.png" type=
"image/png" />
<link rel='start' href='../index.html' title='Python Documentation Index'
/>
<link rel=
"first" href=
"api.html" title='Python/C API Reference Manual'
/>
<link rel='contents' href='contents.html'
title=
"Contents" />
<link rel='index' href='genindex.html' title='Index'
/>
<link rel='last' href='about.html' title='About this document...'
/>
<link rel='help' href='about.html' title='About this document...'
/>
<link rel=
"next" href=
"advanced-debugging.html" />
<link rel=
"prev" href=
"threads.html" />
<link rel=
"parent" href=
"initialization.html" />
<link rel=
"next" href=
"advanced-debugging.html" />
<meta name='aesop' content='information'
/>
<title>8.2 Profiling and Tracing
</title>
<div id='top-navigation-panel' xml:id='top-navigation-panel'
>
<table align=
"center" width=
"100%" cellpadding=
"0" cellspacing=
"2">
<td class='online-navigation'
><a rel=
"prev" title=
"8.1 Thread State and"
href=
"threads.html"><img src='../icons/previous.png'
border='
0' height='
32' alt='Previous Page' width='
32'
/></A></td><td class='online-navigation'
><a rel=
"parent" title=
"8. Initialization, Finalization, and"
href=
"initialization.html"><img src='../icons/up.png'
border='
0' height='
32' alt='Up One Level' width='
32'
/></A></td><td class='online-navigation'
><a rel=
"next" title=
"8.3 Advanced Debugger Support"
href=
"advanced-debugging.html"><img src='../icons/next.png'
border='
0' height='
32' alt='Next Page' width='
32'
/></A></td><td align=
"center" width=
"100%">Python/C API Reference Manual
</td>
<td class='online-navigation'
><a rel=
"contents" title=
"Table of Contents"
href=
"contents.html"><img src='../icons/contents.png'
border='
0' height='
32' alt='Contents' width='
32'
/></A></td><td class='online-navigation'
><img src='../icons/blank.png'
border='
0' height='
32' alt='' width='
32'
/></td><td class='online-navigation'
><a rel=
"index" title=
"Index"
href=
"genindex.html"><img src='../icons/index.png'
border='
0' height='
32' alt='Index' width='
32'
/></A></td><div class='online-navigation'
>
<b class=
"navlabel">Previous:
</b>
<a class=
"sectref" rel=
"prev" href=
"threads.html">8.1 Thread State and
</A>
<b class=
"navlabel">Up:
</b>
<a class=
"sectref" rel=
"parent" href=
"initialization.html">8. Initialization, Finalization, and
</A>
<b class=
"navlabel">Next:
</b>
<a class=
"sectref" rel=
"next" href=
"advanced-debugging.html">8.3 Advanced Debugger Support
</A>
<!--End of Navigation Panel-->
<H1><A NAME=
"SECTION0010200000000000000000"></A><A NAME=
"profiling"></A>
8.2 Profiling and Tracing
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
<dl><dt><b><tt class=
"ctype"><a id='l2h-
881' xml:id='l2h-
881'
>int (*Py_tracefunc)(PyObject *obj,
PyFrameObject *frame, int what,
PyObject *arg)
</a></tt></b></dt> The type of the trace function registered using
<tt class=
"cfunction">PyEval_SetProfile()
</tt> and
<tt class=
"cfunction">PyEval_SetTrace()
</tt>.
The first parameter is the object passed to the registration
function as
<var>obj
</var>,
<var>frame
</var> is the frame object to which the
event pertains,
<var>what
</var> is one of the constants
<tt class=
"constant">PyTrace_CALL
</tt>,
<tt class=
"constant">PyTrace_EXCEPTION
</tt>,
<tt class=
"constant">PyTrace_LINE
</tt>,
<tt class=
"constant">PyTrace_RETURN
</tt>,
<tt class=
"constant">PyTrace_C_CALL
</tt>,
<tt class=
"constant">PyTrace_C_EXCEPTION
</tt>,
or
<tt class=
"constant">PyTrace_C_RETURN
</tt>, and
<var>arg
</var> depends on the value of
<var>what
</var>:
<div class=
"center"><table class=
"realtable">
<th class=
"left" >Value of
<var>what
</var></th>
<th class=
"left" >Meaning of
<var>arg
</var></th>
<tr><td class=
"left" valign=
"baseline"><tt class=
"constant">PyTrace_CALL
</tt></td>
<td class=
"left" >Always
<tt class=
"constant">NULL
</tt>.
</td></tr>
<tr><td class=
"left" valign=
"baseline"><tt class=
"constant">PyTrace_EXCEPTION
</tt></td>
<td class=
"left" >Exception information as returned by
<tt class=
"function">sys.exc_info()
</tt>.
</td></tr>
<tr><td class=
"left" valign=
"baseline"><tt class=
"constant">PyTrace_LINE
</tt></td>
<td class=
"left" >Always
<tt class=
"constant">NULL
</tt>.
</td></tr>
<tr><td class=
"left" valign=
"baseline"><tt class=
"constant">PyTrace_RETURN
</tt></td>
<td class=
"left" >Value being returned to the caller.
</td></tr>
<tr><td class=
"left" valign=
"baseline"><tt class=
"constant">PyTrace_C_CALL
</tt></td>
<td class=
"left" >Name of function being called.
</td></tr>
<tr><td class=
"left" valign=
"baseline"><tt class=
"constant">PyTrace_C_EXCEPTION
</tt></td>
<td class=
"left" >Always
<tt class=
"constant">NULL
</tt>.
</td></tr>
<tr><td class=
"left" valign=
"baseline"><tt class=
"constant">PyTrace_C_RETURN
</tt></td>
<td class=
"left" >Always
<tt class=
"constant">NULL
</tt>.
</td></tr></tbody>
<dl><dt>int
<b><tt id='l2h-
882' xml:id='l2h-
882'
class=
"cdata">PyTrace_CALL
</tt></b></dt>
The value of the
<var>what
</var> parameter to a
<tt class=
"ctype">Py_tracefunc
</tt> 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.
<dl><dt>int
<b><tt id='l2h-
883' xml:id='l2h-
883'
class=
"cdata">PyTrace_EXCEPTION
</tt></b></dt>
The value of the
<var>what
</var> parameter to a
<tt class=
"ctype">Py_tracefunc
</tt> function when an exception has been raised. The callback function
is called with this value for
<var>what
</var> 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
<dl><dt>int
<b><tt id='l2h-
884' xml:id='l2h-
884'
class=
"cdata">PyTrace_LINE
</tt></b></dt>
The value passed as the
<var>what
</var> parameter to a trace function
(but not a profiling function) when a line-number event is being
<dl><dt>int
<b><tt id='l2h-
885' xml:id='l2h-
885'
class=
"cdata">PyTrace_RETURN
</tt></b></dt>
The value for the
<var>what
</var> parameter to
<tt class=
"ctype">Py_tracefunc
</tt> functions when a call is returning without propagating an exception.
<dl><dt>int
<b><tt id='l2h-
886' xml:id='l2h-
886'
class=
"cdata">PyTrace_C_CALL
</tt></b></dt>
The value for the
<var>what
</var> parameter to
<tt class=
"ctype">Py_tracefunc
</tt> functions when a C function is about to be called.
<dl><dt>int
<b><tt id='l2h-
887' xml:id='l2h-
887'
class=
"cdata">PyTrace_C_EXCEPTION
</tt></b></dt>
The value for the
<var>what
</var> parameter to
<tt class=
"ctype">Py_tracefunc
</tt> functions when a C function has thrown an exception.
<dl><dt>int
<b><tt id='l2h-
888' xml:id='l2h-
888'
class=
"cdata">PyTrace_C_RETURN
</tt></b></dt>
The value for the
<var>what
</var> parameter to
<tt class=
"ctype">Py_tracefunc
</tt> functions when a C function has returned.
<dl><dt><table cellpadding=
"0" cellspacing=
"0"><tr valign=
"baseline"><td><nobr>void
<b><tt id='l2h-
889' xml:id='l2h-
889'
class=
"cfunction">PyEval_SetProfile
</tt></b>(
</nobr></td><td>Py_tracefunc
<var>func
</var>, PyObject *
<var>obj
</var>)
</td></tr></table></dt>
Set the profiler function to
<var>func
</var>. The
<var>obj
</var> parameter is
passed to the function as its first parameter, and may be any Python
object, or
<tt class=
"constant">NULL
</tt>. If the profile function needs to maintain state,
using a different value for
<var>obj
</var> 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.
<dl><dt><table cellpadding=
"0" cellspacing=
"0"><tr valign=
"baseline"><td><nobr>void
<b><tt id='l2h-
890' xml:id='l2h-
890'
class=
"cfunction">PyEval_SetTrace
</tt></b>(
</nobr></td><td>Py_tracefunc
<var>func
</var>, PyObject *
<var>obj
</var>)
</td></tr></table></dt>
Set the tracing function to
<var>func
</var>. This is similar to
<tt class=
"cfunction">PyEval_SetProfile()
</tt>, except the tracing function does
receive line-number events.
<div class='online-navigation'
>
<table align=
"center" width=
"100%" cellpadding=
"0" cellspacing=
"2">
<td class='online-navigation'
><a rel=
"prev" title=
"8.1 Thread State and"
href=
"threads.html"><img src='../icons/previous.png'
border='
0' height='
32' alt='Previous Page' width='
32'
/></A></td><td class='online-navigation'
><a rel=
"parent" title=
"8. Initialization, Finalization, and"
href=
"initialization.html"><img src='../icons/up.png'
border='
0' height='
32' alt='Up One Level' width='
32'
/></A></td><td class='online-navigation'
><a rel=
"next" title=
"8.3 Advanced Debugger Support"
href=
"advanced-debugging.html"><img src='../icons/next.png'
border='
0' height='
32' alt='Next Page' width='
32'
/></A></td><td align=
"center" width=
"100%">Python/C API Reference Manual
</td>
<td class='online-navigation'
><a rel=
"contents" title=
"Table of Contents"
href=
"contents.html"><img src='../icons/contents.png'
border='
0' height='
32' alt='Contents' width='
32'
/></A></td><td class='online-navigation'
><img src='../icons/blank.png'
border='
0' height='
32' alt='' width='
32'
/></td><td class='online-navigation'
><a rel=
"index" title=
"Index"
href=
"genindex.html"><img src='../icons/index.png'
border='
0' height='
32' alt='Index' width='
32'
/></A></td><div class='online-navigation'
>
<b class=
"navlabel">Previous:
</b>
<a class=
"sectref" rel=
"prev" href=
"threads.html">8.1 Thread State and
</A>
<b class=
"navlabel">Up:
</b>
<a class=
"sectref" rel=
"parent" href=
"initialization.html">8. Initialization, Finalization, and
</A>
<b class=
"navlabel">Next:
</b>
<a class=
"sectref" rel=
"next" href=
"advanced-debugging.html">8.3 Advanced Debugger Support
</A>
<span class=
"release-info">Release
2.4.2, documentation updated on
28 September
2005.
</span>
<!--End of Navigation Panel-->
See
<i><a href=
"about.html">About this document...
</a></i> for information on suggesting changes.
projects / OpenSPARC-T2-SAM / blob