A utility for displaying useful information about the [incr Tcl] classes
used in a program:
classBrowser v1.1 - Profiler for [incr Tcl]
screenshot shows an example of the display that will be generated, taken
from the test program ./classBrowserTest1.
Names of classes;
Names of the methods, variables, procs and commons in each class.
Execution times and execution counts for each proc and method, which may
be updated or cleared on demand.
May be configured to show only public items, or to include protected and
private items as well.
Adding the classBrowser to an [incr Tcl] program
Minimal changes to an [incr Tcl] program are required to add the classBrowser.
Unpack the release into a directory with the commands:
gzip -cd classBrowser1.1.tar.gz | tar xvf -
Append the full pathname of the directory into which the files have been
unpacked to the list in the global variable "auto_path".
Create the classBrowser widget in the same way as any other widget with
The value returned is the value of the pathname supplied. Normally, the
classBrowser would be included in a program temporarily, so it may be best
to create a separate toplevel for it:
Do this before sourcing the scripts which declare the [incr Tcl] classes
that you wish to profile.
pack [::classBrowser::classBrowser .t.b]
Then run the program as usual. It may be sensible to add a command line
flag to the program (for example, "-browser") which can load it
Controlling the classBrowser
The classBrowser is easy to control. The following buttons may each be
used at any time:
The optionmenu "mode:" allows the display to be switched between
percentage and absolute times without resetting the time information. Note
that because Iwidgets are used by the classBrowser, hitting the classBrowser
buttons causes methods to be invoked and the time information to change.
In the "percentage" mode, this will cause all of the data to change
even if no events have been processed in the program being tested, which
can be confusing.
Hit "Reconstruct" to cause the display to be regenerated to include any
new classes that have been declared, and also to cause the time information
to be updated.
Hit "update time info" which updates the time information but does not
reconstruct the table. This has the advantage of not changing the scroll
position of the table, as well as being faster.
Hit "clear time info" to reset all time and execution count values to zero.
Note that zero values are displayed as a blank.
The checkbuttons "heritage" and "variable" control whether additional
columns listing the corresponding details of the class should be shown.
The checkbutton "debug" controls the "debug" option of the classIntrospection
The profiling capability is implemented by instrumenting the bodies of
each [incr Tcl] method and proc, by adding additional code to measure and
report the execution time of each call. This slows down the program, but
in practice the effect is not large and the time information is very useful
in pinpointing where code optimizations will have the greatest value.
The classBrowser consists of two packages:
The purpose of this package is to extend the functionality of the procedure
"class" of the package "itcl". An info option is added which allows
the public interface to the class to be investigated programmatically.
The extended syntax is as follows:
Before loading any [incr Tcl] classes that are to be instrumented:
class <className> <definition>
This is the original form. In addition to declaring the specified class,
information about the class is collected and stored in a database.
class <className> info heritage|variable|proc|method|common
The first option returns a list of the classes which are inherited directly
by the specified class, while the remainder return a list of the names
of the public items in the class definition of the specified type.
call "package require classIntrospection"; and,
configure the following variables with the configure routine of the form:
classIntrospection::configure -<flag> <value> -<flag> <value>
The following options are supported:
Specify a callback to distribute information on execution counts and
timing. The callback procedure must take arguments of the form:
<class> <method/proc> <time in microseconds>
If not set, then the timing shell instrumentation will not be added.
In this case, the program will not be slowed down by the overhead of the
timing wrapper, but class introspection as described above will still be
If TRUE, instrument public components of the class, and if FALSE, ignore
them. Defaults to TRUE.
If TRUE, instrument protected components of the class, and if FALSE,
ignore them. Defaults to FALSE.
If TRUE, instrument private components of the class, and if FALSE,
ignore them. Defaults to FALSE.
If TRUE, generate an information message if unexpected commands are
found within a class body during instrumentation. This is needed
because a class declaration may contain commands other than those specific
to Itcl such as "method". An example is "itk_option". Defaults to FALSE.
This package implements the GUI, and is based in turn on the package Tktable.
Version 2.7 of Tktable is required, because earlier versions suffer from
a problem in which areas of the display may not be drawn, in a manner dependent
on the characteristics of the display.
The procedure ::classBrowser::classBrowser takes as a mandatory
argument the name of the window to be created, which is also returned as
the result of the procedure. The remaining arguments are flag/value pairs
which are used to configure the classIntrospection package as follows:
If TRUE, omit instrumentation of public methods and procs.
Defaults to FALSE.
If TRUE, instrument protected methods and procs. Defaults to
If TRUE, instrument private methods and procs. Defaults to
The widget behaves as described in Controlling
the classBrowser .
If TRUE, generate an information message if unexpected commands
are found within a class body during instrumentation. Defaults to FALSE.
A suite of three applications are provided to test the classBrowser:
Minimalist application that uses the classBrowser widget to
describe a test class which exercises each of the cases of declarations
which are (i) preceded by "public", "protected" or "private" or unspecified;
(ii) are placed in a subscript preceded by one of those scope keywords.
Demonstration application that uses the classBrowser widget
to describe the classes of incr-widgets.
Test to exercise profiling for methods that have bodies declared
(i) in the class declaration or (ii) with separate itcl::body commands.
After loading, hit "execute each method of class c" and "update time info".
All four factorial methods show similar statistics - factorial1
and factorial2 have methods declared within the class declaration,
while factorial3 and factorial4 have methods declared
using separate itcl::body commands.
factorial2 and factorial4 use "expr" commands in which
the expressions are not protected against unnecessary double-substitution
with braces, and should therefore be slower than factorial1 and
factorial3 which are otherwise identical.
There are no specific requirements for package versions (except for Tktable
as documented under classBrowser ). The
following table lists the package versions which have been tested and are
known support the test programs described above:
||Test Configuration 1
||Test Configuration 2
Permission to use, copy, modify, and distribute this software and its documentation
for any purpose and without fee is hereby granted, provided that this copyright
notice appears in all copies. No representations are made about the
suitability of this software for any purpose. It is provided "as
is" without express or implied warranty.
To the author, Paul Welton, at <firstname.lastname@example.org>
last updated: 10th July 2002