classBrowser v1.1 - Profiler for [incr Tcl]

A utility for displaying useful information about the [incr Tcl] classes used in a program:

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.

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:

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

Implementation

The classBrowser consists of two packages:

classIntrospection

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:

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:

-cbTimeInfo

<class> <method/proc> <time in microseconds>

-public

If TRUE, instrument public components of the class, and if FALSE, ignore them. Defaults to TRUE.

-protected

If TRUE, instrument protected components of the class, and if FALSE, ignore them. Defaults to FALSE.

-private

If TRUE, instrument private components of the class, and if FALSE, ignore them. Defaults to FALSE.

-debug

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.

classBrowser

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:

-nopublic
If TRUE, omit instrumentation of public methods and procs. Defaults to FALSE.

-protected
If TRUE, instrument protected methods and procs. Defaults to FALSE.

-private
If TRUE, instrument private methods and procs. Defaults to FALSE.

-debug

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:

classBrowserTest1

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.

classBrowserTest2

Demonstration application that uses the classBrowser widget to describe the classes of incr-widgets.

classBrowserTest3

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

Copyright

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.

Comments

To the author, Paul Welton, at <crossrad@users.sourceforge.net>

last updated: 10th July 2002