cpython-lru_cache-weakref: Doc/lib/libprofile.tex annotate

annotate Doc/lib/libprofile.tex @ 21467:4e35fa5d5708 legacy-trunk

Add documentation for the help() built-in; contributed by Ka-Ping Yee. This is part of SF patch #494622.

author	Fred Drake <fdrake@acm.org>
date	Tue, 18 Dec 2001 16:31:08 +0000
parents	33dac6181be5
children	e6691ce91b9f 85406045f014

rev	line source
10520 7ee1e3134147 Fixed latex2html weirdness with footnotes. Fred Drake <fdrake@acm.org> parents: 8716 diff changeset	1 \chapter{The Python Profiler \label{profile}}
7ee1e3134147 Fixed latex2html weirdness with footnotes. Fred Drake <fdrake@acm.org> parents: 8716 diff changeset	2
7ee1e3134147 Fixed latex2html weirdness with footnotes. Fred Drake <fdrake@acm.org> parents: 8716 diff changeset	3 \sectionauthor{James Roskind}{}
2465 1f4141aafe36 converted docs for Jim Roskind's profiler Guido van Rossum <guido@python.org> parents: diff changeset	4
4728 b218f294b726 (lib<all sorts of stuff>.tex): Fred Drake <fdrake@acm.org> parents: 3377 diff changeset	5 Copyright \copyright{} 1994, by InfoSeek Corporation, all rights reserved.
7822 d1b23504bd99 Index entries. Fred Drake <fdrake@acm.org> parents: 7797 diff changeset	6 \index{InfoSeek Corporation}
2465 1f4141aafe36 converted docs for Jim Roskind's profiler Guido van Rossum <guido@python.org> parents: diff changeset	7
10520 7ee1e3134147 Fixed latex2html weirdness with footnotes. Fred Drake <fdrake@acm.org> parents: 8716 diff changeset	8 Written by James Roskind.\footnote{
7ee1e3134147 Fixed latex2html weirdness with footnotes. Fred Drake <fdrake@acm.org> parents: 8716 diff changeset	9 Updated and converted to \LaTeX\ by Guido van Rossum. The references to
7ee1e3134147 Fixed latex2html weirdness with footnotes. Fred Drake <fdrake@acm.org> parents: 8716 diff changeset	10 the old profiler are left in the text, although it no longer exists.}
2465 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 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	13 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	14 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	15 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	16 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	17 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	18 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	19 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	20 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	21 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	22 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	23 Python module.
1f4141aafe36 converted docs for Jim Roskind's profiler Guido van Rossum <guido@python.org> parents: diff changeset	24
1f4141aafe36 converted docs for Jim Roskind's profiler Guido van Rossum <guido@python.org> parents: diff changeset	25 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	26 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	27 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	28 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	29 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	30 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	31 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	32
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 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	35 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	36 '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	37 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	38 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	39 ways at times. Please send suggestions for improvements to:
7498 1906a7fc7509 Logical markup. Fred Drake <fdrake@acm.org> parents: 7453 diff changeset	40 \email{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	41 I'd appreciate the feedback.
1f4141aafe36 converted docs for Jim Roskind's profiler Guido van Rossum <guido@python.org> parents: diff changeset	42
1f4141aafe36 converted docs for Jim Roskind's profiler Guido van Rossum <guido@python.org> parents: diff changeset	43
2576 f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications; Guido van Rossum <guido@python.org> parents: 2491 diff changeset	44 \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	45 \nodename{Profiler Introduction}
2465 1f4141aafe36 converted docs for Jim Roskind's profiler Guido van Rossum <guido@python.org> parents: diff changeset	46
1f4141aafe36 converted docs for Jim Roskind's profiler Guido van Rossum <guido@python.org> parents: diff changeset	47 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	48 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	49 describes the profiler functionality provided in the modules
7498 1906a7fc7509 Logical markup. Fred Drake <fdrake@acm.org> parents: 7453 diff changeset	50 \module{profile} and \module{pstats}. This profiler provides
2465 1f4141aafe36 converted docs for Jim Roskind's profiler Guido van Rossum <guido@python.org> parents: diff changeset	51 \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	52 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	53 examine the results of a profile operation.
7498 1906a7fc7509 Logical markup. Fred Drake <fdrake@acm.org> parents: 7453 diff changeset	54 \index{deterministic profiling}
1906a7fc7509 Logical markup. Fred Drake <fdrake@acm.org> parents: 7453 diff changeset	55 \index{profiling, deterministic}
2465 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
1f4141aafe36 converted docs for Jim Roskind's profiler Guido van Rossum <guido@python.org> parents: diff changeset	58 \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	59 \nodename{Profiler Changes}
2465 1f4141aafe36 converted docs for Jim Roskind's profiler Guido van Rossum <guido@python.org> parents: diff changeset	60
6586 753077f9eb2c Clarified reference to old profiler. Guido van Rossum <guido@python.org> parents: 5818 diff changeset	61 (This section is of historical importance only; the old profiler
753077f9eb2c Clarified reference to old profiler. Guido van Rossum <guido@python.org> parents: 5818 diff changeset	62 discussed here was last seen in Python 1.1.)
753077f9eb2c Clarified reference to old profiler. Guido van Rossum <guido@python.org> parents: 5818 diff changeset	63
2465 1f4141aafe36 converted docs for Jim Roskind's profiler Guido van Rossum <guido@python.org> parents: diff changeset	64 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	65 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	66 trade-up.
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 To be specific:
1f4141aafe36 converted docs for Jim Roskind's profiler Guido van Rossum <guido@python.org> parents: diff changeset	69
1f4141aafe36 converted docs for Jim Roskind's profiler Guido van Rossum <guido@python.org> parents: diff changeset	70 \begin{description}
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[Bugs removed:]
1f4141aafe36 converted docs for Jim Roskind's profiler Guido van Rossum <guido@python.org> parents: diff changeset	73 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	74 to correct functions.
1f4141aafe36 converted docs for Jim Roskind's profiler Guido van Rossum <guido@python.org> parents: diff changeset	75
1f4141aafe36 converted docs for Jim Roskind's profiler Guido van Rossum <guido@python.org> parents: diff changeset	76 \item[Accuracy increased:]
1f4141aafe36 converted docs for Jim Roskind's profiler Guido van Rossum <guido@python.org> parents: diff changeset	77 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	78 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	79 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	80
1f4141aafe36 converted docs for Jim Roskind's profiler Guido van Rossum <guido@python.org> parents: diff changeset	81 \item[Speed increased:]
1f4141aafe36 converted docs for Jim Roskind's profiler Guido van Rossum <guido@python.org> parents: diff changeset	82 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	83 factor of five), lightweight profiler module is all that must be
7498 1906a7fc7509 Logical markup. Fred Drake <fdrake@acm.org> parents: 7453 diff changeset	84 loaded, and the report generating module (\module{pstats}) is not needed
2465 1f4141aafe36 converted docs for Jim Roskind's profiler Guido van Rossum <guido@python.org> parents: diff changeset	85 during profiling.
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[Recursive functions support:]
1f4141aafe36 converted docs for Jim Roskind's profiler Guido van Rossum <guido@python.org> parents: diff changeset	88 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	89 recursive entries are counted.
1f4141aafe36 converted docs for Jim Roskind's profiler Guido van Rossum <guido@python.org> parents: diff changeset	90
1f4141aafe36 converted docs for Jim Roskind's profiler Guido van Rossum <guido@python.org> parents: diff changeset	91 \item[Large growth in report generating UI:]
1f4141aafe36 converted docs for Jim Roskind's profiler Guido van Rossum <guido@python.org> parents: diff changeset	92 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	93 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	94 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	95 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	96 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	97
1f4141aafe36 converted docs for Jim Roskind's profiler Guido van Rossum <guido@python.org> parents: diff changeset	98 \end{description}
1f4141aafe36 converted docs for Jim Roskind's profiler Guido van Rossum <guido@python.org> parents: diff changeset	99
1f4141aafe36 converted docs for Jim Roskind's profiler Guido van Rossum <guido@python.org> parents: diff changeset	100
10667 02eb74749262 Misc. markup nits. Fred Drake <fdrake@acm.org> parents: 10520 diff changeset	101 \section{Instant Users Manual \label{profile-instant}}
2465 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 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	104 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	105 rapidly perform profiling on an existing application.
1f4141aafe36 converted docs for Jim Roskind's profiler Guido van Rossum <guido@python.org> parents: diff changeset	106
1f4141aafe36 converted docs for Jim Roskind's profiler Guido van Rossum <guido@python.org> parents: diff changeset	107 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	108 would add the following to your module:
1f4141aafe36 converted docs for Jim Roskind's profiler Guido van Rossum <guido@python.org> parents: diff changeset	109
7277 bf4e790bd61a Remove all \bcode / \ecode cruft; this is no longer needed. See previous Fred Drake <fdrake@acm.org> parents: 6932 diff changeset	110 \begin{verbatim}
5818 3468ea8645ca AMK's megapatch: Guido van Rossum <guido@python.org> parents: 5681 diff changeset	111 import profile
7938 ca4e25ef61f8 Don't use \samp when \code is better. Fred Drake <fdrake@acm.org> parents: 7913 diff changeset	112 profile.run('foo()')
7277 bf4e790bd61a Remove all \bcode / \ecode cruft; this is no longer needed. See previous Fred Drake <fdrake@acm.org> parents: 6932 diff changeset	113 \end{verbatim}
10667 02eb74749262 Misc. markup nits. Fred Drake <fdrake@acm.org> parents: 10520 diff changeset	114
2465 1f4141aafe36 converted docs for Jim Roskind's profiler Guido van Rossum <guido@python.org> parents: diff changeset	115 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	116 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	117 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	118 save the results of a profile into a file for later examination, you
7498 1906a7fc7509 Logical markup. Fred Drake <fdrake@acm.org> parents: 7453 diff changeset	119 can supply a file name as the second argument to the \function{run()}
2465 1f4141aafe36 converted docs for Jim Roskind's profiler Guido van Rossum <guido@python.org> parents: diff changeset	120 function:
1f4141aafe36 converted docs for Jim Roskind's profiler Guido van Rossum <guido@python.org> parents: diff changeset	121
7277 bf4e790bd61a Remove all \bcode / \ecode cruft; this is no longer needed. See previous Fred Drake <fdrake@acm.org> parents: 6932 diff changeset	122 \begin{verbatim}
5818 3468ea8645ca AMK's megapatch: Guido van Rossum <guido@python.org> parents: 5681 diff changeset	123 import profile
7938 ca4e25ef61f8 Don't use \samp when \code is better. Fred Drake <fdrake@acm.org> parents: 7913 diff changeset	124 profile.run('foo()', 'fooprof')
7277 bf4e790bd61a Remove all \bcode / \ecode cruft; this is no longer needed. See previous Fred Drake <fdrake@acm.org> parents: 6932 diff changeset	125 \end{verbatim}
10667 02eb74749262 Misc. markup nits. Fred Drake <fdrake@acm.org> parents: 10520 diff changeset	126
7498 1906a7fc7509 Logical markup. Fred Drake <fdrake@acm.org> parents: 7453 diff changeset	127 The file \file{profile.py} can also be invoked as
5681 d88cb4d26f13 Mention use of profile.py to run a script (AMK). Guido van Rossum <guido@python.org> parents: 4728 diff changeset	128 a script to profile another script. For example:
7498 1906a7fc7509 Logical markup. Fred Drake <fdrake@acm.org> parents: 7453 diff changeset	129
1906a7fc7509 Logical markup. Fred Drake <fdrake@acm.org> parents: 7453 diff changeset	130 \begin{verbatim}
7822 d1b23504bd99 Index entries. Fred Drake <fdrake@acm.org> parents: 7797 diff changeset	131 python /usr/local/lib/python1.5/profile.py myscript.py
7498 1906a7fc7509 Logical markup. Fred Drake <fdrake@acm.org> parents: 7453 diff changeset	132 \end{verbatim}
5681 d88cb4d26f13 Mention use of profile.py to run a script (AMK). Guido van Rossum <guido@python.org> parents: 4728 diff changeset	133
2465 1f4141aafe36 converted docs for Jim Roskind's profiler Guido van Rossum <guido@python.org> parents: diff changeset	134 When you wish to review the profile, you should use the methods in the
7498 1906a7fc7509 Logical markup. Fred Drake <fdrake@acm.org> parents: 7453 diff changeset	135 \module{pstats} module. Typically you would load the statistics data as
2465 1f4141aafe36 converted docs for Jim Roskind's profiler Guido van Rossum <guido@python.org> parents: diff changeset	136 follows:
1f4141aafe36 converted docs for Jim Roskind's profiler Guido van Rossum <guido@python.org> parents: diff changeset	137
7277 bf4e790bd61a Remove all \bcode / \ecode cruft; this is no longer needed. See previous Fred Drake <fdrake@acm.org> parents: 6932 diff changeset	138 \begin{verbatim}
5818 3468ea8645ca AMK's megapatch: Guido van Rossum <guido@python.org> parents: 5681 diff changeset	139 import pstats
3468ea8645ca AMK's megapatch: Guido van Rossum <guido@python.org> parents: 5681 diff changeset	140 p = pstats.Stats('fooprof')
7277 bf4e790bd61a Remove all \bcode / \ecode cruft; this is no longer needed. See previous Fred Drake <fdrake@acm.org> parents: 6932 diff changeset	141 \end{verbatim}
10667 02eb74749262 Misc. markup nits. Fred Drake <fdrake@acm.org> parents: 10520 diff changeset	142
7498 1906a7fc7509 Logical markup. Fred Drake <fdrake@acm.org> parents: 7453 diff changeset	143 The class \class{Stats} (the above code just created an instance of
2465 1f4141aafe36 converted docs for Jim Roskind's profiler Guido van Rossum <guido@python.org> parents: diff changeset	144 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	145 data that was just read into \samp{p}. When you ran
7498 1906a7fc7509 Logical markup. Fred Drake <fdrake@acm.org> parents: 7453 diff changeset	146 \function{profile.run()} above, what was printed was the result of three
2465 1f4141aafe36 converted docs for Jim Roskind's profiler Guido van Rossum <guido@python.org> parents: diff changeset	147 method calls:
1f4141aafe36 converted docs for Jim Roskind's profiler Guido van Rossum <guido@python.org> parents: diff changeset	148
7277 bf4e790bd61a Remove all \bcode / \ecode cruft; this is no longer needed. See previous Fred Drake <fdrake@acm.org> parents: 6932 diff changeset	149 \begin{verbatim}
5818 3468ea8645ca AMK's megapatch: Guido van Rossum <guido@python.org> parents: 5681 diff changeset	150 p.strip_dirs().sort_stats(-1).print_stats()
7277 bf4e790bd61a Remove all \bcode / \ecode cruft; this is no longer needed. See previous Fred Drake <fdrake@acm.org> parents: 6932 diff changeset	151 \end{verbatim}
10667 02eb74749262 Misc. markup nits. Fred Drake <fdrake@acm.org> parents: 10520 diff changeset	152
2465 1f4141aafe36 converted docs for Jim Roskind's profiler Guido van Rossum <guido@python.org> parents: diff changeset	153 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	154 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	155 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	156 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	157 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	158
7277 bf4e790bd61a Remove all \bcode / \ecode cruft; this is no longer needed. See previous Fred Drake <fdrake@acm.org> parents: 6932 diff changeset	159 \begin{verbatim}
5818 3468ea8645ca AMK's megapatch: Guido van Rossum <guido@python.org> parents: 5681 diff changeset	160 p.sort_stats('name')
3468ea8645ca AMK's megapatch: Guido van Rossum <guido@python.org> parents: 5681 diff changeset	161 p.print_stats()
7277 bf4e790bd61a Remove all \bcode / \ecode cruft; this is no longer needed. See previous Fred Drake <fdrake@acm.org> parents: 6932 diff changeset	162 \end{verbatim}
10667 02eb74749262 Misc. markup nits. Fred Drake <fdrake@acm.org> parents: 10520 diff changeset	163
2465 1f4141aafe36 converted docs for Jim Roskind's profiler Guido van Rossum <guido@python.org> parents: diff changeset	164 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	165 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	166 interesting calls to experiment with:
1f4141aafe36 converted docs for Jim Roskind's profiler Guido van Rossum <guido@python.org> parents: diff changeset	167
7277 bf4e790bd61a Remove all \bcode / \ecode cruft; this is no longer needed. See previous Fred Drake <fdrake@acm.org> parents: 6932 diff changeset	168 \begin{verbatim}
5818 3468ea8645ca AMK's megapatch: Guido van Rossum <guido@python.org> parents: 5681 diff changeset	169 p.sort_stats('cumulative').print_stats(10)
7277 bf4e790bd61a Remove all \bcode / \ecode cruft; this is no longer needed. See previous Fred Drake <fdrake@acm.org> parents: 6932 diff changeset	170 \end{verbatim}
10667 02eb74749262 Misc. markup nits. Fred Drake <fdrake@acm.org> parents: 10520 diff changeset	171
2465 1f4141aafe36 converted docs for Jim Roskind's profiler Guido van Rossum <guido@python.org> parents: diff changeset	172 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	173 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	174 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	175
1f4141aafe36 converted docs for Jim Roskind's profiler Guido van Rossum <guido@python.org> parents: diff changeset	176 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	177 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	178
7277 bf4e790bd61a Remove all \bcode / \ecode cruft; this is no longer needed. See previous Fred Drake <fdrake@acm.org> parents: 6932 diff changeset	179 \begin{verbatim}
5818 3468ea8645ca AMK's megapatch: Guido van Rossum <guido@python.org> parents: 5681 diff changeset	180 p.sort_stats('time').print_stats(10)
7277 bf4e790bd61a Remove all \bcode / \ecode cruft; this is no longer needed. See previous Fred Drake <fdrake@acm.org> parents: 6932 diff changeset	181 \end{verbatim}
10667 02eb74749262 Misc. markup nits. Fred Drake <fdrake@acm.org> parents: 10520 diff changeset	182
2465 1f4141aafe36 converted docs for Jim Roskind's profiler Guido van Rossum <guido@python.org> parents: diff changeset	183 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	184 the statistics for the top ten functions.
1f4141aafe36 converted docs for Jim Roskind's profiler Guido van Rossum <guido@python.org> parents: diff changeset	185
1f4141aafe36 converted docs for Jim Roskind's profiler Guido van Rossum <guido@python.org> parents: diff changeset	186 You might also try:
1f4141aafe36 converted docs for Jim Roskind's profiler Guido van Rossum <guido@python.org> parents: diff changeset	187
7277 bf4e790bd61a Remove all \bcode / \ecode cruft; this is no longer needed. See previous Fred Drake <fdrake@acm.org> parents: 6932 diff changeset	188 \begin{verbatim}
5818 3468ea8645ca AMK's megapatch: Guido van Rossum <guido@python.org> parents: 5681 diff changeset	189 p.sort_stats('file').print_stats('__init__')
7277 bf4e790bd61a Remove all \bcode / \ecode cruft; this is no longer needed. See previous Fred Drake <fdrake@acm.org> parents: 6932 diff changeset	190 \end{verbatim}
10667 02eb74749262 Misc. markup nits. Fred Drake <fdrake@acm.org> parents: 10520 diff changeset	191
2465 1f4141aafe36 converted docs for Jim Roskind's profiler Guido van Rossum <guido@python.org> parents: diff changeset	192 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	193 statistics for only the class init methods ('cause they are spelled
7498 1906a7fc7509 Logical markup. Fred Drake <fdrake@acm.org> parents: 7453 diff changeset	194 with \samp{__init__} in them). As one final example, you could try:
2465 1f4141aafe36 converted docs for Jim Roskind's profiler Guido van Rossum <guido@python.org> parents: diff changeset	195
7277 bf4e790bd61a Remove all \bcode / \ecode cruft; this is no longer needed. See previous Fred Drake <fdrake@acm.org> parents: 6932 diff changeset	196 \begin{verbatim}
5818 3468ea8645ca AMK's megapatch: Guido van Rossum <guido@python.org> parents: 5681 diff changeset	197 p.sort_stats('time', 'cum').print_stats(.5, 'init')
7277 bf4e790bd61a Remove all \bcode / \ecode cruft; this is no longer needed. See previous Fred Drake <fdrake@acm.org> parents: 6932 diff changeset	198 \end{verbatim}
10667 02eb74749262 Misc. markup nits. Fred Drake <fdrake@acm.org> parents: 10520 diff changeset	199
2465 1f4141aafe36 converted docs for Jim Roskind's profiler Guido van Rossum <guido@python.org> parents: diff changeset	200 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	201 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	202 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	203 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	204 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	205
1f4141aafe36 converted docs for Jim Roskind's profiler Guido van Rossum <guido@python.org> parents: diff changeset	206 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	207 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	208
7277 bf4e790bd61a Remove all \bcode / \ecode cruft; this is no longer needed. See previous Fred Drake <fdrake@acm.org> parents: 6932 diff changeset	209 \begin{verbatim}
5818 3468ea8645ca AMK's megapatch: Guido van Rossum <guido@python.org> parents: 5681 diff changeset	210 p.print_callers(.5, 'init')
7277 bf4e790bd61a Remove all \bcode / \ecode cruft; this is no longer needed. See previous Fred Drake <fdrake@acm.org> parents: 6932 diff changeset	211 \end{verbatim}
7498 1906a7fc7509 Logical markup. Fred Drake <fdrake@acm.org> parents: 7453 diff changeset	212
20295 5d2d1e2ec473 Remove code and docs for the OldProfile and HotProfile classes: code Tim Peters <tim.peters@gmail.com> parents: 18416 diff changeset	213 and you would get a list of callers for each of the listed functions.
2465 1f4141aafe36 converted docs for Jim Roskind's profiler Guido van Rossum <guido@python.org> parents: diff changeset	214
1f4141aafe36 converted docs for Jim Roskind's profiler Guido van Rossum <guido@python.org> parents: diff changeset	215 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	216 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	217
7277 bf4e790bd61a Remove all \bcode / \ecode cruft; this is no longer needed. See previous Fred Drake <fdrake@acm.org> parents: 6932 diff changeset	218 \begin{verbatim}
5818 3468ea8645ca AMK's megapatch: Guido van Rossum <guido@python.org> parents: 5681 diff changeset	219 p.print_callees()
3468ea8645ca AMK's megapatch: Guido van Rossum <guido@python.org> parents: 5681 diff changeset	220 p.add('fooprof')
7277 bf4e790bd61a Remove all \bcode / \ecode cruft; this is no longer needed. See previous Fred Drake <fdrake@acm.org> parents: 6932 diff changeset	221 \end{verbatim}
10667 02eb74749262 Misc. markup nits. Fred Drake <fdrake@acm.org> parents: 10520 diff changeset	222
17462 e8741dc36ad1 Added a test main to the pstats library that can help you browse profile dumps. Eric S. Raymond <esr@thyrsus.com> parents: 10703 diff changeset	223 Invoked as a script, the \module{pstats} module is a statistics
e8741dc36ad1 Added a test main to the pstats library that can help you browse profile dumps. Eric S. Raymond <esr@thyrsus.com> parents: 10703 diff changeset	224 browser for reading and examining profile dumps. It has a simple
17478 613dcd5476b6 Minor markup adjustments. Fred Drake <fdrake@acm.org> parents: 17462 diff changeset	225 line-oriented interface (implemented using \refmodule{cmd}) and
17462 e8741dc36ad1 Added a test main to the pstats library that can help you browse profile dumps. Eric S. Raymond <esr@thyrsus.com> parents: 10703 diff changeset	226 interactive help.
e8741dc36ad1 Added a test main to the pstats library that can help you browse profile dumps. Eric S. Raymond <esr@thyrsus.com> parents: 10703 diff changeset	227
2465 1f4141aafe36 converted docs for Jim Roskind's profiler Guido van Rossum <guido@python.org> parents: diff changeset	228 \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	229 \nodename{Deterministic Profiling}
2465 1f4141aafe36 converted docs for Jim Roskind's profiler Guido van Rossum <guido@python.org> parents: diff changeset	230
1f4141aafe36 converted docs for Jim Roskind's profiler Guido van Rossum <guido@python.org> parents: diff changeset	231 \dfn{Deterministic profiling} is meant to reflect the fact that all
17478 613dcd5476b6 Minor markup adjustments. Fred Drake <fdrake@acm.org> parents: 17462 diff changeset	232 \emph{function call}, \emph{function return}, and \emph{exception} events
2465 1f4141aafe36 converted docs for Jim Roskind's profiler Guido van Rossum <guido@python.org> parents: diff changeset	233 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	234 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	235 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	236 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	237 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	238 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	239 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	240
1f4141aafe36 converted docs for Jim Roskind's profiler Guido van Rossum <guido@python.org> parents: diff changeset	241 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	242 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	243 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	244 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	245 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	246 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	247 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	248 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	249 execution of a Python program.
1f4141aafe36 converted docs for Jim Roskind's profiler Guido van Rossum <guido@python.org> parents: diff changeset	250
1f4141aafe36 converted docs for Jim Roskind's profiler Guido van Rossum <guido@python.org> parents: diff changeset	251 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	252 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	253 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	254 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	255 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	256 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	257 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	258 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	259
1f4141aafe36 converted docs for Jim Roskind's profiler Guido van Rossum <guido@python.org> parents: diff changeset	260
1f4141aafe36 converted docs for Jim Roskind's profiler Guido van Rossum <guido@python.org> parents: diff changeset	261 \section{Reference Manual}
10667 02eb74749262 Misc. markup nits. Fred Drake <fdrake@acm.org> parents: 10520 diff changeset	262
8716 760dcf197048 Adjusted to use the new module synopsis support macros. Fred Drake <fdrake@acm.org> parents: 8018 diff changeset	263 \declaremodule{standard}{profile}
10667 02eb74749262 Misc. markup nits. Fred Drake <fdrake@acm.org> parents: 10520 diff changeset	264 \modulesynopsis{Python profiler}
8716 760dcf197048 Adjusted to use the new module synopsis support macros. Fred Drake <fdrake@acm.org> parents: 8018 diff changeset	265
2465 1f4141aafe36 converted docs for Jim Roskind's profiler Guido van Rossum <guido@python.org> parents: diff changeset	266
1f4141aafe36 converted docs for Jim Roskind's profiler Guido van Rossum <guido@python.org> parents: diff changeset	267
1f4141aafe36 converted docs for Jim Roskind's profiler Guido van Rossum <guido@python.org> parents: diff changeset	268 The primary entry point for the profiler is the global function
7498 1906a7fc7509 Logical markup. Fred Drake <fdrake@acm.org> parents: 7453 diff changeset	269 \function{profile.run()}. It is typically used to create any profile
2465 1f4141aafe36 converted docs for Jim Roskind's profiler Guido van Rossum <guido@python.org> parents: diff changeset	270 information. The reports are formatted and printed using methods of
7498 1906a7fc7509 Logical markup. Fred Drake <fdrake@acm.org> parents: 7453 diff changeset	271 the class \class{pstats.Stats}. The following is a description of all
2465 1f4141aafe36 converted docs for Jim Roskind's profiler Guido van Rossum <guido@python.org> parents: diff changeset	272 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	273 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	274 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	275 ``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	276 code for these modules.
1f4141aafe36 converted docs for Jim Roskind's profiler Guido van Rossum <guido@python.org> parents: diff changeset	277
7768 8f177933c41f Use the new {methoddesc} and {memberdesc} environments as appropriate. Fred Drake <fdrake@acm.org> parents: 7713 diff changeset	278 \begin{funcdesc}{run}{string\optional{, filename\optional{, ...}}}
2465 1f4141aafe36 converted docs for Jim Roskind's profiler Guido van Rossum <guido@python.org> parents: diff changeset	279
1f4141aafe36 converted docs for Jim Roskind's profiler Guido van Rossum <guido@python.org> parents: diff changeset	280 This function takes a single argument that has can be passed to the
7498 1906a7fc7509 Logical markup. Fred Drake <fdrake@acm.org> parents: 7453 diff changeset	281 \keyword{exec} statement, and an optional file name. In all cases this
1906a7fc7509 Logical markup. Fred Drake <fdrake@acm.org> parents: 7453 diff changeset	282 routine attempts to \keyword{exec} its first argument, and gather profiling
2465 1f4141aafe36 converted docs for Jim Roskind's profiler Guido van Rossum <guido@python.org> parents: diff changeset	283 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	284 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	285 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	286 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	287
7277 bf4e790bd61a Remove all \bcode / \ecode cruft; this is no longer needed. See previous Fred Drake <fdrake@acm.org> parents: 6932 diff changeset	288 \begin{verbatim}
2647 9b7e6d9a528d typos, layout and other small things Guido van Rossum <guido@python.org> parents: 2596 diff changeset	289 main()
9b7e6d9a528d typos, layout and other small things Guido van Rossum <guido@python.org> parents: 2596 diff changeset	290 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	291
2647 9b7e6d9a528d typos, layout and other small things Guido van Rossum <guido@python.org> parents: 2596 diff changeset	292 Ordered by: standard name
2465 1f4141aafe36 converted docs for Jim Roskind's profiler Guido van Rossum <guido@python.org> parents: diff changeset	293
2647 9b7e6d9a528d typos, layout and other small things Guido van Rossum <guido@python.org> parents: 2596 diff changeset	294 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	295 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	296 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	297 ...
7277 bf4e790bd61a Remove all \bcode / \ecode cruft; this is no longer needed. See previous Fred Drake <fdrake@acm.org> parents: 6932 diff changeset	298 \end{verbatim}
2465 1f4141aafe36 converted docs for Jim Roskind's profiler Guido van Rossum <guido@python.org> parents: diff changeset	299
1f4141aafe36 converted docs for Jim Roskind's profiler Guido van Rossum <guido@python.org> parents: diff changeset	300 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	301 \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	302 \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	303 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	304 \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	305 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	306 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	307 The column headings include:
1f4141aafe36 converted docs for Jim Roskind's profiler Guido van Rossum <guido@python.org> parents: diff changeset	308
1f4141aafe36 converted docs for Jim Roskind's profiler Guido van Rossum <guido@python.org> parents: diff changeset	309 \begin{description}
1f4141aafe36 converted docs for Jim Roskind's profiler Guido van Rossum <guido@python.org> parents: diff changeset	310
1f4141aafe36 converted docs for Jim Roskind's profiler Guido van Rossum <guido@python.org> parents: diff changeset	311 \item[ncalls ]
20295 5d2d1e2ec473 Remove code and docs for the OldProfile and HotProfile classes: code Tim Peters <tim.peters@gmail.com> parents: 18416 diff changeset	312 for the number of calls,
2465 1f4141aafe36 converted docs for Jim Roskind's profiler Guido van Rossum <guido@python.org> parents: diff changeset	313
1f4141aafe36 converted docs for Jim Roskind's profiler Guido van Rossum <guido@python.org> parents: diff changeset	314 \item[tottime ]
1f4141aafe36 converted docs for Jim Roskind's profiler Guido van Rossum <guido@python.org> parents: diff changeset	315 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	316 made in calls to sub-functions),
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 \item[percall ]
1f4141aafe36 converted docs for Jim Roskind's profiler Guido van Rossum <guido@python.org> parents: diff changeset	319 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	320
1f4141aafe36 converted docs for Jim Roskind's profiler Guido van Rossum <guido@python.org> parents: diff changeset	321 \item[cumtime ]
18416 33b4357aebb8 Fix up a few style nits -- avoid "e.g." and "i.e." -- these make Fred Drake <fdrake@acm.org> parents: 18370 diff changeset	322 is the total time spent in this and all subfunctions (from invocation
33b4357aebb8 Fix up a few style nits -- avoid "e.g." and "i.e." -- these make Fred Drake <fdrake@acm.org> parents: 18370 diff changeset	323 till exit). This figure is accurate \emph{even} for recursive
2465 1f4141aafe36 converted docs for Jim Roskind's profiler Guido van Rossum <guido@python.org> parents: diff changeset	324 functions.
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 \item[percall ]
1f4141aafe36 converted docs for Jim Roskind's profiler Guido van Rossum <guido@python.org> parents: diff changeset	327 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	328
1f4141aafe36 converted docs for Jim Roskind's profiler Guido van Rossum <guido@python.org> parents: diff changeset	329 \item[filename:lineno(function) ]
1f4141aafe36 converted docs for Jim Roskind's profiler Guido van Rossum <guido@python.org> parents: diff changeset	330 provides the respective data of each function
1f4141aafe36 converted docs for Jim Roskind's profiler Guido van Rossum <guido@python.org> parents: diff changeset	331
1f4141aafe36 converted docs for Jim Roskind's profiler Guido van Rossum <guido@python.org> parents: diff changeset	332 \end{description}
1f4141aafe36 converted docs for Jim Roskind's profiler Guido van Rossum <guido@python.org> parents: diff changeset	333
18416 33b4357aebb8 Fix up a few style nits -- avoid "e.g." and "i.e." -- these make Fred Drake <fdrake@acm.org> parents: 18370 diff changeset	334 When there are two numbers in the first column (for example,
33b4357aebb8 Fix up a few style nits -- avoid "e.g." and "i.e." -- these make Fred Drake <fdrake@acm.org> parents: 18370 diff changeset	335 \samp{43/3}), then the latter is the number of primitive calls, and
33b4357aebb8 Fix up a few style nits -- avoid "e.g." and "i.e." -- these make Fred Drake <fdrake@acm.org> parents: 18370 diff changeset	336 the former is the actual number of calls. Note that when the function
33b4357aebb8 Fix up a few style nits -- avoid "e.g." and "i.e." -- these make Fred Drake <fdrake@acm.org> parents: 18370 diff changeset	337 does not recurse, these two values are the same, and only the single
33b4357aebb8 Fix up a few style nits -- avoid "e.g." and "i.e." -- these make Fred Drake <fdrake@acm.org> parents: 18370 diff changeset	338 figure is printed.
2647 9b7e6d9a528d typos, layout and other small things Guido van Rossum <guido@python.org> parents: 2596 diff changeset	339
2465 1f4141aafe36 converted docs for Jim Roskind's profiler Guido van Rossum <guido@python.org> parents: diff changeset	340 \end{funcdesc}
1f4141aafe36 converted docs for Jim Roskind's profiler Guido van Rossum <guido@python.org> parents: diff changeset	341
7498 1906a7fc7509 Logical markup. Fred Drake <fdrake@acm.org> parents: 7453 diff changeset	342 Analysis of the profiler data is done using this class from the
1906a7fc7509 Logical markup. Fred Drake <fdrake@acm.org> parents: 7453 diff changeset	343 \module{pstats} module:
1906a7fc7509 Logical markup. Fred Drake <fdrake@acm.org> parents: 7453 diff changeset	344
7768 8f177933c41f Use the new {methoddesc} and {memberdesc} environments as appropriate. Fred Drake <fdrake@acm.org> parents: 7713 diff changeset	345 % now switch modules....
10667 02eb74749262 Misc. markup nits. Fred Drake <fdrake@acm.org> parents: 10520 diff changeset	346 % (This \stmodindex use may be hard to change ;-( )
7768 8f177933c41f Use the new {methoddesc} and {memberdesc} environments as appropriate. Fred Drake <fdrake@acm.org> parents: 7713 diff changeset	347 \stmodindex{pstats}
7498 1906a7fc7509 Logical markup. Fred Drake <fdrake@acm.org> parents: 7453 diff changeset	348
7712 0cbc9df882b6 Change "\," to just "," in function signatures. This is easier to maintain, Fred Drake <fdrake@acm.org> parents: 7498 diff changeset	349 \begin{classdesc}{Stats}{filename\optional{, ...}}
2465 1f4141aafe36 converted docs for Jim Roskind's profiler Guido van Rossum <guido@python.org> parents: diff changeset	350 This class constructor creates an instance of a ``statistics object''
7498 1906a7fc7509 Logical markup. Fred Drake <fdrake@acm.org> parents: 7453 diff changeset	351 from a \var{filename} (or set of filenames). \class{Stats} objects are
2465 1f4141aafe36 converted docs for Jim Roskind's profiler Guido van Rossum <guido@python.org> parents: diff changeset	352 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	353
1f4141aafe36 converted docs for Jim Roskind's profiler Guido van Rossum <guido@python.org> parents: diff changeset	354 The file selected by the above constructor must have been created by
7498 1906a7fc7509 Logical markup. Fred Drake <fdrake@acm.org> parents: 7453 diff changeset	355 the corresponding version of \module{profile}. To be specific, there is
1906a7fc7509 Logical markup. Fred Drake <fdrake@acm.org> parents: 7453 diff changeset	356 \emph{no} file compatibility guaranteed with future versions of this
2465 1f4141aafe36 converted docs for Jim Roskind's profiler Guido van Rossum <guido@python.org> parents: diff changeset	357 profiler, and there is no compatibility with files produced by other
18416 33b4357aebb8 Fix up a few style nits -- avoid "e.g." and "i.e." -- these make Fred Drake <fdrake@acm.org> parents: 18370 diff changeset	358 profilers (such as the old system profiler).
2465 1f4141aafe36 converted docs for Jim Roskind's profiler Guido van Rossum <guido@python.org> parents: diff changeset	359
1f4141aafe36 converted docs for Jim Roskind's profiler Guido van Rossum <guido@python.org> parents: diff changeset	360 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	361 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	362 processes can be considered in a single report. If additional files
7498 1906a7fc7509 Logical markup. Fred Drake <fdrake@acm.org> parents: 7453 diff changeset	363 need to be combined with data in an existing \class{Stats} object, the
1906a7fc7509 Logical markup. Fred Drake <fdrake@acm.org> parents: 7453 diff changeset	364 \method{add()} method can be used.
1906a7fc7509 Logical markup. Fred Drake <fdrake@acm.org> parents: 7453 diff changeset	365 \end{classdesc}
2465 1f4141aafe36 converted docs for Jim Roskind's profiler Guido van Rossum <guido@python.org> parents: diff changeset	366
1f4141aafe36 converted docs for Jim Roskind's profiler Guido van Rossum <guido@python.org> parents: diff changeset	367
10667 02eb74749262 Misc. markup nits. Fred Drake <fdrake@acm.org> parents: 10520 diff changeset	368 \subsection{The \class{Stats} Class \label{profile-stats}}
2465 1f4141aafe36 converted docs for Jim Roskind's profiler Guido van Rossum <guido@python.org> parents: diff changeset	369
10667 02eb74749262 Misc. markup nits. Fred Drake <fdrake@acm.org> parents: 10520 diff changeset	370 \class{Stats} objects have the following methods:
2465 1f4141aafe36 converted docs for Jim Roskind's profiler Guido van Rossum <guido@python.org> parents: diff changeset	371
10667 02eb74749262 Misc. markup nits. Fred Drake <fdrake@acm.org> parents: 10520 diff changeset	372 \begin{methoddesc}[Stats]{strip_dirs}{}
7498 1906a7fc7509 Logical markup. Fred Drake <fdrake@acm.org> parents: 7453 diff changeset	373 This method for the \class{Stats} class removes all leading path
1906a7fc7509 Logical markup. Fred Drake <fdrake@acm.org> parents: 7453 diff changeset	374 information from file names. It is very useful in reducing the size
1906a7fc7509 Logical markup. Fred Drake <fdrake@acm.org> parents: 7453 diff changeset	375 of the printout to fit within (close to) 80 columns. This method
1906a7fc7509 Logical markup. Fred Drake <fdrake@acm.org> parents: 7453 diff changeset	376 modifies the object, and the stripped information is lost. After
1906a7fc7509 Logical markup. Fred Drake <fdrake@acm.org> parents: 7453 diff changeset	377 performing a strip operation, the object is considered to have its
1906a7fc7509 Logical markup. Fred Drake <fdrake@acm.org> parents: 7453 diff changeset	378 entries in a ``random'' order, as it was just after object
1906a7fc7509 Logical markup. Fred Drake <fdrake@acm.org> parents: 7453 diff changeset	379 initialization and loading. If \method{strip_dirs()} causes two
18416 33b4357aebb8 Fix up a few style nits -- avoid "e.g." and "i.e." -- these make Fred Drake <fdrake@acm.org> parents: 18370 diff changeset	380 function names to be indistinguishable (they are on the same
7498 1906a7fc7509 Logical markup. Fred Drake <fdrake@acm.org> parents: 7453 diff changeset	381 line of the same filename, and have the same function name), then the
1906a7fc7509 Logical markup. Fred Drake <fdrake@acm.org> parents: 7453 diff changeset	382 statistics for these two entries are accumulated into a single entry.
7768 8f177933c41f Use the new {methoddesc} and {memberdesc} environments as appropriate. Fred Drake <fdrake@acm.org> parents: 7713 diff changeset	383 \end{methoddesc}
2465 1f4141aafe36 converted docs for Jim Roskind's profiler Guido van Rossum <guido@python.org> parents: diff changeset	384
1f4141aafe36 converted docs for Jim Roskind's profiler Guido van Rossum <guido@python.org> parents: diff changeset	385
10667 02eb74749262 Misc. markup nits. Fred Drake <fdrake@acm.org> parents: 10520 diff changeset	386 \begin{methoddesc}[Stats]{add}{filename\optional{, ...}}
7498 1906a7fc7509 Logical markup. Fred Drake <fdrake@acm.org> parents: 7453 diff changeset	387 This method of the \class{Stats} class accumulates additional
1906a7fc7509 Logical markup. Fred Drake <fdrake@acm.org> parents: 7453 diff changeset	388 profiling information into the current profiling object. Its
1906a7fc7509 Logical markup. Fred Drake <fdrake@acm.org> parents: 7453 diff changeset	389 arguments should refer to filenames created by the corresponding
1906a7fc7509 Logical markup. Fred Drake <fdrake@acm.org> parents: 7453 diff changeset	390 version of \function{profile.run()}. Statistics for identically named
1906a7fc7509 Logical markup. Fred Drake <fdrake@acm.org> parents: 7453 diff changeset	391 (re: file, line, name) functions are automatically accumulated into
1906a7fc7509 Logical markup. Fred Drake <fdrake@acm.org> parents: 7453 diff changeset	392 single function statistics.
7768 8f177933c41f Use the new {methoddesc} and {memberdesc} environments as appropriate. Fred Drake <fdrake@acm.org> parents: 7713 diff changeset	393 \end{methoddesc}
2465 1f4141aafe36 converted docs for Jim Roskind's profiler Guido van Rossum <guido@python.org> parents: diff changeset	394
10667 02eb74749262 Misc. markup nits. Fred Drake <fdrake@acm.org> parents: 10520 diff changeset	395 \begin{methoddesc}[Stats]{sort_stats}{key\optional{, ...}}
7498 1906a7fc7509 Logical markup. Fred Drake <fdrake@acm.org> parents: 7453 diff changeset	396 This method modifies the \class{Stats} object by sorting it according
1906a7fc7509 Logical markup. Fred Drake <fdrake@acm.org> parents: 7453 diff changeset	397 to the supplied criteria. The argument is typically a string
7938 ca4e25ef61f8 Don't use \samp when \code is better. Fred Drake <fdrake@acm.org> parents: 7913 diff changeset	398 identifying the basis of a sort (example: \code{'time'} or
ca4e25ef61f8 Don't use \samp when \code is better. Fred Drake <fdrake@acm.org> parents: 7913 diff changeset	399 \code{'name'}).
2465 1f4141aafe36 converted docs for Jim Roskind's profiler Guido van Rossum <guido@python.org> parents: diff changeset	400
1f4141aafe36 converted docs for Jim Roskind's profiler Guido van Rossum <guido@python.org> parents: diff changeset	401 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	402 secondary criteria when the there is equality in all keys selected
7498 1906a7fc7509 Logical markup. Fred Drake <fdrake@acm.org> parents: 7453 diff changeset	403 before them. For example, \samp{sort_stats('name', 'file')} will sort
1906a7fc7509 Logical markup. Fred Drake <fdrake@acm.org> parents: 7453 diff changeset	404 all the entries according to their function name, and resolve all ties
2465 1f4141aafe36 converted docs for Jim Roskind's profiler Guido van Rossum <guido@python.org> parents: diff changeset	405 (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	406
1f4141aafe36 converted docs for Jim Roskind's profiler Guido van Rossum <guido@python.org> parents: diff changeset	407 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	408 abbreviation is unambiguous. The following are the keys currently
20295 5d2d1e2ec473 Remove code and docs for the OldProfile and HotProfile classes: code Tim Peters <tim.peters@gmail.com> parents: 18416 diff changeset	409 defined:
2465 1f4141aafe36 converted docs for Jim Roskind's profiler Guido van Rossum <guido@python.org> parents: diff changeset	410
8018 011ae71fea96 Lighten up tables. Fred Drake <fdrake@acm.org> parents: 7938 diff changeset	411 \begin{tableii}{l\|l}{code}{Valid Arg}{Meaning}
7822 d1b23504bd99 Index entries. Fred Drake <fdrake@acm.org> parents: 7797 diff changeset	412 \lineii{'calls'}{call count}
d1b23504bd99 Index entries. Fred Drake <fdrake@acm.org> parents: 7797 diff changeset	413 \lineii{'cumulative'}{cumulative time}
d1b23504bd99 Index entries. Fred Drake <fdrake@acm.org> parents: 7797 diff changeset	414 \lineii{'file'}{file name}
d1b23504bd99 Index entries. Fred Drake <fdrake@acm.org> parents: 7797 diff changeset	415 \lineii{'module'}{file name}
d1b23504bd99 Index entries. Fred Drake <fdrake@acm.org> parents: 7797 diff changeset	416 \lineii{'pcalls'}{primitive call count}
d1b23504bd99 Index entries. Fred Drake <fdrake@acm.org> parents: 7797 diff changeset	417 \lineii{'line'}{line number}
d1b23504bd99 Index entries. Fred Drake <fdrake@acm.org> parents: 7797 diff changeset	418 \lineii{'name'}{function name}
d1b23504bd99 Index entries. Fred Drake <fdrake@acm.org> parents: 7797 diff changeset	419 \lineii{'nfl'}{name/file/line}
d1b23504bd99 Index entries. Fred Drake <fdrake@acm.org> parents: 7797 diff changeset	420 \lineii{'stdname'}{standard name}
d1b23504bd99 Index entries. Fred Drake <fdrake@acm.org> parents: 7797 diff changeset	421 \lineii{'time'}{internal time}
2465 1f4141aafe36 converted docs for Jim Roskind's profiler Guido van Rossum <guido@python.org> parents: diff changeset	422 \end{tableii}
1f4141aafe36 converted docs for Jim Roskind's profiler Guido van Rossum <guido@python.org> parents: diff changeset	423
1f4141aafe36 converted docs for Jim Roskind's profiler Guido van Rossum <guido@python.org> parents: diff changeset	424 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	425 most time consuming items first), where as name, file, and line number
18416 33b4357aebb8 Fix up a few style nits -- avoid "e.g." and "i.e." -- these make Fred Drake <fdrake@acm.org> parents: 18370 diff changeset	426 searches are in ascending order (alphabetical). The subtle
7938 ca4e25ef61f8 Don't use \samp when \code is better. Fred Drake <fdrake@acm.org> parents: 7913 diff changeset	427 distinction between \code{'nfl'} and \code{'stdname'} is that the
2465 1f4141aafe36 converted docs for Jim Roskind's profiler Guido van Rossum <guido@python.org> parents: diff changeset	428 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	429 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	430 3, 20, and 40 would (if the file names were the same) appear in the
7938 ca4e25ef61f8 Don't use \samp when \code is better. Fred Drake <fdrake@acm.org> parents: 7913 diff changeset	431 string order 20, 3 and 40. In contrast, \code{'nfl'} does a numeric
ca4e25ef61f8 Don't use \samp when \code is better. Fred Drake <fdrake@acm.org> parents: 7913 diff changeset	432 compare of the line numbers. In fact, \code{sort_stats('nfl')} is the
ca4e25ef61f8 Don't use \samp when \code is better. Fred Drake <fdrake@acm.org> parents: 7913 diff changeset	433 same as \code{sort_stats('name', 'file', 'line')}.
2465 1f4141aafe36 converted docs for Jim Roskind's profiler Guido van Rossum <guido@python.org> parents: diff changeset	434
1f4141aafe36 converted docs for Jim Roskind's profiler Guido van Rossum <guido@python.org> parents: diff changeset	435 For compatibility with the old profiler, the numeric arguments
7938 ca4e25ef61f8 Don't use \samp when \code is better. Fred Drake <fdrake@acm.org> parents: 7913 diff changeset	436 \code{-1}, \code{0}, \code{1}, and \code{2} are permitted. They are
ca4e25ef61f8 Don't use \samp when \code is better. Fred Drake <fdrake@acm.org> parents: 7913 diff changeset	437 interpreted as \code{'stdname'}, \code{'calls'}, \code{'time'}, and
ca4e25ef61f8 Don't use \samp when \code is better. Fred Drake <fdrake@acm.org> parents: 7913 diff changeset	438 \code{'cumulative'} respectively. If this old style format (numeric)
2465 1f4141aafe36 converted docs for Jim Roskind's profiler Guido van Rossum <guido@python.org> parents: diff changeset	439 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	440 additional arguments will be silently ignored.
7768 8f177933c41f Use the new {methoddesc} and {memberdesc} environments as appropriate. Fred Drake <fdrake@acm.org> parents: 7713 diff changeset	441 \end{methoddesc}
2465 1f4141aafe36 converted docs for Jim Roskind's profiler Guido van Rossum <guido@python.org> parents: diff changeset	442
1f4141aafe36 converted docs for Jim Roskind's profiler Guido van Rossum <guido@python.org> parents: diff changeset	443
10667 02eb74749262 Misc. markup nits. Fred Drake <fdrake@acm.org> parents: 10520 diff changeset	444 \begin{methoddesc}[Stats]{reverse_order}{}
7498 1906a7fc7509 Logical markup. Fred Drake <fdrake@acm.org> parents: 7453 diff changeset	445 This method for the \class{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	446 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	447 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	448 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	449 the sort key of choice.
7768 8f177933c41f Use the new {methoddesc} and {memberdesc} environments as appropriate. Fred Drake <fdrake@acm.org> parents: 7713 diff changeset	450 \end{methoddesc}
2465 1f4141aafe36 converted docs for Jim Roskind's profiler Guido van Rossum <guido@python.org> parents: diff changeset	451
18370 c76dad06461b Marked the parameters to Stats.print_() as optional. Fred Drake <fdrake@acm.org>* parents: 18117 diff changeset	452 \begin{methoddesc}[Stats]{print_stats}{\optional{restriction, \moreargs}}
7498 1906a7fc7509 Logical markup. Fred Drake <fdrake@acm.org> parents: 7453 diff changeset	453 This method for the \class{Stats} class prints out a report as described
1906a7fc7509 Logical markup. Fred Drake <fdrake@acm.org> parents: 7453 diff changeset	454 in the \function{profile.run()} definition.
2465 1f4141aafe36 converted docs for Jim Roskind's profiler Guido van Rossum <guido@python.org> parents: diff changeset	455
7498 1906a7fc7509 Logical markup. Fred Drake <fdrake@acm.org> parents: 7453 diff changeset	456 The order of the printing is based on the last \method{sort_stats()}
1906a7fc7509 Logical markup. Fred Drake <fdrake@acm.org> parents: 7453 diff changeset	457 operation done on the object (subject to caveats in \method{add()} and
1906a7fc7509 Logical markup. Fred Drake <fdrake@acm.org> parents: 7453 diff changeset	458 \method{strip_dirs()}.
2465 1f4141aafe36 converted docs for Jim Roskind's profiler Guido van Rossum <guido@python.org> parents: diff changeset	459
1f4141aafe36 converted docs for Jim Roskind's profiler Guido van Rossum <guido@python.org> parents: diff changeset	460 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	461 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	462 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	463 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	464 0.0 and 1.0 inclusive (to select a percentage of lines), or a regular
6586 753077f9eb2c Clarified reference to old profiler. Guido van Rossum <guido@python.org> parents: 5818 diff changeset	465 expression (to pattern match the standard name that is printed; as of
753077f9eb2c Clarified reference to old profiler. Guido van Rossum <guido@python.org> parents: 5818 diff changeset	466 Python 1.5b1, this uses the Perl-style regular expression syntax
10703 e4e800a78d8d Make internal module references hyperlinks wherever it makes sense. Fred Drake <fdrake@acm.org> parents: 10667 diff changeset	467 defined by the \refmodule{re} module). If several restrictions are
6586 753077f9eb2c Clarified reference to old profiler. Guido van Rossum <guido@python.org> parents: 5818 diff changeset	468 provided, then they are applied sequentially. For example:
2465 1f4141aafe36 converted docs for Jim Roskind's profiler Guido van Rossum <guido@python.org> parents: diff changeset	469
7277 bf4e790bd61a Remove all \bcode / \ecode cruft; this is no longer needed. See previous Fred Drake <fdrake@acm.org> parents: 6932 diff changeset	470 \begin{verbatim}
7938 ca4e25ef61f8 Don't use \samp when \code is better. Fred Drake <fdrake@acm.org> parents: 7913 diff changeset	471 print_stats(.1, 'foo:')
7277 bf4e790bd61a Remove all \bcode / \ecode cruft; this is no longer needed. See previous Fred Drake <fdrake@acm.org> parents: 6932 diff changeset	472 \end{verbatim}
7498 1906a7fc7509 Logical markup. Fred Drake <fdrake@acm.org> parents: 7453 diff changeset	473
2465 1f4141aafe36 converted docs for Jim Roskind's profiler Guido van Rossum <guido@python.org> parents: diff changeset	474 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	475 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	476 contrast, the command:
1f4141aafe36 converted docs for Jim Roskind's profiler Guido van Rossum <guido@python.org> parents: diff changeset	477
7277 bf4e790bd61a Remove all \bcode / \ecode cruft; this is no longer needed. See previous Fred Drake <fdrake@acm.org> parents: 6932 diff changeset	478 \begin{verbatim}
7938 ca4e25ef61f8 Don't use \samp when \code is better. Fred Drake <fdrake@acm.org> parents: 7913 diff changeset	479 print_stats('foo:', .1)
7277 bf4e790bd61a Remove all \bcode / \ecode cruft; this is no longer needed. See previous Fred Drake <fdrake@acm.org> parents: 6932 diff changeset	480 \end{verbatim}
7498 1906a7fc7509 Logical markup. Fred Drake <fdrake@acm.org> parents: 7453 diff changeset	481
2465 1f4141aafe36 converted docs for Jim Roskind's profiler Guido van Rossum <guido@python.org> parents: diff changeset	482 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	483 and then proceed to only print the first 10\% of them.
7768 8f177933c41f Use the new {methoddesc} and {memberdesc} environments as appropriate. Fred Drake <fdrake@acm.org> parents: 7713 diff changeset	484 \end{methoddesc}
2465 1f4141aafe36 converted docs for Jim Roskind's profiler Guido van Rossum <guido@python.org> parents: diff changeset	485
1f4141aafe36 converted docs for Jim Roskind's profiler Guido van Rossum <guido@python.org> parents: diff changeset	486
18370 c76dad06461b Marked the parameters to Stats.print_() as optional. Fred Drake <fdrake@acm.org>* parents: 18117 diff changeset	487 \begin{methoddesc}[Stats]{print_callers}{\optional{restriction, \moreargs}}
7498 1906a7fc7509 Logical markup. Fred Drake <fdrake@acm.org> parents: 7453 diff changeset	488 This method for the \class{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	489 that called each function in the profiled database. The ordering is
7498 1906a7fc7509 Logical markup. Fred Drake <fdrake@acm.org> parents: 7453 diff changeset	490 identical to that provided by \method{print_stats()}, and the definition
2465 1f4141aafe36 converted docs for Jim Roskind's profiler Guido van Rossum <guido@python.org> parents: diff changeset	491 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	492 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	493 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	494 is the cumulative time spent in the function at the right.
7768 8f177933c41f Use the new {methoddesc} and {memberdesc} environments as appropriate. Fred Drake <fdrake@acm.org> parents: 7713 diff changeset	495 \end{methoddesc}
2465 1f4141aafe36 converted docs for Jim Roskind's profiler Guido van Rossum <guido@python.org> parents: diff changeset	496
18370 c76dad06461b Marked the parameters to Stats.print_() as optional. Fred Drake <fdrake@acm.org>* parents: 18117 diff changeset	497 \begin{methoddesc}[Stats]{print_callees}{\optional{restriction, \moreargs}}
7498 1906a7fc7509 Logical markup. Fred Drake <fdrake@acm.org> parents: 7453 diff changeset	498 This method for the \class{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	499 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	500 of direction of calls (re: called vs was called by), the arguments and
7498 1906a7fc7509 Logical markup. Fred Drake <fdrake@acm.org> parents: 7453 diff changeset	501 ordering are identical to the \method{print_callers()} method.
7768 8f177933c41f Use the new {methoddesc} and {memberdesc} environments as appropriate. Fred Drake <fdrake@acm.org> parents: 7713 diff changeset	502 \end{methoddesc}
2465 1f4141aafe36 converted docs for Jim Roskind's profiler Guido van Rossum <guido@python.org> parents: diff changeset	503
10667 02eb74749262 Misc. markup nits. Fred Drake <fdrake@acm.org> parents: 10520 diff changeset	504 \begin{methoddesc}[Stats]{ignore}{}
10520 7ee1e3134147 Fixed latex2html weirdness with footnotes. Fred Drake <fdrake@acm.org> parents: 8716 diff changeset	505 \deprecated{1.5.1}{This is not needed in modern versions of
7ee1e3134147 Fixed latex2html weirdness with footnotes. Fred Drake <fdrake@acm.org> parents: 8716 diff changeset	506 Python.\footnote{
7ee1e3134147 Fixed latex2html weirdness with footnotes. Fred Drake <fdrake@acm.org> parents: 8716 diff changeset	507 This was once necessary, when Python would print any unused expression
7ee1e3134147 Fixed latex2html weirdness with footnotes. Fred Drake <fdrake@acm.org> parents: 8716 diff changeset	508 result that was not \code{None}. The method is still defined for
7ee1e3134147 Fixed latex2html weirdness with footnotes. Fred Drake <fdrake@acm.org> parents: 8716 diff changeset	509 backward compatibility.}}
7768 8f177933c41f Use the new {methoddesc} and {memberdesc} environments as appropriate. Fred Drake <fdrake@acm.org> parents: 7713 diff changeset	510 \end{methoddesc}
2465 1f4141aafe36 converted docs for Jim Roskind's profiler Guido van Rossum <guido@python.org> parents: diff changeset	511
1f4141aafe36 converted docs for Jim Roskind's profiler Guido van Rossum <guido@python.org> parents: diff changeset	512
10667 02eb74749262 Misc. markup nits. Fred Drake <fdrake@acm.org> parents: 10520 diff changeset	513 \section{Limitations \label{profile-limits}}
2465 1f4141aafe36 converted docs for Jim Roskind's profiler Guido van Rossum <guido@python.org> parents: diff changeset	514
1f4141aafe36 converted docs for Jim Roskind's profiler Guido van Rossum <guido@python.org> parents: diff changeset	515 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	516 that it relies on the Python interpreter to dispatch \dfn{call},
7498 1906a7fc7509 Logical markup. Fred Drake <fdrake@acm.org> parents: 7453 diff changeset	517 \dfn{return}, and \dfn{exception} events. Compiled \C{} code does not
2465 1f4141aafe36 converted docs for Jim Roskind's profiler Guido van Rossum <guido@python.org> parents: diff changeset	518 get interpreted, and hence is ``invisible'' to the profiler. All time
7797 068a7762e286 Hyphenate "built-in" for consistency. Fred Drake <fdrake@acm.org> parents: 7768 diff changeset	519 spent in \C{} code (including built-in functions) will be charged to the
7498 1906a7fc7509 Logical markup. Fred Drake <fdrake@acm.org> parents: 7453 diff changeset	520 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	521 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	522 properly.
1f4141aafe36 converted docs for Jim Roskind's profiler Guido van Rossum <guido@python.org> parents: diff changeset	523
1f4141aafe36 converted docs for Jim Roskind's profiler Guido van Rossum <guido@python.org> parents: diff changeset	524 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	525 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	526 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	527 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	528 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	529 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	530 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	531 of error...
1f4141aafe36 converted docs for Jim Roskind's profiler Guido van Rossum <guido@python.org> parents: diff changeset	532
1f4141aafe36 converted docs for Jim Roskind's profiler Guido van Rossum <guido@python.org> parents: diff changeset	533 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	534 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	535 \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	536 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	537 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	538 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	539 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	540 The error that accumulates in this fashion is typically less than the
18416 33b4357aebb8 Fix up a few style nits -- avoid "e.g." and "i.e." -- these make Fred Drake <fdrake@acm.org> parents: 18370 diff changeset	541 accuracy of the clock (less than one clock tick), but it
2465 1f4141aafe36 converted docs for Jim Roskind's profiler Guido van Rossum <guido@python.org> parents: diff changeset	542 \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	543 provides a means of calibrating itself for a given platform so that
18416 33b4357aebb8 Fix up a few style nits -- avoid "e.g." and "i.e." -- these make Fred Drake <fdrake@acm.org> parents: 18370 diff changeset	544 this error can be probabilistically (on the average) removed.
2465 1f4141aafe36 converted docs for Jim Roskind's profiler Guido van Rossum <guido@python.org> parents: diff changeset	545 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	546 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	547 call counts are exceptionally low, and the gods of probability work
10667 02eb74749262 Misc. markup nits. Fred Drake <fdrake@acm.org> parents: 10520 diff changeset	548 against you :-). ) Do \emph{not} be alarmed by negative numbers in
2465 1f4141aafe36 converted docs for Jim Roskind's profiler Guido van Rossum <guido@python.org> parents: diff changeset	549 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	550 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	551 calibration.
1f4141aafe36 converted docs for Jim Roskind's profiler Guido van Rossum <guido@python.org> parents: diff changeset	552
1f4141aafe36 converted docs for Jim Roskind's profiler Guido van Rossum <guido@python.org> parents: diff changeset	553
10667 02eb74749262 Misc. markup nits. Fred Drake <fdrake@acm.org> parents: 10520 diff changeset	554 \section{Calibration \label{profile-calibration}}
2465 1f4141aafe36 converted docs for Jim Roskind's profiler Guido van Rossum <guido@python.org> parents: diff changeset	555
20347 b79ffd3fca28 Allow the profiler's calibration constant to be specified in the constructor Tim Peters <tim.peters@gmail.com> parents: 20295 diff changeset	556 The profiler subtracts a constant from each
2465 1f4141aafe36 converted docs for Jim Roskind's profiler Guido van Rossum <guido@python.org> parents: diff changeset	557 event handling time to compensate for the overhead of calling the time
20347 b79ffd3fca28 Allow the profiler's calibration constant to be specified in the constructor Tim Peters <tim.peters@gmail.com> parents: 20295 diff changeset	558 function, and socking away the results. By default, the constant is 0.
b79ffd3fca28 Allow the profiler's calibration constant to be specified in the constructor Tim Peters <tim.peters@gmail.com> parents: 20295 diff changeset	559 The following procedure can
b79ffd3fca28 Allow the profiler's calibration constant to be specified in the constructor Tim Peters <tim.peters@gmail.com> parents: 20295 diff changeset	560 be used to obtain a better constant for a given platform (see discussion
2465 1f4141aafe36 converted docs for Jim Roskind's profiler Guido van Rossum <guido@python.org> parents: diff changeset	561 in section Limitations above).
1f4141aafe36 converted docs for Jim Roskind's profiler Guido van Rossum <guido@python.org> parents: diff changeset	562
7277 bf4e790bd61a Remove all \bcode / \ecode cruft; this is no longer needed. See previous Fred Drake <fdrake@acm.org> parents: 6932 diff changeset	563 \begin{verbatim}
5818 3468ea8645ca AMK's megapatch: Guido van Rossum <guido@python.org> parents: 5681 diff changeset	564 import profile
3468ea8645ca AMK's megapatch: Guido van Rossum <guido@python.org> parents: 5681 diff changeset	565 pr = profile.Profile()
20347 b79ffd3fca28 Allow the profiler's calibration constant to be specified in the constructor Tim Peters <tim.peters@gmail.com> parents: 20295 diff changeset	566 for i in range(5):
b79ffd3fca28 Allow the profiler's calibration constant to be specified in the constructor Tim Peters <tim.peters@gmail.com> parents: 20295 diff changeset	567 print pr.calibrate(10000)
7277 bf4e790bd61a Remove all \bcode / \ecode cruft; this is no longer needed. See previous Fred Drake <fdrake@acm.org> parents: 6932 diff changeset	568 \end{verbatim}
7498 1906a7fc7509 Logical markup. Fred Drake <fdrake@acm.org> parents: 7453 diff changeset	569
20347 b79ffd3fca28 Allow the profiler's calibration constant to be specified in the constructor Tim Peters <tim.peters@gmail.com> parents: 20295 diff changeset	570 The method executes the number of Python calls given by the argument,
b79ffd3fca28 Allow the profiler's calibration constant to be specified in the constructor Tim Peters <tim.peters@gmail.com> parents: 20295 diff changeset	571 directly and again under the profiler, measuring the time for both.
b79ffd3fca28 Allow the profiler's calibration constant to be specified in the constructor Tim Peters <tim.peters@gmail.com> parents: 20295 diff changeset	572 It then computes the hidden overhead per profiler event, and returns
b79ffd3fca28 Allow the profiler's calibration constant to be specified in the constructor Tim Peters <tim.peters@gmail.com> parents: 20295 diff changeset	573 that as a float. For example, on an 800 MHz Pentium running
b79ffd3fca28 Allow the profiler's calibration constant to be specified in the constructor Tim Peters <tim.peters@gmail.com> parents: 20295 diff changeset	574 Windows 2000, and using Python's time.clock() as the timer,
b79ffd3fca28 Allow the profiler's calibration constant to be specified in the constructor Tim Peters <tim.peters@gmail.com> parents: 20295 diff changeset	575 the magical number is about 12.5e-6.
7498 1906a7fc7509 Logical markup. Fred Drake <fdrake@acm.org> parents: 7453 diff changeset	576
2465 1f4141aafe36 converted docs for Jim Roskind's profiler Guido van Rossum <guido@python.org> parents: diff changeset	577 The object of this exercise is to get a fairly consistent result.
20347 b79ffd3fca28 Allow the profiler's calibration constant to be specified in the constructor Tim Peters <tim.peters@gmail.com> parents: 20295 diff changeset	578 If your computer is \emph{very} fast, or your timer function has poor
b79ffd3fca28 Allow the profiler's calibration constant to be specified in the constructor Tim Peters <tim.peters@gmail.com> parents: 20295 diff changeset	579 resolution, you might have to pass 100000, or even 1000000, to get
b79ffd3fca28 Allow the profiler's calibration constant to be specified in the constructor Tim Peters <tim.peters@gmail.com> parents: 20295 diff changeset	580 consistent results.
2465 1f4141aafe36 converted docs for Jim Roskind's profiler Guido van Rossum <guido@python.org> parents: diff changeset	581
20347 b79ffd3fca28 Allow the profiler's calibration constant to be specified in the constructor Tim Peters <tim.peters@gmail.com> parents: 20295 diff changeset	582 When you have a consistent answer,
b79ffd3fca28 Allow the profiler's calibration constant to be specified in the constructor Tim Peters <tim.peters@gmail.com> parents: 20295 diff changeset	583 there are three ways you can use it:\footnote{Prior to Python 2.2, it
b79ffd3fca28 Allow the profiler's calibration constant to be specified in the constructor Tim Peters <tim.peters@gmail.com> parents: 20295 diff changeset	584 was necessary to edit the profiler source code to embed the bias as
b79ffd3fca28 Allow the profiler's calibration constant to be specified in the constructor Tim Peters <tim.peters@gmail.com> parents: 20295 diff changeset	585 a literal number. You still can, but that method is no longer
b79ffd3fca28 Allow the profiler's calibration constant to be specified in the constructor Tim Peters <tim.peters@gmail.com> parents: 20295 diff changeset	586 described, because no longer needed.}
2465 1f4141aafe36 converted docs for Jim Roskind's profiler Guido van Rossum <guido@python.org> parents: diff changeset	587
7277 bf4e790bd61a Remove all \bcode / \ecode cruft; this is no longer needed. See previous Fred Drake <fdrake@acm.org> parents: 6932 diff changeset	588 \begin{verbatim}
20347 b79ffd3fca28 Allow the profiler's calibration constant to be specified in the constructor Tim Peters <tim.peters@gmail.com> parents: 20295 diff changeset	589 import profile
b79ffd3fca28 Allow the profiler's calibration constant to be specified in the constructor Tim Peters <tim.peters@gmail.com> parents: 20295 diff changeset	590
b79ffd3fca28 Allow the profiler's calibration constant to be specified in the constructor Tim Peters <tim.peters@gmail.com> parents: 20295 diff changeset	591 # 1. Apply computed bias to all Profile instances created hereafter.
20349 33dac6181be5 A copy-and-paste job forget the "paste" half. Tim Peters <tim.peters@gmail.com> parents: 20347 diff changeset	592 profile.Profile.bias = your_computed_bias
2465 1f4141aafe36 converted docs for Jim Roskind's profiler Guido van Rossum <guido@python.org> parents: diff changeset	593
20347 b79ffd3fca28 Allow the profiler's calibration constant to be specified in the constructor Tim Peters <tim.peters@gmail.com> parents: 20295 diff changeset	594 # 2. Apply computed bias to a specific Profile instance.
b79ffd3fca28 Allow the profiler's calibration constant to be specified in the constructor Tim Peters <tim.peters@gmail.com> parents: 20295 diff changeset	595 pr = profile.Profile()
b79ffd3fca28 Allow the profiler's calibration constant to be specified in the constructor Tim Peters <tim.peters@gmail.com> parents: 20295 diff changeset	596 pr.bias = your_computed_bias
b79ffd3fca28 Allow the profiler's calibration constant to be specified in the constructor Tim Peters <tim.peters@gmail.com> parents: 20295 diff changeset	597
b79ffd3fca28 Allow the profiler's calibration constant to be specified in the constructor Tim Peters <tim.peters@gmail.com> parents: 20295 diff changeset	598 # 3. Specify computed bias in instance constructor.
b79ffd3fca28 Allow the profiler's calibration constant to be specified in the constructor Tim Peters <tim.peters@gmail.com> parents: 20295 diff changeset	599 pr = profile.Profile(bias=your_computed_bias)
7277 bf4e790bd61a Remove all \bcode / \ecode cruft; this is no longer needed. See previous Fred Drake <fdrake@acm.org> parents: 6932 diff changeset	600 \end{verbatim}
7498 1906a7fc7509 Logical markup. Fred Drake <fdrake@acm.org> parents: 7453 diff changeset	601
20347 b79ffd3fca28 Allow the profiler's calibration constant to be specified in the constructor Tim Peters <tim.peters@gmail.com> parents: 20295 diff changeset	602 If you have a choice, you are better off choosing a smaller constant, and
b79ffd3fca28 Allow the profiler's calibration constant to be specified in the constructor Tim Peters <tim.peters@gmail.com> parents: 20295 diff changeset	603 then your results will ``less often'' show up as negative in profile
b79ffd3fca28 Allow the profiler's calibration constant to be specified in the constructor Tim Peters <tim.peters@gmail.com> parents: 20295 diff changeset	604 statistics.
2465 1f4141aafe36 converted docs for Jim Roskind's profiler Guido van Rossum <guido@python.org> parents: diff changeset	605
1f4141aafe36 converted docs for Jim Roskind's profiler Guido van Rossum <guido@python.org> parents: diff changeset	606
2581 4d28b655b728 added nodename macro calls for new very long section names Guido van Rossum <guido@python.org> parents: 2576 diff changeset	607 \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	608 \nodename{Profiler Extensions}
2465 1f4141aafe36 converted docs for Jim Roskind's profiler Guido van Rossum <guido@python.org> parents: diff changeset	609
7498 1906a7fc7509 Logical markup. Fred Drake <fdrake@acm.org> parents: 7453 diff changeset	610 The \class{Profile} class of module \module{profile} was written so that
20295 5d2d1e2ec473 Remove code and docs for the OldProfile and HotProfile classes: code Tim Peters <tim.peters@gmail.com> parents: 18416 diff changeset	611 derived classes could be developed to extend the profiler. The details
5d2d1e2ec473 Remove code and docs for the OldProfile and HotProfile classes: code Tim Peters <tim.peters@gmail.com> parents: 18416 diff changeset	612 are not described here, as doing this successfully requires an expert
5d2d1e2ec473 Remove code and docs for the OldProfile and HotProfile classes: code Tim Peters <tim.peters@gmail.com> parents: 18416 diff changeset	613 understanding of how the \class{Profile} class works internally. Study
5d2d1e2ec473 Remove code and docs for the OldProfile and HotProfile classes: code Tim Peters <tim.peters@gmail.com> parents: 18416 diff changeset	614 the source code of module \module{profile} carefully if you want to
5d2d1e2ec473 Remove code and docs for the OldProfile and HotProfile classes: code Tim Peters <tim.peters@gmail.com> parents: 18416 diff changeset	615 pursue this.
2465 1f4141aafe36 converted docs for Jim Roskind's profiler Guido van Rossum <guido@python.org> parents: diff changeset	616
20295 5d2d1e2ec473 Remove code and docs for the OldProfile and HotProfile classes: code Tim Peters <tim.peters@gmail.com> parents: 18416 diff changeset	617 If all you want to do is change how current time is determined (for
5d2d1e2ec473 Remove code and docs for the OldProfile and HotProfile classes: code Tim Peters <tim.peters@gmail.com> parents: 18416 diff changeset	618 example, to force use of wall-clock time or elapsed process time),
5d2d1e2ec473 Remove code and docs for the OldProfile and HotProfile classes: code Tim Peters <tim.peters@gmail.com> parents: 18416 diff changeset	619 pass the timing function you want to the \class{Profile} class
5d2d1e2ec473 Remove code and docs for the OldProfile and HotProfile classes: code Tim Peters <tim.peters@gmail.com> parents: 18416 diff changeset	620 constructor:
2465 1f4141aafe36 converted docs for Jim Roskind's profiler Guido van Rossum <guido@python.org> parents: diff changeset	621
7277 bf4e790bd61a Remove all \bcode / \ecode cruft; this is no longer needed. See previous Fred Drake <fdrake@acm.org> parents: 6932 diff changeset	622 \begin{verbatim}
5818 3468ea8645ca AMK's megapatch: Guido van Rossum <guido@python.org> parents: 5681 diff changeset	623 pr = profile.Profile(your_time_func)
7277 bf4e790bd61a Remove all \bcode / \ecode cruft; this is no longer needed. See previous Fred Drake <fdrake@acm.org> parents: 6932 diff changeset	624 \end{verbatim}
7498 1906a7fc7509 Logical markup. Fred Drake <fdrake@acm.org> parents: 7453 diff changeset	625
20295 5d2d1e2ec473 Remove code and docs for the OldProfile and HotProfile classes: code Tim Peters <tim.peters@gmail.com> parents: 18416 diff changeset	626 The resulting profiler will then call \code{your_time_func()}.
5d2d1e2ec473 Remove code and docs for the OldProfile and HotProfile classes: code Tim Peters <tim.peters@gmail.com> parents: 18416 diff changeset	627 The function should return a single number, or a list of
5d2d1e2ec473 Remove code and docs for the OldProfile and HotProfile classes: code Tim Peters <tim.peters@gmail.com> parents: 18416 diff changeset	628 numbers whose sum is the current time (like what \function{os.times()}
5d2d1e2ec473 Remove code and docs for the OldProfile and HotProfile classes: code Tim Peters <tim.peters@gmail.com> parents: 18416 diff changeset	629 returns). If the function returns a single time number, or the list of
5d2d1e2ec473 Remove code and docs for the OldProfile and HotProfile classes: code Tim Peters <tim.peters@gmail.com> parents: 18416 diff changeset	630 returned numbers has length 2, then you will get an especially fast
5d2d1e2ec473 Remove code and docs for the OldProfile and HotProfile classes: code Tim Peters <tim.peters@gmail.com> parents: 18416 diff changeset	631 version of the dispatch routine.
2465 1f4141aafe36 converted docs for Jim Roskind's profiler Guido van Rossum <guido@python.org> parents: diff changeset	632
20295 5d2d1e2ec473 Remove code and docs for the OldProfile and HotProfile classes: code Tim Peters <tim.peters@gmail.com> parents: 18416 diff changeset	633 Be warned that you should calibrate the profiler class for the
2465 1f4141aafe36 converted docs for Jim Roskind's profiler Guido van Rossum <guido@python.org> parents: diff changeset	634 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	635 returns a lone integer value will provide the best results in terms of
7498 1906a7fc7509 Logical markup. Fred Drake <fdrake@acm.org> parents: 7453 diff changeset	636 low overhead during profiling. (\function{os.times()} is
20295 5d2d1e2ec473 Remove code and docs for the OldProfile and HotProfile classes: code Tim Peters <tim.peters@gmail.com> parents: 18416 diff changeset	637 \emph{pretty} bad, as it returns a tuple of floating point values). If
5d2d1e2ec473 Remove code and docs for the OldProfile and HotProfile classes: code Tim Peters <tim.peters@gmail.com> parents: 18416 diff changeset	638 you want to substitute a better timer in the cleanest fashion,
5d2d1e2ec473 Remove code and docs for the OldProfile and HotProfile classes: code Tim Peters <tim.peters@gmail.com> parents: 18416 diff changeset	639 derive a class and hardwire a replacement dispatch method that best
7498 1906a7fc7509 Logical markup. Fred Drake <fdrake@acm.org> parents: 7453 diff changeset	640 handles your timer call, along with the appropriate calibration
18058 d93b49298afd In the section on extending the profiler, add some additional discussion Fred Drake <fdrake@acm.org> parents: 17478 diff changeset	641 constant.

Mercurial > cpython-lru_cache-weakref

annotate Doc/lib/libprofile.tex @ 21467:4e35fa5d5708 legacy-trunk