1[comment {-*- tcl -*- doctools manpage}]
2[manpage_begin profiler n 0.3]
3[moddesc   {Tcl Profiler}]
4[titledesc {Tcl source code profiler}]
5[category  {Programming tools}]
6[require Tcl 8.3]
7[require profiler [opt 0.3]]
8[description]
9[para]
10
11The [package profiler] package provides a simple Tcl source code
12profiler.  It is a function-level profiler; that is, it collects only
13function-level information, not the more detailed line-level
14information.  It operates by redefining the Tcl [cmd proc] command.
15Profiling is initiated via the [cmd ::profiler::init] command.
16
17[section COMMANDS]
18
19[list_begin definitions]
20
21
22[call [cmd ::profiler::init]]
23
24Initiate profiling.  All procedures created after this command is
25called will be profiled.  To profile an entire application, this
26command must be called before any other commands.
27
28[call [cmd ::profiler::dump] [arg pattern]]
29
30Dump profiling information for the all functions matching
31
32[arg pattern].  If no pattern is specified, information for all
33functions will be returned.  The result is a list of key/value pairs
34that maps function names to information about that function.  The
35information about each function is in turn a list of key/value pairs.
36The keys used and their values are:
37
38[list_begin definitions]
39
40[def [const totalCalls]]
41
42The total number of times [arg functionName] was called.
43
44[def [const callerDist]]
45
46A list of key/value pairs mapping each calling function that called
47[arg functionName] to the number of times it called
48
49[arg functionName].
50
51[def [const compileTime]]
52
53The runtime, in clock clicks, of [arg functionName] the first time
54that it was called.
55
56[def [const totalRuntime]]
57
58The sum of the runtimes of all calls of [arg functionName].
59
60[def [const averageRuntime]]
61
62Average runtime of [arg functionName].
63
64[def [const descendantTime]]
65
66Sum of the time spent in descendants of [arg functionName].
67
68[def [const averageDescendantTime]]
69
70Average time spent in descendants of [arg functionName]. 
71
72[list_end]
73
74
75[call [cmd ::profiler::print] [opt [arg pattern]]]
76
77Print profiling information for all functions matching [arg pattern].
78If no pattern is specified, information about all functions will be
79displayed.  The return result is a human readable display of the
80profiling information.
81
82[call [cmd ::profiler::reset] [opt [arg pattern]]]
83
84Reset profiling information for all functions matching [arg pattern].
85If no pattern is specified, information will be reset for all
86functions.
87
88[call [cmd ::profiler::suspend] [opt [arg pattern]]]
89
90Suspend profiling for all functions matching [arg pattern].  If no
91pattern is specified, profiling will be suspended for all
92functions. It stops gathering profiling information after this command
93is issued. However, it does not erase any profiling information that
94has been gathered previously.  Use resume command to re-enable
95profiling.
96
97[call [cmd ::profiler::resume] [opt [arg pattern]]]
98
99Resume profiling for all functions matching [arg pattern].  If no
100pattern is specified, profiling will be resumed for all functions.
101This command should be invoked after suspending the profiler in the
102code.
103
104[call [cmd ::profiler::sortFunctions] [arg key]]
105
106Return a list of functions sorted by a particular profiling statistic.
107Supported values for [arg key] are: [const calls],
108
109[const exclusiveTime], [const compileTime], [const nonCompileTime],
110[const totalRuntime], [const avgExclusiveTime], and
111
112[const avgRuntime].  The return result is a list of lists, where each
113sublist consists of a function name and the value of [arg key] for
114that function.
115
116[list_end]
117
118[section {BUGS, IDEAS, FEEDBACK}]
119
120This document, and the package it describes, will undoubtedly contain
121bugs and other problems.
122
123Please report such in the category [emph profiler] of the
124[uri {http://sourceforge.net/tracker/?group_id=12883} {Tcllib SF Trackers}].
125
126Please also report any ideas for enhancements you may have for either
127package and/or documentation.
128
129
130[keywords profile performance speed]
131[manpage_end]
132