'\"
'\" Generated from file 'profiler\&.man' by tcllib/doctools with format 'nroff'
'\"
.TH "profiler" n 0\&.5 tcllib "Tcl Profiler"
.\" The -*- nroff -*- definitions below are for supplemental macros used
.\" in Tcl/Tk manual entries.
.\"
.\" .AP type name in/out ?indent?
.\"	Start paragraph describing an argument to a library procedure.
.\"	type is type of argument (int, etc.), in/out is either "in", "out",
.\"	or "in/out" to describe whether procedure reads or modifies arg,
.\"	and indent is equivalent to second arg of .IP (shouldn't ever be
.\"	needed;  use .AS below instead)
.\"
.\" .AS ?type? ?name?
.\"	Give maximum sizes of arguments for setting tab stops.  Type and
.\"	name are examples of largest possible arguments that will be passed
.\"	to .AP later.  If args are omitted, default tab stops are used.
.\"
.\" .BS
.\"	Start box enclosure.  From here until next .BE, everything will be
.\"	enclosed in one large box.
.\"
.\" .BE
.\"	End of box enclosure.
.\"
.\" .CS
.\"	Begin code excerpt.
.\"
.\" .CE
.\"	End code excerpt.
.\"
.\" .VS ?version? ?br?
.\"	Begin vertical sidebar, for use in marking newly-changed parts
.\"	of man pages.  The first argument is ignored and used for recording
.\"	the version when the .VS was added, so that the sidebars can be
.\"	found and removed when they reach a certain age.  If another argument
.\"	is present, then a line break is forced before starting the sidebar.
.\"
.\" .VE
.\"	End of vertical sidebar.
.\"
.\" .DS
.\"	Begin an indented unfilled display.
.\"
.\" .DE
.\"	End of indented unfilled display.
.\"
.\" .SO ?manpage?
.\"	Start of list of standard options for a Tk widget. The manpage
.\"	argument defines where to look up the standard options; if
.\"	omitted, defaults to "options". The options follow on successive
.\"	lines, in three columns separated by tabs.
.\"
.\" .SE
.\"	End of list of standard options for a Tk widget.
.\"
.\" .OP cmdName dbName dbClass
.\"	Start of description of a specific option.  cmdName gives the
.\"	option's name as specified in the class command, dbName gives
.\"	the option's name in the option database, and dbClass gives
.\"	the option's class in the option database.
.\"
.\" .UL arg1 arg2
.\"	Print arg1 underlined, then print arg2 normally.
.\"
.\" .QW arg1 ?arg2?
.\"	Print arg1 in quotes, then arg2 normally (for trailing punctuation).
.\"
.\" .PQ arg1 ?arg2?
.\"	Print an open parenthesis, arg1 in quotes, then arg2 normally
.\"	(for trailing punctuation) and then a closing parenthesis.
.\"
.\"	# Set up traps and other miscellaneous stuff for Tcl/Tk man pages.
.if t .wh -1.3i ^B
.nr ^l \n(.l
.ad b
.\"	# Start an argument description
.de AP
.ie !"\\$4"" .TP \\$4
.el \{\
.   ie !"\\$2"" .TP \\n()Cu
.   el          .TP 15
.\}
.ta \\n()Au \\n()Bu
.ie !"\\$3"" \{\
\&\\$1 \\fI\\$2\\fP (\\$3)
.\".b
.\}
.el \{\
.br
.ie !"\\$2"" \{\
\&\\$1	\\fI\\$2\\fP
.\}
.el \{\
\&\\fI\\$1\\fP
.\}
.\}
..
.\"	# define tabbing values for .AP
.de AS
.nr )A 10n
.if !"\\$1"" .nr )A \\w'\\$1'u+3n
.nr )B \\n()Au+15n
.\"
.if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n
.nr )C \\n()Bu+\\w'(in/out)'u+2n
..
.AS Tcl_Interp Tcl_CreateInterp in/out
.\"	# BS - start boxed text
.\"	# ^y = starting y location
.\"	# ^b = 1
.de BS
.br
.mk ^y
.nr ^b 1u
.if n .nf
.if n .ti 0
.if n \l'\\n(.lu\(ul'
.if n .fi
..
.\"	# BE - end boxed text (draw box now)
.de BE
.nf
.ti 0
.mk ^t
.ie n \l'\\n(^lu\(ul'
.el \{\
.\"	Draw four-sided box normally, but don't draw top of
.\"	box if the box started on an earlier page.
.ie !\\n(^b-1 \{\
\h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
.\}
.el \}\
\h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
.\}
.\}
.fi
.br
.nr ^b 0
..
.\"	# VS - start vertical sidebar
.\"	# ^Y = starting y location
.\"	# ^v = 1 (for troff;  for nroff this doesn't matter)
.de VS
.if !"\\$2"" .br
.mk ^Y
.ie n 'mc \s12\(br\s0
.el .nr ^v 1u
..
.\"	# VE - end of vertical sidebar
.de VE
.ie n 'mc
.el \{\
.ev 2
.nf
.ti 0
.mk ^t
\h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n'
.sp -1
.fi
.ev
.\}
.nr ^v 0
..
.\"	# Special macro to handle page bottom:  finish off current
.\"	# box/sidebar if in box/sidebar mode, then invoked standard
.\"	# page bottom macro.
.de ^B
.ev 2
'ti 0
'nf
.mk ^t
.if \\n(^b \{\
.\"	Draw three-sided box if this is the box's first page,
.\"	draw two sides but no top otherwise.
.ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c
.el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c
.\}
.if \\n(^v \{\
.nr ^x \\n(^tu+1v-\\n(^Yu
\kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c
.\}
.bp
'fi
.ev
.if \\n(^b \{\
.mk ^y
.nr ^b 2
.\}
.if \\n(^v \{\
.mk ^Y
.\}
..
.\"	# DS - begin display
.de DS
.RS
.nf
.sp
..
.\"	# DE - end display
.de DE
.fi
.RE
.sp
..
.\"	# SO - start of list of standard options
.de SO
'ie '\\$1'' .ds So \\fBoptions\\fR
'el .ds So \\fB\\$1\\fR
.SH "STANDARD OPTIONS"
.LP
.nf
.ta 5.5c 11c
.ft B
..
.\"	# SE - end of list of standard options
.de SE
.fi
.ft R
.LP
See the \\*(So manual entry for details on the standard options.
..
.\"	# OP - start of full description for a single option
.de OP
.LP
.nf
.ta 4c
Command-Line Name:	\\fB\\$1\\fR
Database Name:	\\fB\\$2\\fR
Database Class:	\\fB\\$3\\fR
.fi
.IP
..
.\"	# CS - begin code excerpt
.de CS
.RS
.nf
.ta .25i .5i .75i 1i
..
.\"	# CE - end code excerpt
.de CE
.fi
.RE
..
.\"	# UL - underline word
.de UL
\\$1\l'|0\(ul'\\$2
..
.\"	# QW - apply quotation marks to word
.de QW
.ie '\\*(lq'"' ``\\$1''\\$2
.\"" fix emacs highlighting
.el \\*(lq\\$1\\*(rq\\$2
..
.\"	# PQ - apply parens and quotation marks to word
.de PQ
.ie '\\*(lq'"' (``\\$1''\\$2)\\$3
.\"" fix emacs highlighting
.el (\\*(lq\\$1\\*(rq\\$2)\\$3
..
.\"	# QR - quoted range
.de QR
.ie '\\*(lq'"' ``\\$1''\\-``\\$2''\\$3
.\"" fix emacs highlighting
.el \\*(lq\\$1\\*(rq\\-\\*(lq\\$2\\*(rq\\$3
..
.\"	# MT - "empty" string
.de MT
.QW ""
..
.BS
.SH NAME
profiler \- Tcl source code profiler
.SH SYNOPSIS
package require \fBTcl  8\&.3\fR
.sp
package require \fBprofiler  ?0\&.5?\fR
.sp
\fB::profiler::init\fR
.sp
\fB::profiler::dump\fR \fIpattern\fR
.sp
\fB::profiler::print\fR ?\fIpattern\fR?
.sp
\fB::profiler::reset\fR ?\fIpattern\fR?
.sp
\fB::profiler::suspend\fR ?\fIpattern\fR?
.sp
\fB::profiler::resume\fR ?\fIpattern\fR?
.sp
\fB::profiler::new-disabled\fR
.sp
\fB::profiler::new-enabled\fR
.sp
\fB::profiler::sortFunctions\fR \fIkey\fR
.sp
.BE
.SH DESCRIPTION
.PP
The \fBprofiler\fR 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 \fBproc\fR command\&.
Profiling is initiated via the \fB::profiler::init\fR command\&.
.SH COMMANDS
.TP
\fB::profiler::init\fR
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\&.
.TP
\fB::profiler::dump\fR \fIpattern\fR
Dump profiling information for the all functions matching
\fIpattern\fR\&.  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:
.RS
.TP
\fBtotalCalls\fR
The total number of times \fIfunctionName\fR was called\&.
.TP
\fBcallerDist\fR
A list of key/value pairs mapping each calling function that called
\fIfunctionName\fR to the number of times it called
\fIfunctionName\fR\&.
.TP
\fBcompileTime\fR
The runtime, in clock clicks, of \fIfunctionName\fR the first time
that it was called\&.
.TP
\fBtotalRuntime\fR
The sum of the runtimes of all calls of \fIfunctionName\fR\&.
.TP
\fBaverageRuntime\fR
Average runtime of \fIfunctionName\fR\&.
.TP
\fBdescendantTime\fR
Sum of the time spent in descendants of \fIfunctionName\fR\&.
.TP
\fBaverageDescendantTime\fR
Average time spent in descendants of \fIfunctionName\fR\&.
.RE
.TP
\fB::profiler::print\fR ?\fIpattern\fR?
Print profiling information for all functions matching \fIpattern\fR\&.
If no pattern is specified, information about all functions will be
displayed\&.  The return result is a human readable display of the
profiling information\&.
.TP
\fB::profiler::reset\fR ?\fIpattern\fR?
Reset profiling information for all functions matching \fIpattern\fR\&.
If no pattern is specified, information will be reset for all
functions\&.
.TP
\fB::profiler::suspend\fR ?\fIpattern\fR?
Suspend profiling for all functions matching \fIpattern\fR\&.  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\&.
.TP
\fB::profiler::resume\fR ?\fIpattern\fR?
Resume profiling for all functions matching \fIpattern\fR\&.  If no
pattern is specified, profiling will be resumed for all functions\&.
This command should be invoked after suspending the profiler in the
code\&.
.TP
\fB::profiler::new-disabled\fR
Change the initial profiling state for new procedures\&. Invoking this
command disables profiling for all procedures created after this
command until \fBnew-enabled\fR is invoked\&. Activate profiling of
specific procedures via \fBresume\fR\&.
.TP
\fB::profiler::new-enabled\fR
Change the initial profiling state for new procedures\&. Invoking this
command enables profiling for all procedures created after this
command until \fBnew-disabled\fR is invoked\&. Prevent profiling of
specific procedures via \fBsuspend\fR\&.
.TP
\fB::profiler::sortFunctions\fR \fIkey\fR
Return a list of functions sorted by a particular profiling statistic\&.
Supported values for \fIkey\fR are: \fBcalls\fR,
\fBexclusiveTime\fR, \fBcompileTime\fR, \fBnonCompileTime\fR,
\fBtotalRuntime\fR, \fBavgExclusiveTime\fR, and
\fBavgRuntime\fR\&.  The return result is a list of lists, where each
sublist consists of a function name and the value of \fIkey\fR for
that function\&.
.PP
.SH "BUGS, IDEAS, FEEDBACK"
This document, and the package it describes, will undoubtedly contain
bugs and other problems\&.
Please report such in the category \fIprofiler\fR of the
\fITcllib Trackers\fR [http://core\&.tcl\&.tk/tcllib/reportlist]\&.
Please also report any ideas for enhancements you may have for either
package and/or documentation\&.
.PP
When proposing code changes, please provide \fIunified diffs\fR,
i\&.e the output of \fBdiff -u\fR\&.
.PP
Note further that \fIattachments\fR are strongly preferred over
inlined patches\&. Attachments can be made by going to the \fBEdit\fR
form of the ticket immediately after its creation, and then using the
left-most button in the secondary navigation bar\&.
.SH KEYWORDS
performance, profile, speed
.SH CATEGORY
Programming tools