Saint:: Stand Alone Instrumenter

This is the design documentation for the saint or Stand Alone Instrumenter package for Tuba and other Tcl tools.
 

Background

In Tuba, the instrumenter is tightly integrated in the debugger code. This makes a tool like testinstrumenter very difficult. And any other non-Tuba use of the instrumenter (such as Tea) is next to impossible.

Goals

I want to decouple the instrumenter from the debugger so that it can be used as a general code instrumenter. Tools that can use this could be a proc lister, line-of-code counter, a profiler, code documentors, etc.

Another advantage to this decoupling is to be able to swap in different parsers for Tuba.

Interfaces

In order for the instrumenter to have some smarts, there needs to be a two-way communication between the instrumenter and the client. This interface will be in terms of procs (a Tea class version will be available later).
 

Instrumenter Interface

All procs of the instrumenter should be defined in a namespace called instrumenter. This namespace should be relative so that the client can stick it anywhere it wants.
 

Namespace

All instrumenting implementations must adhere to the following interface. This allows the client to talk to the instrumenter in an abstract fashion.

The namespace definition should look something like this:

The procs

The following procs must be defined by the instrumenter. Clients should not assume that these will be exported.
instrumenter::init {libdir clientns options}
instrumenter::instrument {file}
instrumenter::purgeCache {}
instrumenter::getLevel {}

Client Interface

The client must also provide an interface for the instrumenter. There are two types of callbacks the instrumenter will make back to the client: those at instrument time, and those at runtime.

Namespace

The client tells the instrumented the namespace to use for the callbacks when he calls the instrumenter::init proc; therefore, there is no special namespace requirements for the client.

Instrument-time procs

Instrument time callbacks are mostly for statistics to inform the client when various Tcl entities crop up, like procs or statements.
foundCommand{file line commandvar}
foundComment {file begline commentvar}
 foundProc {file line commandvar procnamevar dynamicflag}

Run-time procs

Runtime callbacks are invoked if the instrumented code is ever run.
statement {file line stmt}
procEntry {procname}
procExit {procname}