NAME

       profiler - Tcl source code profiler

SYNOPSIS

       package require Tcl  8.3

       package require profiler  ?0.3?

       ::profiler::init

       ::profiler::dump pattern

       ::profiler::print ?pattern?

       ::profiler::reset ?pattern?

       ::profiler::suspend ?pattern?

       ::profiler::resume ?pattern?

       ::profiler::sortFunctions key

_________________________________________________________________________________________________

DESCRIPTION

       The  profiler  package provides a simple Tcl source code profiler.  It is a function-level
       profiler; that is, it collects only function-level  information,  not  the  more  detailed
       line-level  information.   It  operates  by redefining the Tcl proc command.  Profiling is
       initiated via the ::profiler::init command.

COMMANDS

       ::profiler::init
              Initiate profiling.  All procedures created after this command is  called  will  be
              profiled.  To profile an entire application, this command must be called before any
              other commands.

       ::profiler::dump pattern
              Dump profiling information for the all functions matching pattern.  If  no  pattern
              is specified, information for all functions will be returned.  The result is a list
              of key/value pairs that maps function names to  information  about  that  function.
              The information about each function is in turn a list of key/value pairs.  The keys
              used and their values are:

              totalCalls
                     The total number of times functionName was called.

              callerDist
                     A list  of  key/value  pairs  mapping  each  calling  function  that  called
                     functionName to the number of times it called functionName.

              compileTime
                     The  runtime,  in  clock  clicks, of functionName the first time that it was
                     called.

              totalRuntime
                     The sum of the runtimes of all calls of functionName.

              averageRuntime
                     Average runtime of functionName.

              descendantTime
                     Sum of the time spent in descendants of functionName.

              averageDescendantTime
                     Average time spent in descendants of functionName.

       ::profiler::print ?pattern?
              Print profiling information for all functions matching pattern.  If no  pattern  is
              specified, information about all functions will be displayed.  The return result is
              a human readable display of the profiling information.

       ::profiler::reset ?pattern?
              Reset profiling information for all functions matching pattern.  If no  pattern  is
              specified, information will be reset for all functions.

       ::profiler::suspend ?pattern?
              Suspend  profiling for all functions matching pattern.  If no pattern is specified,
              profiling will be  suspended  for  all  functions.  It  stops  gathering  profiling
              information  after this command is issued. However, it does not erase any profiling
              information that has been gathered previously.  Use  resume  command  to  re-enable
              profiling.

       ::profiler::resume ?pattern?
              Resume  profiling  for all functions matching pattern.  If no pattern is specified,
              profiling will be resumed for all functions.  This command should be invoked  after
              suspending the profiler in the code.

       ::profiler::sortFunctions key
              Return  a  list of functions sorted by a particular profiling statistic.  Supported
              values  for   key   are:   calls,   exclusiveTime,   compileTime,   nonCompileTime,
              totalRuntime,  avgExclusiveTime,  and  avgRuntime.   The return result is a list of
              lists, where each sublist consists of a function name and the value of key for that
              function.

BUGS, IDEAS, FEEDBACK

       This  document,  and  the  package  it  describes, will undoubtedly contain bugs and other
       problems.   Please  report  such  in  the  category  profiler  of  the   Tcllib   Trackers
       [http://core.tcl.tk/tcllib/reportlist].  Please also report any ideas for enhancements you
       may have for either package and/or documentation.

KEYWORDS

       performance, profile, speed

CATEGORY

       Programming tools