classBrowser v1.1 - Profiler for [incr Tcl]

A utility for displaying useful information about the [incr Tcl] classes used in a program: This screenshot shows an example of the display that will be generated, taken from the test program ./classBrowserTest1

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 command:

::classBrowser::classBrowser <pathname>
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:
toplevel .t
pack [::classBrowser::classBrowser .t.b]
Do this before sourcing the scripts which declare the [incr Tcl] classes that you wish to profile.

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 whenever needed.

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.

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 package.

Instrumentation Overhead

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:
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.
Before loading any [incr Tcl] classes that are to be instrumented:
  1. call "package require classIntrospection"; and,
  2. configure the following variables with the configure routine of the form:

    classIntrospection::configure -<flag> <value> -<flag> <value> ...

    The following options are supported:
    1. -cbTimeInfo
        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 possible.
        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 FALSE.
If TRUE, instrument private methods and procs. Defaults to FALSE.
If TRUE, generate an information message if unexpected commands are found within a class body during instrumentation. Defaults to FALSE.
The widget behaves as described in Controlling the classBrowser .

Test Applications

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.

Package Requirements

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:
Package Name Test Configuration 1 Test Configuration 2
Tcl 8.3.3 8.4b1
Tk 8.3.3 8.4b1
Itcl 3.2 3.2.1
Iwidgets 3.1.0 4.0.0
Tktable 2.7 2.7


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 <>

last updated: 10th July 2002