1profiler(n) Tcl Profiler profiler(n)
2______________________________________________________________________________
6
8 profiler - Tcl source code profiler
9
11 package require Tcl 8.3
12 package require profiler ?0.3?
14 ::profiler::init
16 ::profiler::dump pattern
18 ::profiler::print ?pattern?
20 ::profiler::reset ?pattern?
22 ::profiler::suspend ?pattern?
24 ::profiler::resume ?pattern?
26 ::profiler::sortFunctions key
28______________________________________________________________________________
30
32 The profiler package provides a simple Tcl source code profiler. It is
33 a function-level profiler; that is, it collects only function-level
34 information, not the more detailed line-level information. It operates
35 by redefining the Tcl proc command. Profiling is initiated via the
36 ::profiler::init command.
37
39 ::profiler::init
40 Initiate profiling. All procedures created after this command
41 is called will be profiled. To profile an entire application,
42 this command must be called before any other commands.
43 ::profiler::dump pattern
45 Dump profiling information for the all functions matching pat‐
46 tern. If no pattern is specified, information for all functions
47 will be returned. The result is a list of key/value pairs that
48 maps function names to information about that function. The
49 information about each function is in turn a list of key/value
50 pairs. The keys used and their values are:
51 totalCalls
53 The total number of times functionName was called.
54 callerDist
56 A list of key/value pairs mapping each calling function
57 that called functionName to the number of times it called
58 functionName.
59 compileTime
61 The runtime, in clock clicks, of functionName the first
62 time that it was called.
63 totalRuntime
65 The sum of the runtimes of all calls of functionName.
66 averageRuntime
68 Average runtime of functionName.
69 descendantTime
71 Sum of the time spent in descendants of functionName.
72 averageDescendantTime
74 Average time spent in descendants of functionName.
75 ::profiler::print ?pattern?
77 Print profiling information for all functions matching pattern.
78 If no pattern is specified, information about all functions will
79 be displayed. The return result is a human readable display of
80 the profiling information.
81 ::profiler::reset ?pattern?
83 Reset profiling information for all functions matching pattern.
84 If no pattern is specified, information will be reset for all
85 functions.
86 ::profiler::suspend ?pattern?
88 Suspend profiling for all functions matching pattern. If no
89 pattern is specified, profiling will be suspended for all func‐
90 tions. It stops gathering profiling information after this com‐
91 mand is issued. However, it does not erase any profiling infor‐
92 mation that has been gathered previously. Use resume command to
93 re-enable profiling.
94 ::profiler::resume ?pattern?
96 Resume profiling for all functions matching pattern. If no pat‐
97 tern is specified, profiling will be resumed for all functions.
98 This command should be invoked after suspending the profiler in
99 the code.
100 ::profiler::sortFunctions key
102 Return a list of functions sorted by a particular profiling
103 statistic. Supported values for key are: calls, exclusiveTime,
104 compileTime, nonCompileTime, totalRuntime, avgExclusiveTime, and
105 avgRuntime. The return result is a list of lists, where each
106 sublist consists of a function name and the value of key for
107 that function.
108
110 This document, and the package it describes, will undoubtedly contain
111 bugs and other problems. Please report such in the category profiler
112 of the Tcllib Trackers [http://core.tcl.tk/tcllib/reportlist]. Please
113 also report any ideas for enhancements you may have for either package
114 and/or documentation.
115 When proposing code changes, please provide unified diffs, i.e the out‐
117 put of diff -u.
118 Note further that attachments are strongly preferred over inlined
120 patches. Attachments can be made by going to the Edit form of the
121 ticket immediately after its creation, and then using the left-most
122 button in the secondary navigation bar.
123
125 performance, profile, speed
126
128 Programming tools
129tcllib 0.3 profiler(n)