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