projects / OpenSPARC-T2-SAM / blame
? search:
summary | tags | clone url | shortlog | log | commit | commitdiff | tree
blob | blame (incremental) | history | HEAD
Initial commit of OpenSPARC T2 architecture model.
[OpenSPARC-T2-SAM] / sam-t2 / devtools / v9 / html / python / lib / module-profile.html
CommitLineData
920dae64
AT		 1<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
2<html>
3<head>
4<link rel="STYLESHEET" href="lib.css" type='text/css' />
5<link rel="SHORTCUT ICON" href="../icons/pyfav.png" type="image/png" />
6<link rel='start' href='../index.html' title='Python Documentation Index' />
7<link rel="first" href="lib.html" title='Python Library Reference' />
8<link rel='contents' href='contents.html' title="Contents" />
9<link rel='index' href='genindex.html' title='Index' />
10<link rel='last' href='about.html' title='About this document...' />
11<link rel='help' href='about.html' title='About this document...' />
12<link rel="next" href="profile-limits.html" />
13<link rel="prev" href="node453.html" />
14<link rel="parent" href="profile.html" />
15<link rel="next" href="profile-stats.html" />
16<meta name='aesop' content='information' />
17<title>10.5 Reference Manual</title>
18</head>
19<body>
20<DIV CLASS="navigation">
21<div id='top-navigation-panel' xml:id='top-navigation-panel'>
22<table align="center" width="100%" cellpadding="0" cellspacing="2">
23<tr>
24<td class='online-navigation'><a rel="prev" title="10.4 What Is Deterministic"
25 href="node453.html"><img src='../icons/previous.png'
26 border='0' height='32' alt='Previous Page' width='32' /></A></td>
27<td class='online-navigation'><a rel="parent" title="10. The Python Profiler"
28 href="profile.html"><img src='../icons/up.png'
29 border='0' height='32' alt='Up One Level' width='32' /></A></td>
30<td class='online-navigation'><a rel="next" title="10.5.1 The Stats Class"
31 href="profile-stats.html"><img src='../icons/next.png'
32 border='0' height='32' alt='Next Page' width='32' /></A></td>
33<td align="center" width="100%">Python Library Reference</td>
34<td class='online-navigation'><a rel="contents" title="Table of Contents"
35 href="contents.html"><img src='../icons/contents.png'
36 border='0' height='32' alt='Contents' width='32' /></A></td>
37<td class='online-navigation'><a href="modindex.html" title="Module Index"><img src='../icons/modules.png'
38 border='0' height='32' alt='Module Index' width='32' /></a></td>
39<td class='online-navigation'><a rel="index" title="Index"
40 href="genindex.html"><img src='../icons/index.png'
41 border='0' height='32' alt='Index' width='32' /></A></td>
42</tr></table>
43<div class='online-navigation'>
44<b class="navlabel">Previous:</b>
45<a class="sectref" rel="prev" href="node453.html">10.4 What Is Deterministic</A>
46<b class="navlabel">Up:</b>
47<a class="sectref" rel="parent" href="profile.html">10. The Python Profiler</A>
48<b class="navlabel">Next:</b>
49<a class="sectref" rel="next" href="profile-stats.html">10.5.1 The Stats Class</A>
50</div>
51<hr /></div>
52</DIV>
53<!--End of Navigation Panel-->
54
55<H1><A NAME="SECTION0012500000000000000000">
5610.5 Reference Manual</A>
57</H1>
58
59<P>
60<A NAME="module-profile"></A>
61
62<P>
63The primary entry point for the profiler is the global function
64<tt class="function">profile.run()</tt>. It is typically used to create any profile
65information. The reports are formatted and printed using methods of
66the class <tt class="class">pstats.Stats</tt>. The following is a description of all
67of these standard entry points and functions. For a more in-depth
68view of some of the code, consider reading the later section on
69Profiler Extensions, which includes discussion of how to derive
70``better'' profilers from the classes presented, or reading the source
71code for these modules.
72
73<P>
74<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
75 <td><nobr><b><tt id='l2h-3108' xml:id='l2h-3108' class="function">run</tt></b>(</nobr></td>
76 <td><var>command</var><big>[</big><var>, filename</var><big>]</big><var></var>)</td></tr></table></dt>
77<dd>
78
79<P>
80This function takes a single argument that has can be passed to the
81<tt class="keyword">exec</tt> statement, and an optional file name. In all cases this
82routine attempts to <tt class="keyword">exec</tt> its first argument, and gather profiling
83statistics from the execution. If no file name is present, then this
84function automatically prints a simple profiling report, sorted by the
85standard name string (file/line/function-name) that is presented in
86each line. The following is a typical output from such a call:
87
88<P>
89<div class="verbatim"><pre>
90 main()
91 2706 function calls (2004 primitive calls) in 4.504 CPU seconds
92
93Ordered by: standard name
94
95ncalls tottime percall cumtime percall filename:lineno(function)
96 2 0.006 0.003 0.953 0.477 pobject.py:75(save_objects)
97 43/3 0.533 0.012 0.749 0.250 pobject.py:99(evaluate)
98 ...
99</pre></div>
100
101<P>
102The first line indicates that this profile was generated by the call:
103<BR><code>profile.run('main()')</code>, and hence the exec'ed string is
104<code>'main()'</code>. The second line indicates that 2706 calls were
105monitored. Of those calls, 2004 were <i class="dfn">primitive</i>. We define
106<i class="dfn">primitive</i> to mean that the call was not induced via recursion.
107The next line: <code>Ordered by: standard name</code>, indicates that
108the text string in the far right column was used to sort the output.
109The column headings include:
110
111<P>
112<DL>
113<DT><STRONG>ncalls </STRONG></DT>
114<DD>for the number of calls,
115
116<P>
117</DD>
118<DT><STRONG>tottime </STRONG></DT>
119<DD>for the total time spent in the given function (and excluding time
120made in calls to sub-functions),
121
122<P>
123</DD>
124<DT><STRONG>percall </STRONG></DT>
125<DD>is the quotient of <code>tottime</code> divided by <code>ncalls</code>
126
127<P>
128</DD>
129<DT><STRONG>cumtime </STRONG></DT>
130<DD>is the total time spent in this and all subfunctions (from invocation
131till exit). This figure is accurate <em>even</em> for recursive
132functions.
133
134<P>
135</DD>
136<DT><STRONG>percall </STRONG></DT>
137<DD>is the quotient of <code>cumtime</code> divided by primitive calls
138
139<P>
140</DD>
141<DT><STRONG>filename:lineno(function) </STRONG></DT>
142<DD>provides the respective data of each function
143
144<P>
145</DD>
146</DL>
147
148<P>
149When there are two numbers in the first column (for example,
150"<tt class="samp">43/3</tt>"), then the latter is the number of primitive calls, and
151the former is the actual number of calls. Note that when the function
152does not recurse, these two values are the same, and only the single
153figure is printed.
154
155<P>
156</dl>
157
158<P>
159<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
160 <td><nobr><b><tt id='l2h-3109' xml:id='l2h-3109' class="function">runctx</tt></b>(</nobr></td>
161 <td><var>command, globals, locals</var><big>[</big><var>, filename</var><big>]</big><var></var>)</td></tr></table></dt>
162<dd>
163This function is similar to <tt class="function">profile.run()</tt>, with added
164arguments to supply the globals and locals dictionaries for the
165<var>command</var> string.
166</dl>
167
168<P>
169Analysis of the profiler data is done using this class from the
170<tt class="module">pstats</tt> module:
171
172<P>
173<a id='l2h-3111' xml:id='l2h-3111'></a>
174
175<P>
176<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
177 <td><nobr><b><span class="typelabel">class</span>&nbsp;<tt id='l2h-3110' xml:id='l2h-3110' class="class">Stats</tt></b>(</nobr></td>
178 <td><var>filename</var><big>[</big><var>, ...</var><big>]</big><var></var>)</td></tr></table></dt>
179<dd>
180This class constructor creates an instance of a ``statistics object''
181from a <var>filename</var> (or set of filenames). <tt class="class">Stats</tt> objects are
182manipulated by methods, in order to print useful reports.
183
184<P>
185The file selected by the above constructor must have been created by
186the corresponding version of <tt class="module">profile</tt>. To be specific, there is
187<em>no</em> file compatibility guaranteed with future versions of this
188profiler, and there is no compatibility with files produced by other
189profilers (such as the old system profiler).
190
191<P>
192If several files are provided, all the statistics for identical
193functions will be coalesced, so that an overall view of several
194processes can be considered in a single report. If additional files
195need to be combined with data in an existing <tt class="class">Stats</tt> object, the
196<tt class="method">add()</tt> method can be used.
197</dl>
198
199<P>
200
201<p><br /></p><hr class='online-navigation' />
202<div class='online-navigation'>
203<!--Table of Child-Links-->
204<A NAME="CHILD_LINKS"><STRONG>Subsections</STRONG></a>
205
206<UL CLASS="ChildLinks">
207<LI><A href="profile-stats.html">10.5.1 The <tt class="class">Stats</tt> Class</a>
208</ul>
209<!--End of Table of Child-Links-->
210</div>
211
212<DIV CLASS="navigation">
213<div class='online-navigation'>
214<p></p><hr />
215<table align="center" width="100%" cellpadding="0" cellspacing="2">
216<tr>
217<td class='online-navigation'><a rel="prev" title="10.4 What Is Deterministic"
218 href="node453.html"><img src='../icons/previous.png'
219 border='0' height='32' alt='Previous Page' width='32' /></A></td>
220<td class='online-navigation'><a rel="parent" title="10. The Python Profiler"
221 href="profile.html"><img src='../icons/up.png'
222 border='0' height='32' alt='Up One Level' width='32' /></A></td>
223<td class='online-navigation'><a rel="next" title="10.5.1 The Stats Class"
224 href="profile-stats.html"><img src='../icons/next.png'
225 border='0' height='32' alt='Next Page' width='32' /></A></td>
226<td align="center" width="100%">Python Library Reference</td>
227<td class='online-navigation'><a rel="contents" title="Table of Contents"
228 href="contents.html"><img src='../icons/contents.png'
229 border='0' height='32' alt='Contents' width='32' /></A></td>
230<td class='online-navigation'><a href="modindex.html" title="Module Index"><img src='../icons/modules.png'
231 border='0' height='32' alt='Module Index' width='32' /></a></td>
232<td class='online-navigation'><a rel="index" title="Index"
233 href="genindex.html"><img src='../icons/index.png'
234 border='0' height='32' alt='Index' width='32' /></A></td>
235</tr></table>
236<div class='online-navigation'>
237<b class="navlabel">Previous:</b>
238<a class="sectref" rel="prev" href="node453.html">10.4 What Is Deterministic</A>
239<b class="navlabel">Up:</b>
240<a class="sectref" rel="parent" href="profile.html">10. The Python Profiler</A>
241<b class="navlabel">Next:</b>
242<a class="sectref" rel="next" href="profile-stats.html">10.5.1 The Stats Class</A>
243</div>
244</div>
245<hr />
246<span class="release-info">Release 2.4.2, documentation updated on 28 September 2005.</span>
247</DIV>
248<!--End of Navigation Panel-->
249<ADDRESS>
250See <i><a href="about.html">About this document...</a></i> for information on suggesting changes.
251</ADDRESS>
252</BODY>
253</HTML>
Full OpenSPARC architecture tarball including simulator, hypervisor, and OBP.