profiler(n)							   Tcl Profiler 						       profiler(n)

__________________________________________________________________________________________________________________________________________________

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  function-
		     Name.

	      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 func-
	      tions.

       ::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, compile-
	      Time, nonCompileTime, totalRuntime, avgExclusiveTime, and avgRuntime.  The return result is a list of lists, where each sublist con-
	      sists 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 SF Trackers [http://sourceforge.net/tracker/?group_id=12883].  Please also report any ideas for enhancements you may have for
       either package and/or documentation.

KEYWORDS

       performance, profile, speed

CATEGORY

       Programming tools

profiler								0.3							       profiler(n)