cpython-lru_cache-weakref: Lib/profile.doc annotate

annotate Lib/profile.doc @ 25838:8540887bcec6 2.2

Backport of 2.183: Fix memory leak in add_subclass() found by NealN with valgrind.

author	Guido van Rossum <guido@python.org>
date	Fri, 18 Oct 2002 13:42:21 +0000
parents	1940892d2fe3
children	6f15e73b59f2

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

Mercurial > cpython-lru_cache-weakref

annotate Lib/profile.doc @ 25838:8540887bcec6 2.2