Mercurial > cpython-lru_cache-weakref

annotate Doc/lib/libprofile.tex @ 4566:6403c94de50d legacy-trunk

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Added safeguard against failure in __del__.
author Guido van Rossum <guido@python.org>
date Wed, 27 Nov 1996 19:39:58 +0000
parents 827338699094
children b218f294b726
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
2465
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
1 \chapter{The Python Profiler}
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
2 \stmodindex{profile}
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
3 \stmodindex{pstats}
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
4
2576
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents: 2491
diff changeset
5 Copyright \copyright\ 1994, by InfoSeek Corporation, all rights reserved.
2465
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
6
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
7 Written by James Roskind%
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
8 \footnote{
2491
fb8e08ec88dd changes (suggested) by Soren Larsen
Guido van Rossum <guido@python.org>
parents: 2465
diff changeset
9 Updated and converted to \LaTeX\ by Guido van Rossum. The references to
2465
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
10 the old profiler are left in the text, although it no longer exists.
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
11 }
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
12
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
13 Permission to use, copy, modify, and distribute this Python software
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
14 and its associated documentation for any purpose (subject to the
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
15 restriction in the following sentence) without fee is hereby granted,
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
16 provided that the above copyright notice appears in all copies, and
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
17 that both that copyright notice and this permission notice appear in
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
18 supporting documentation, and that the name of InfoSeek not be used in
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
19 advertising or publicity pertaining to distribution of the software
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
20 without specific, written prior permission. This permission is
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
21 explicitly restricted to the copying and modification of the software
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
22 to remain in Python, compiled Python, or other languages (such as C)
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
23 wherein the modified or derived code is exclusively imported into a
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
24 Python module.
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
25
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
26 INFOSEEK CORPORATION DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
27 SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
28 FITNESS. IN NO EVENT SHALL INFOSEEK CORPORATION BE LIABLE FOR ANY
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
29 SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
30 RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
31 CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
32 CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
33
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
34
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
35 The profiler was written after only programming in Python for 3 weeks.
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
36 As a result, it is probably clumsy code, but I don't know for sure yet
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
37 'cause I'm a beginner :-). I did work hard to make the code run fast,
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
38 so that profiling would be a reasonable thing to do. I tried not to
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
39 repeat code fragments, but I'm sure I did some stuff in really awkward
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
40 ways at times. Please send suggestions for improvements to:
3377
827338699094 change jars email
Guido van Rossum <guido@python.org>
parents: 2647
diff changeset
41 \code{jar@netscape.com}. I won't promise \emph{any} support. ...but
2465
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
42 I'd appreciate the feedback.
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
43
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
44
2576
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents: 2491
diff changeset
45 \section{Introduction to the profiler}
2581
4d28b655b728 added nodename macro calls for new very long section names
Guido van Rossum <guido@python.org>
parents: 2576
diff changeset
46 \nodename{Profiler Introduction}
2465
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
47
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
48 A \dfn{profiler} is a program that describes the run time performance
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
49 of a program, providing a variety of statistics. This documentation
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
50 describes the profiler functionality provided in the modules
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
51 \code{profile} and \code{pstats.} This profiler provides
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
52 \dfn{deterministic profiling} of any Python programs. It also
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
53 provides a series of report generation tools to allow users to rapidly
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
54 examine the results of a profile operation.
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
55
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
56
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
57 \section{How Is This Profiler Different From The Old Profiler?}
2581
4d28b655b728 added nodename macro calls for new very long section names
Guido van Rossum <guido@python.org>
parents: 2576
diff changeset
58 \nodename{Profiler Changes}
2465
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
59
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
60 The big changes from old profiling module are that you get more
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
61 information, and you pay less CPU time. It's not a trade-off, it's a
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
62 trade-up.
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
63
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
64 To be specific:
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
65
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
66 \begin{description}
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
67
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
68 \item[Bugs removed:]
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
69 Local stack frame is no longer molested, execution time is now charged
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
70 to correct functions.
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
71
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
72 \item[Accuracy increased:]
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
73 Profiler execution time is no longer charged to user's code,
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
74 calibration for platform is supported, file reads are not done \emph{by}
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
75 profiler \emph{during} profiling (and charged to user's code!).
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
76
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
77 \item[Speed increased:]
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
78 Overhead CPU cost was reduced by more than a factor of two (perhaps a
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
79 factor of five), lightweight profiler module is all that must be
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
80 loaded, and the report generating module (\code{pstats}) is not needed
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
81 during profiling.
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
82
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
83 \item[Recursive functions support:]
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
84 Cumulative times in recursive functions are correctly calculated;
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
85 recursive entries are counted.
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
86
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
87 \item[Large growth in report generating UI:]
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
88 Distinct profiles runs can be added together forming a comprehensive
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
89 report; functions that import statistics take arbitrary lists of
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
90 files; sorting criteria is now based on keywords (instead of 4 integer
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
91 options); reports shows what functions were profiled as well as what
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
92 profile file was referenced; output format has been improved.
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
93
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
94 \end{description}
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
95
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
96
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
97 \section{Instant Users Manual}
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
98
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
99 This section is provided for users that ``don't want to read the
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
100 manual.'' It provides a very brief overview, and allows a user to
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
101 rapidly perform profiling on an existing application.
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
102
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
103 To profile an application with a main entry point of \samp{foo()}, you
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
104 would add the following to your module:
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
105
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
106 \begin{verbatim}
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
107 import profile
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
108 profile.run("foo()")
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
109 \end{verbatim}
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
110
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
111 The above action would cause \samp{foo()} to be run, and a series of
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
112 informative lines (the profile) to be printed. The above approach is
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
113 most useful when working with the interpreter. If you would like to
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
114 save the results of a profile into a file for later examination, you
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
115 can supply a file name as the second argument to the \code{run()}
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
116 function:
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
117
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
118 \begin{verbatim}
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
119 import profile
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
120 profile.run("foo()", 'fooprof')
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
121 \end{verbatim}
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
122
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
123 When you wish to review the profile, you should use the methods in the
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
124 \code{pstats} module. Typically you would load the statistics data as
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
125 follows:
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
126
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
127 \begin{verbatim}
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
128 import pstats
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
129 p = pstats.Stats('fooprof')
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
130 \end{verbatim}
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
131
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
132 The class \code{Stats} (the above code just created an instance of
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
133 this class) has a variety of methods for manipulating and printing the
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
134 data that was just read into \samp{p}. When you ran
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
135 \code{profile.run()} above, what was printed was the result of three
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
136 method calls:
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
137
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
138 \begin{verbatim}
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
139 p.strip_dirs().sort_stats(-1).print_stats()
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
140 \end{verbatim}
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
141
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
142 The first method removed the extraneous path from all the module
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
143 names. The second method sorted all the entries according to the
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
144 standard module/line/name string that is printed (this is to comply
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
145 with the semantics of the old profiler). The third method printed out
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
146 all the statistics. You might try the following sort calls:
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
147
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
148 \begin{verbatim}
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
149 p.sort_stats('name')
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
150 p.print_stats()
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
151 \end{verbatim}
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
152
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
153 The first call will actually sort the list by function name, and the
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
154 second call will print out the statistics. The following are some
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
155 interesting calls to experiment with:
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
156
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
157 \begin{verbatim}
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
158 p.sort_stats('cumulative').print_stats(10)
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
159 \end{verbatim}
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
160
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
161 This sorts the profile by cumulative time in a function, and then only
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
162 prints the ten most significant lines. If you want to understand what
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
163 algorithms are taking time, the above line is what you would use.
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
164
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
165 If you were looking to see what functions were looping a lot, and
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
166 taking a lot of time, you would do:
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
167
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
168 \begin{verbatim}
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
169 p.sort_stats('time').print_stats(10)
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
170 \end{verbatim}
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
171
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
172 to sort according to time spent within each function, and then print
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
173 the statistics for the top ten functions.
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
174
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
175 You might also try:
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
176
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
177 \begin{verbatim}
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
178 p.sort_stats('file').print_stats('__init__')
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
179 \end{verbatim}
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
180
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
181 This will sort all the statistics by file name, and then print out
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
182 statistics for only the class init methods ('cause they are spelled
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
183 with \code{__init__} in them). As one final example, you could try:
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
184
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
185 \begin{verbatim}
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
186 p.sort_stats('time', 'cum').print_stats(.5, 'init')
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
187 \end{verbatim}
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
188
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
189 This line sorts statistics with a primary key of time, and a secondary
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
190 key of cumulative time, and then prints out some of the statistics.
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
191 To be specific, the list is first culled down to 50\% (re: \samp{.5})
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
192 of its original size, then only lines containing \code{init} are
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
193 maintained, and that sub-sub-list is printed.
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
194
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
195 If you wondered what functions called the above functions, you could
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
196 now (\samp{p} is still sorted according to the last criteria) do:
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
197
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
198 \begin{verbatim}
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
199 p.print_callers(.5, 'init')
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
200 \end{verbatim}
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
201
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
202 and you would get a list of callers for each of the listed functions.
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
203
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
204 If you want more functionality, you're going to have to read the
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
205 manual, or guess what the following functions do:
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
206
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
207 \begin{verbatim}
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
208 p.print_callees()
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
209 p.add('fooprof')
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
210 \end{verbatim}
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
211
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
212
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
213 \section{What Is Deterministic Profiling?}
2581
4d28b655b728 added nodename macro calls for new very long section names
Guido van Rossum <guido@python.org>
parents: 2576
diff changeset
214 \nodename{Deterministic Profiling}
2465
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
215
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
216 \dfn{Deterministic profiling} is meant to reflect the fact that all
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
217 \dfn{function call}, \dfn{function return}, and \dfn{exception} events
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
218 are monitored, and precise timings are made for the intervals between
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
219 these events (during which time the user's code is executing). In
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
220 contrast, \dfn{statistical profiling} (which is not done by this
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
221 module) randomly samples the effective instruction pointer, and
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
222 deduces where time is being spent. The latter technique traditionally
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
223 involves less overhead (as the code does not need to be instrumented),
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
224 but provides only relative indications of where time is being spent.
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
225
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
226 In Python, since there is an interpreter active during execution, the
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
227 presence of instrumented code is not required to do deterministic
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
228 profiling. Python automatically provides a \dfn{hook} (optional
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
229 callback) for each event. In addition, the interpreted nature of
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
230 Python tends to add so much overhead to execution, that deterministic
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
231 profiling tends to only add small processing overhead in typical
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
232 applications. The result is that deterministic profiling is not that
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
233 expensive, yet provides extensive run time statistics about the
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
234 execution of a Python program.
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
235
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
236 Call count statistics can be used to identify bugs in code (surprising
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
237 counts), and to identify possible inline-expansion points (high call
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
238 counts). Internal time statistics can be used to identify ``hot
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
239 loops'' that should be carefully optimized. Cumulative time
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
240 statistics should be used to identify high level errors in the
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
241 selection of algorithms. Note that the unusual handling of cumulative
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
242 times in this profiler allows statistics for recursive implementations
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
243 of algorithms to be directly compared to iterative implementations.
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
244
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
245
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
246 \section{Reference Manual}
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
247
2576
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents: 2491
diff changeset
248 \renewcommand{\indexsubitem}{(profiler function)}
2465
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
249
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
250 The primary entry point for the profiler is the global function
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
251 \code{profile.run()}. It is typically used to create any profile
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
252 information. The reports are formatted and printed using methods of
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
253 the class \code{pstats.Stats}. The following is a description of all
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
254 of these standard entry points and functions. For a more in-depth
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
255 view of some of the code, consider reading the later section on
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
256 Profiler Extensions, which includes discussion of how to derive
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
257 ``better'' profilers from the classes presented, or reading the source
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
258 code for these modules.
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
259
2576
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents: 2491
diff changeset
260 \begin{funcdesc}{profile.run}{string\optional{\, filename\optional{\, ...}}}
2465
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
261
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
262 This function takes a single argument that has can be passed to the
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
263 \code{exec} statement, and an optional file name. In all cases this
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
264 routine attempts to \code{exec} its first argument, and gather profiling
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
265 statistics from the execution. If no file name is present, then this
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
266 function automatically prints a simple profiling report, sorted by the
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
267 standard name string (file/line/function-name) that is presented in
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
268 each line. The following is a typical output from such a call:
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
269
2647
9b7e6d9a528d typos, layout and other small things
Guido van Rossum <guido@python.org>
parents: 2596
diff changeset
270 \small{
2465
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
271 \begin{verbatim}
2647
9b7e6d9a528d typos, layout and other small things
Guido van Rossum <guido@python.org>
parents: 2596
diff changeset
272 main()
9b7e6d9a528d typos, layout and other small things
Guido van Rossum <guido@python.org>
parents: 2596
diff changeset
273 2706 function calls (2004 primitive calls) in 4.504 CPU seconds
2465
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
274
2647
9b7e6d9a528d typos, layout and other small things
Guido van Rossum <guido@python.org>
parents: 2596
diff changeset
275 Ordered by: standard name
2465
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
276
2647
9b7e6d9a528d typos, layout and other small things
Guido van Rossum <guido@python.org>
parents: 2596
diff changeset
277 ncalls tottime percall cumtime percall filename:lineno(function)
9b7e6d9a528d typos, layout and other small things
Guido van Rossum <guido@python.org>
parents: 2596
diff changeset
278 2 0.006 0.003 0.953 0.477 pobject.py:75(save_objects)
9b7e6d9a528d typos, layout and other small things
Guido van Rossum <guido@python.org>
parents: 2596
diff changeset
279 43/3 0.533 0.012 0.749 0.250 pobject.py:99(evaluate)
9b7e6d9a528d typos, layout and other small things
Guido van Rossum <guido@python.org>
parents: 2596
diff changeset
280 ...
2465
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
281 \end{verbatim}
2647
9b7e6d9a528d typos, layout and other small things
Guido van Rossum <guido@python.org>
parents: 2596
diff changeset
282 }
2465
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
283
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
284 The first line indicates that this profile was generated by the call:\\
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
285 \code{profile.run('main()')}, and hence the exec'ed string is
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
286 \code{'main()'}. The second line indicates that 2706 calls were
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
287 monitored. Of those calls, 2004 were \dfn{primitive}. We define
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
288 \dfn{primitive} to mean that the call was not induced via recursion.
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
289 The next line: \code{Ordered by:\ standard name}, indicates that
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
290 the text string in the far right column was used to sort the output.
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
291 The column headings include:
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
292
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
293 \begin{description}
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
294
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
295 \item[ncalls ]
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
296 for the number of calls,
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
297
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
298 \item[tottime ]
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
299 for the total time spent in the given function (and excluding time
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
300 made in calls to sub-functions),
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
301
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
302 \item[percall ]
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
303 is the quotient of \code{tottime} divided by \code{ncalls}
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
304
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
305 \item[cumtime ]
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
306 is the total time spent in this and all subfunctions (i.e., from
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
307 invocation till exit). This figure is accurate \emph{even} for recursive
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
308 functions.
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
309
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
310 \item[percall ]
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
311 is the quotient of \code{cumtime} divided by primitive calls
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
312
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
313 \item[filename:lineno(function) ]
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
314 provides the respective data of each function
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
315
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
316 \end{description}
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
317
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
318 When there are two numbers in the first column (e.g.: \samp{43/3}),
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
319 then the latter is the number of primitive calls, and the former is
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
320 the actual number of calls. Note that when the function does not
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
321 recurse, these two values are the same, and only the single figure is
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
322 printed.
2647
9b7e6d9a528d typos, layout and other small things
Guido van Rossum <guido@python.org>
parents: 2596
diff changeset
323
2465
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
324 \end{funcdesc}
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
325
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
326 \begin{funcdesc}{pstats.Stats}{filename\optional{\, ...}}
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
327 This class constructor creates an instance of a ``statistics object''
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
328 from a \var{filename} (or set of filenames). \code{Stats} objects are
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
329 manipulated by methods, in order to print useful reports.
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
330
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
331 The file selected by the above constructor must have been created by
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
332 the corresponding version of \code{profile}. To be specific, there is
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
333 \emph{NO} file compatibility guaranteed with future versions of this
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
334 profiler, and there is no compatibility with files produced by other
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
335 profilers (e.g., the old system profiler).
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
336
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
337 If several files are provided, all the statistics for identical
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
338 functions will be coalesced, so that an overall view of several
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
339 processes can be considered in a single report. If additional files
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
340 need to be combined with data in an existing \code{Stats} object, the
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
341 \code{add()} method can be used.
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
342 \end{funcdesc}
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
343
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
344
2576
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents: 2491
diff changeset
345 \subsection{The \sectcode{Stats} Class}
2465
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
346
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
347 \renewcommand{\indexsubitem}{(Stats method)}
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
348
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
349 \begin{funcdesc}{strip_dirs}{}
2576
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents: 2491
diff changeset
350 This method for the \code{Stats} class removes all leading path information
2465
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
351 from file names. It is very useful in reducing the size of the
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
352 printout to fit within (close to) 80 columns. This method modifies
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
353 the object, and the stripped information is lost. After performing a
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
354 strip operation, the object is considered to have its entries in a
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
355 ``random'' order, as it was just after object initialization and
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
356 loading. If \code{strip_dirs()} causes two function names to be
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
357 indistinguishable (i.e., they are on the same line of the same
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
358 filename, and have the same function name), then the statistics for
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
359 these two entries are accumulated into a single entry.
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
360 \end{funcdesc}
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
361
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
362
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
363 \begin{funcdesc}{add}{filename\optional{\, ...}}
2576
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents: 2491
diff changeset
364 This method of the \code{Stats} class accumulates additional profiling
2465
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
365 information into the current profiling object. Its arguments should
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
366 refer to filenames created by the corresponding version of
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
367 \code{profile.run()}. Statistics for identically named (re: file,
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
368 line, name) functions are automatically accumulated into single
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
369 function statistics.
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
370 \end{funcdesc}
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
371
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
372 \begin{funcdesc}{sort_stats}{key\optional{\, ...}}
2576
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents: 2491
diff changeset
373 This method modifies the \code{Stats} object by sorting it according to the
2465
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
374 supplied criteria. The argument is typically a string identifying the
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
375 basis of a sort (example: \code{"time"} or \code{"name"}).
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
376
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
377 When more than one key is provided, then additional keys are used as
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
378 secondary criteria when the there is equality in all keys selected
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
379 before them. For example, sort_stats('name', 'file') will sort all
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
380 the entries according to their function name, and resolve all ties
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
381 (identical function names) by sorting by file name.
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
382
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
383 Abbreviations can be used for any key names, as long as the
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
384 abbreviation is unambiguous. The following are the keys currently
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
385 defined:
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
386
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
387 \begin{tableii}{|l|l|}{code}{Valid Arg}{Meaning}
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
388 \lineii{"calls"}{call count}
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
389 \lineii{"cumulative"}{cumulative time}
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
390 \lineii{"file"}{file name}
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
391 \lineii{"module"}{file name}
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
392 \lineii{"pcalls"}{primitive call count}
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
393 \lineii{"line"}{line number}
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
394 \lineii{"name"}{function name}
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
395 \lineii{"nfl"}{name/file/line}
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
396 \lineii{"stdname"}{standard name}
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
397 \lineii{"time"}{internal time}
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
398 \end{tableii}
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
399
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
400 Note that all sorts on statistics are in descending order (placing
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
401 most time consuming items first), where as name, file, and line number
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
402 searches are in ascending order (i.e., alphabetical). The subtle
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
403 distinction between \code{"nfl"} and \code{"stdname"} is that the
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
404 standard name is a sort of the name as printed, which means that the
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
405 embedded line numbers get compared in an odd way. For example, lines
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
406 3, 20, and 40 would (if the file names were the same) appear in the
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
407 string order 20, 3 and 40. In contrast, \code{"nfl"} does a numeric
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
408 compare of the line numbers. In fact, \code{sort_stats("nfl")} is the
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
409 same as \code{sort_stats("name", "file", "line")}.
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
410
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
411 For compatibility with the old profiler, the numeric arguments
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
412 \samp{-1}, \samp{0}, \samp{1}, and \samp{2} are permitted. They are
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
413 interpreted as \code{"stdname"}, \code{"calls"}, \code{"time"}, and
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
414 \code{"cumulative"} respectively. If this old style format (numeric)
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
415 is used, only one sort key (the numeric key) will be used, and
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
416 additional arguments will be silently ignored.
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
417 \end{funcdesc}
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
418
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
419
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
420 \begin{funcdesc}{reverse_order}{}
2576
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents: 2491
diff changeset
421 This method for the \code{Stats} class reverses the ordering of the basic
2465
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
422 list within the object. This method is provided primarily for
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
423 compatibility with the old profiler. Its utility is questionable
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
424 now that ascending vs descending order is properly selected based on
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
425 the sort key of choice.
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
426 \end{funcdesc}
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
427
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
428 \begin{funcdesc}{print_stats}{restriction\optional{\, ...}}
2576
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents: 2491
diff changeset
429 This method for the \code{Stats} class prints out a report as described
2465
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
430 in the \code{profile.run()} definition.
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
431
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
432 The order of the printing is based on the last \code{sort_stats()}
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
433 operation done on the object (subject to caveats in \code{add()} and
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
434 \code{strip_dirs())}.
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
435
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
436 The arguments provided (if any) can be used to limit the list down to
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
437 the significant entries. Initially, the list is taken to be the
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
438 complete set of profiled functions. Each restriction is either an
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
439 integer (to select a count of lines), or a decimal fraction between
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
440 0.0 and 1.0 inclusive (to select a percentage of lines), or a regular
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
441 expression (to pattern match the standard name that is printed). If
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
442 several restrictions are provided, then they are applied sequentially.
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
443 For example:
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
444
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
445 \begin{verbatim}
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
446 print_stats(.1, "foo:")
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
447 \end{verbatim}
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
448
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
449 would first limit the printing to first 10\% of list, and then only
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
450 print functions that were part of filename \samp{.*foo:}. In
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
451 contrast, the command:
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
452
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
453 \begin{verbatim}
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
454 print_stats("foo:", .1)
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
455 \end{verbatim}
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
456
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
457 would limit the list to all functions having file names \samp{.*foo:},
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
458 and then proceed to only print the first 10\% of them.
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
459 \end{funcdesc}
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
460
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
461
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
462 \begin{funcdesc}{print_callers}{restrictions\optional{\, ...}}
2576
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents: 2491
diff changeset
463 This method for the \code{Stats} class prints a list of all functions
2465
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
464 that called each function in the profiled database. The ordering is
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
465 identical to that provided by \code{print_stats()}, and the definition
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
466 of the restricting argument is also identical. For convenience, a
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
467 number is shown in parentheses after each caller to show how many
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
468 times this specific call was made. A second non-parenthesized number
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
469 is the cumulative time spent in the function at the right.
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
470 \end{funcdesc}
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
471
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
472 \begin{funcdesc}{print_callees}{restrictions\optional{\, ...}}
2576
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents: 2491
diff changeset
473 This method for the \code{Stats} class prints a list of all function
2465
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
474 that were called by the indicated function. Aside from this reversal
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
475 of direction of calls (re: called vs was called by), the arguments and
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
476 ordering are identical to the \code{print_callers()} method.
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
477 \end{funcdesc}
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
478
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
479 \begin{funcdesc}{ignore}{}
2576
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents: 2491
diff changeset
480 This method of the \code{Stats} class is used to dispose of the value
2465
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
481 returned by earlier methods. All standard methods in this class
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
482 return the instance that is being processed, so that the commands can
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
483 be strung together. For example:
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
484
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
485 \begin{verbatim}
2647
9b7e6d9a528d typos, layout and other small things
Guido van Rossum <guido@python.org>
parents: 2596
diff changeset
486 pstats.Stats('foofile').strip_dirs().sort_stats('cum') \
9b7e6d9a528d typos, layout and other small things
Guido van Rossum <guido@python.org>
parents: 2596
diff changeset
487 .print_stats().ignore()
2465
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
488 \end{verbatim}
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
489
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
490 would perform all the indicated functions, but it would not return
2576
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents: 2491
diff changeset
491 the final reference to the \code{Stats} instance.%
2465
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
492 \footnote{
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
493 This was once necessary, when Python would print any unused expression
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
494 result that was not \code{None}. The method is still defined for
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
495 backward compatibility.
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
496 }
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
497 \end{funcdesc}
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
498
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
499
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
500 \section{Limitations}
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
501
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
502 There are two fundamental limitations on this profiler. The first is
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
503 that it relies on the Python interpreter to dispatch \dfn{call},
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
504 \dfn{return}, and \dfn{exception} events. Compiled C code does not
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
505 get interpreted, and hence is ``invisible'' to the profiler. All time
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
506 spent in C code (including builtin functions) will be charged to the
2596
31777622ae93 some new material
Guido van Rossum <guido@python.org>
parents: 2581
diff changeset
507 Python function that invoked the C code. If the C code calls out
2465
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
508 to some native Python code, then those calls will be profiled
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
509 properly.
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
510
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
511 The second limitation has to do with accuracy of timing information.
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
512 There is a fundamental problem with deterministic profilers involving
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
513 accuracy. The most obvious restriction is that the underlying ``clock''
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
514 is only ticking at a rate (typically) of about .001 seconds. Hence no
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
515 measurements will be more accurate that that underlying clock. If
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
516 enough measurements are taken, then the ``error'' will tend to average
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
517 out. Unfortunately, removing this first error induces a second source
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
518 of error...
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
519
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
520 The second problem is that it ``takes a while'' from when an event is
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
521 dispatched until the profiler's call to get the time actually
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
522 \emph{gets} the state of the clock. Similarly, there is a certain lag
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
523 when exiting the profiler event handler from the time that the clock's
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
524 value was obtained (and then squirreled away), until the user's code
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
525 is once again executing. As a result, functions that are called many
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
526 times, or call many functions, will typically accumulate this error.
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
527 The error that accumulates in this fashion is typically less than the
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
528 accuracy of the clock (i.e., less than one clock tick), but it
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
529 \emph{can} accumulate and become very significant. This profiler
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
530 provides a means of calibrating itself for a given platform so that
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
531 this error can be probabilistically (i.e., on the average) removed.
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
532 After the profiler is calibrated, it will be more accurate (in a least
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
533 square sense), but it will sometimes produce negative numbers (when
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
534 call counts are exceptionally low, and the gods of probability work
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
535 against you :-). ) Do \emph{NOT} be alarmed by negative numbers in
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
536 the profile. They should \emph{only} appear if you have calibrated
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
537 your profiler, and the results are actually better than without
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
538 calibration.
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
539
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
540
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
541 \section{Calibration}
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
542
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
543 The profiler class has a hard coded constant that is added to each
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
544 event handling time to compensate for the overhead of calling the time
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
545 function, and socking away the results. The following procedure can
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
546 be used to obtain this constant for a given platform (see discussion
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
547 in section Limitations above).
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
548
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
549 \begin{verbatim}
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
550 import profile
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
551 pr = profile.Profile()
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
552 pr.calibrate(100)
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
553 pr.calibrate(100)
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
554 pr.calibrate(100)
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
555 \end{verbatim}
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
556
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
557 The argument to calibrate() is the number of times to try to do the
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
558 sample calls to get the CPU times. If your computer is \emph{very}
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
559 fast, you might have to do:
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
560
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
561 \begin{verbatim}
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
562 pr.calibrate(1000)
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
563 \end{verbatim}
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
564
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
565 or even:
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
566
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
567 \begin{verbatim}
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
568 pr.calibrate(10000)
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
569 \end{verbatim}
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
570
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
571 The object of this exercise is to get a fairly consistent result.
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
572 When you have a consistent answer, you are ready to use that number in
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
573 the source code. For a Sun Sparcstation 1000 running Solaris 2.3, the
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
574 magical number is about .00053. If you have a choice, you are better
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
575 off with a smaller constant, and your results will ``less often'' show
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
576 up as negative in profile statistics.
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
577
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
578 The following shows how the trace_dispatch() method in the Profile
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
579 class should be modified to install the calibration constant on a Sun
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
580 Sparcstation 1000:
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
581
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
582 \begin{verbatim}
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
583 def trace_dispatch(self, frame, event, arg):
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
584 t = self.timer()
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
585 t = t[0] + t[1] - self.t - .00053 # Calibration constant
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
586
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
587 if self.dispatch[event](frame,t):
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
588 t = self.timer()
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
589 self.t = t[0] + t[1]
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
590 else:
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
591 r = self.timer()
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
592 self.t = r[0] + r[1] - t # put back unrecorded delta
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
593 return
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
594 \end{verbatim}
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
595
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
596 Note that if there is no calibration constant, then the line
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
597 containing the callibration constant should simply say:
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
598
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
599 \begin{verbatim}
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
600 t = t[0] + t[1] - self.t # no calibration constant
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
601 \end{verbatim}
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
602
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
603 You can also achieve the same results using a derived class (and the
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
604 profiler will actually run equally fast!!), but the above method is
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
605 the simplest to use. I could have made the profiler ``self
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
606 calibrating'', but it would have made the initialization of the
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
607 profiler class slower, and would have required some \emph{very} fancy
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
608 coding, or else the use of a variable where the constant \samp{.00053}
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
609 was placed in the code shown. This is a \strong{VERY} critical
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
610 performance section, and there is no reason to use a variable lookup
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
611 at this point, when a constant can be used.
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
612
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
613
2581
4d28b655b728 added nodename macro calls for new very long section names
Guido van Rossum <guido@python.org>
parents: 2576
diff changeset
614 \section{Extensions --- Deriving Better Profilers}
4d28b655b728 added nodename macro calls for new very long section names
Guido van Rossum <guido@python.org>
parents: 2576
diff changeset
615 \nodename{Profiler Extensions}
2465
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
616
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
617 The \code{Profile} class of module \code{profile} was written so that
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
618 derived classes could be developed to extend the profiler. Rather
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
619 than describing all the details of such an effort, I'll just present
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
620 the following two examples of derived classes that can be used to do
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
621 profiling. If the reader is an avid Python programmer, then it should
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
622 be possible to use these as a model and create similar (and perchance
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
623 better) profile classes.
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
624
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
625 If all you want to do is change how the timer is called, or which
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
626 timer function is used, then the basic class has an option for that in
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
627 the constructor for the class. Consider passing the name of a
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
628 function to call into the constructor:
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
629
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
630 \begin{verbatim}
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
631 pr = profile.Profile(your_time_func)
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
632 \end{verbatim}
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
633
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
634 The resulting profiler will call \code{your_time_func()} instead of
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
635 \code{os.times()}. The function should return either a single number
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
636 or a list of numbers (like what \code{os.times()} returns). If the
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
637 function returns a single time number, or the list of returned numbers
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
638 has length 2, then you will get an especially fast version of the
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
639 dispatch routine.
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
640
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
641 Be warned that you \emph{should} calibrate the profiler class for the
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
642 timer function that you choose. For most machines, a timer that
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
643 returns a lone integer value will provide the best results in terms of
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
644 low overhead during profiling. (os.times is \emph{pretty} bad, 'cause
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
645 it returns a tuple of floating point values, so all arithmetic is
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
646 floating point in the profiler!). If you want to substitute a
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
647 better timer in the cleanest fashion, you should derive a class, and
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
648 simply put in the replacement dispatch method that better handles your
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
649 timer call, along with the appropriate calibration constant :-).
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
650
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
651
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
652 \subsection{OldProfile Class}
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
653
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
654 The following derived profiler simulates the old style profiler,
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
655 providing errant results on recursive functions. The reason for the
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
656 usefulness of this profiler is that it runs faster (i.e., less
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
657 overhead) than the old profiler. It still creates all the caller
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
658 stats, and is quite useful when there is \emph{no} recursion in the
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
659 user's code. It is also a lot more accurate than the old profiler, as
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
660 it does not charge all its overhead time to the user's code.
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
661
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
662 \begin{verbatim}
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
663 class OldProfile(Profile):
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
664
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
665 def trace_dispatch_exception(self, frame, t):
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
666 rt, rtt, rct, rfn, rframe, rcur = self.cur
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
667 if rcur and not rframe is frame:
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
668 return self.trace_dispatch_return(rframe, t)
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
669 return 0
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
670
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
671 def trace_dispatch_call(self, frame, t):
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
672 fn = `frame.f_code`
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
673
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
674 self.cur = (t, 0, 0, fn, frame, self.cur)
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
675 if self.timings.has_key(fn):
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
676 tt, ct, callers = self.timings[fn]
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
677 self.timings[fn] = tt, ct, callers
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
678 else:
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
679 self.timings[fn] = 0, 0, {}
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
680 return 1
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
681
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
682 def trace_dispatch_return(self, frame, t):
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
683 rt, rtt, rct, rfn, frame, rcur = self.cur
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
684 rtt = rtt + t
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
685 sft = rtt + rct
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
686
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
687 pt, ptt, pct, pfn, pframe, pcur = rcur
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
688 self.cur = pt, ptt+rt, pct+sft, pfn, pframe, pcur
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
689
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
690 tt, ct, callers = self.timings[rfn]
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
691 if callers.has_key(pfn):
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
692 callers[pfn] = callers[pfn] + 1
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
693 else:
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
694 callers[pfn] = 1
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
695 self.timings[rfn] = tt+rtt, ct + sft, callers
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
696
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
697 return 1
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
698
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
699
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
700 def snapshot_stats(self):
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
701 self.stats = {}
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
702 for func in self.timings.keys():
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
703 tt, ct, callers = self.timings[func]
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
704 nor_func = self.func_normalize(func)
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
705 nor_callers = {}
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
706 nc = 0
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
707 for func_caller in callers.keys():
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
708 nor_callers[self.func_normalize(func_caller)]=\
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
709 callers[func_caller]
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
710 nc = nc + callers[func_caller]
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
711 self.stats[nor_func] = nc, nc, tt, ct, nor_callers
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
712 \end{verbatim}
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
713
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
714
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
715 \subsection{HotProfile Class}
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
716
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
717 This profiler is the fastest derived profile example. It does not
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
718 calculate caller-callee relationships, and does not calculate
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
719 cumulative time under a function. It only calculates time spent in a
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
720 function, so it runs very quickly (re: very low overhead). In truth,
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
721 the basic profiler is so fast, that is probably not worth the savings
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
722 to give up the data, but this class still provides a nice example.
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
723
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
724 \begin{verbatim}
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
725 class HotProfile(Profile):
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
726
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
727 def trace_dispatch_exception(self, frame, t):
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
728 rt, rtt, rfn, rframe, rcur = self.cur
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
729 if rcur and not rframe is frame:
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
730 return self.trace_dispatch_return(rframe, t)
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
731 return 0
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
732
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
733 def trace_dispatch_call(self, frame, t):
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
734 self.cur = (t, 0, frame, self.cur)
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
735 return 1
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
736
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
737 def trace_dispatch_return(self, frame, t):
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
738 rt, rtt, frame, rcur = self.cur
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
739
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
740 rfn = `frame.f_code`
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
741
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
742 pt, ptt, pframe, pcur = rcur
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
743 self.cur = pt, ptt+rt, pframe, pcur
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
744
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
745 if self.timings.has_key(rfn):
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
746 nc, tt = self.timings[rfn]
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
747 self.timings[rfn] = nc + 1, rt + rtt + tt
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
748 else:
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
749 self.timings[rfn] = 1, rt + rtt
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
750
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
751 return 1
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
752
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
753
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
754 def snapshot_stats(self):
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
755 self.stats = {}
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
756 for func in self.timings.keys():
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
757 nc, tt = self.timings[func]
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
758 nor_func = self.func_normalize(func)
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
759 self.stats[nor_func] = nc, nc, tt, 0, {}
1f4141aafe36 converted docs for Jim Roskind's profiler
Guido van Rossum <guido@python.org>
parents:
diff changeset
760 \end{verbatim}