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.6?
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::new-disabled
28 ::profiler::new-enabled
30 ::profiler::sortFunctions key
32______________________________________________________________________________
34
36 The profiler package provides a simple Tcl source code profiler. It is
37 a function-level profiler; that is, it collects only function-level in‐
38 formation, not the more detailed line-level information. It operates
39 by redefining the Tcl proc command. Profiling is initiated via the
40 ::profiler::init command.
41
43 ::profiler::init
44 Initiate profiling. All procedures created after this command
45 is called will be profiled. To profile an entire application,
46 this command must be called before any other commands.
47 ::profiler::dump pattern
49 Dump profiling information for the all functions matching pat‐
50 tern. If no pattern is specified, information for all functions
51 will be returned. The result is a list of key/value pairs that
52 maps function names to information about that function. The in‐
53 formation about each function is in turn a list of key/value
54 pairs. The keys used and their values are:
55 totalCalls
57 The total number of times functionName was called.
58 callerDist
60 A list of key/value pairs mapping each calling function
61 that called functionName to the number of times it called
62 functionName.
63 compileTime
65 The runtime, in clock clicks, of functionName the first
66 time that it was called.
67 totalRuntime
69 The sum of the runtimes of all calls of functionName.
70 averageRuntime
72 Average runtime of functionName.
73 descendantTime
75 Sum of the time spent in descendants of functionName.
76 averageDescendantTime
78 Average time spent in descendants of functionName.
79 ::profiler::print ?pattern?
81 Print profiling information for all functions matching pattern.
82 If no pattern is specified, information about all functions will
83 be displayed. The return result is a human readable display of
84 the profiling information.
85 ::profiler::reset ?pattern?
87 Reset profiling information for all functions matching pattern.
88 If no pattern is specified, information will be reset for all
89 functions.
90 ::profiler::suspend ?pattern?
92 Suspend profiling for all functions matching pattern. If no
93 pattern is specified, profiling will be suspended for all func‐
94 tions. It stops gathering profiling information after this com‐
95 mand is issued. However, it does not erase any profiling infor‐
96 mation that has been gathered previously. Use resume command to
97 re-enable profiling.
98 ::profiler::resume ?pattern?
100 Resume profiling for all functions matching pattern. If no pat‐
101 tern is specified, profiling will be resumed for all functions.
102 This command should be invoked after suspending the profiler in
103 the code.
104 ::profiler::new-disabled
106 Change the initial profiling state for new procedures. Invoking
107 this command disables profiling for all procedures created after
108 this command until new-enabled is invoked. Activate profiling of
109 specific procedures via resume.
110 ::profiler::new-enabled
112 Change the initial profiling state for new procedures. Invoking
113 this command enables profiling for all procedures created after
114 this command until new-disabled is invoked. Prevent profiling of
115 specific procedures via suspend.
116 ::profiler::sortFunctions key
118 Return a list of functions sorted by a particular profiling
119 statistic. Supported values for key are: calls, exclusiveTime,
120 compileTime, nonCompileTime, totalRuntime, avgExclusiveTime, and
121 avgRuntime. The return result is a list of lists, where each
122 sublist consists of a function name and the value of key for
123 that function.
124
126 This document, and the package it describes, will undoubtedly contain
127 bugs and other problems. Please report such in the category profiler
128 of the Tcllib Trackers [http://core.tcl.tk/tcllib/reportlist]. Please
129 also report any ideas for enhancements you may have for either package
130 and/or documentation.
131 When proposing code changes, please provide unified diffs, i.e the out‐
133 put of diff -u.
134 Note further that attachments are strongly preferred over inlined
136 patches. Attachments can be made by going to the Edit form of the
137 ticket immediately after its creation, and then using the left-most
138 button in the secondary navigation bar.
139
141 performance, profile, speed
142
144 Programming tools
145tcllib 0.6 profiler(n)