Writing a Data Display Function
The frame of reference in describing this is C++.
In order for C++View to work correctly, the code you write and TotalView must cooperate. There are two key issues here. The first is registering your function so that TotalView can find it when it needs to format data for display. This is straightforward: all you need to do is to define your function to have the right name and prototype. When TotalView needs to format the data of type T, it will look for a function with this signature:
int TV_ttf_display_type ( const T * );
The const is deliberate to remind you that changes should not be made to the object being formatted for display. Many real-world applications are not entirely const-correct, and in cases where you must cast away the const, extreme caution is advised.
You will need to define a TV_ttf_display_type function for each type you want to format. A TV_ttf_display_type function may be at global scope, or it may be a class (static) method. It cannot be a member function.
The second issue concerns how the TV_ttf_display_type function which you will write communicates with TotalView. The API you will need to use is given in the header file tv_data_display.h included with your TotalView distribution in the <totalview-installation>/src directory.
Your TV_ttf_display_type will use the provided function TV_ttf_add_row to tell TotalView what information should be displayed. Its prototype is:
int TV_ttf_add_row ( const char *field_name,
const char *type_name,
const char *address );
The field_name parameter is the descriptive name of the data field being computed. It will be shown by TotalView in a form similar to that of the name of a structure's field. The type_name parameter is the type of the data to be displayed. It must be the name of a legal type name in the program, or one of TotalView's types.
As a convenience, the header file provides these symbols for you:
TV_ttf_type_ascii_string
This tells TotalView to format a character array as a string (i.e., left to right) instead of an array (top to bottom).
TV_ttf_type_int
This is an alias for TotalView integer type $int.
The third parameter, address, is the address in your program's address space of the object to be displayed.
TV_ttf_add_row should be called only as a result of TotalView invoking your TV_ttf_display_type function. It may be called by a TV_ttf_display_type called by TotalView, or by one of the descendant callees of that TV_ttf_display_type.
Example
Here are the definitions of a couple of classes:
class A {
int i;
char *s;
};
class B {
A a;
double d;
};
We can define the display callback functions as follows:
int TV_ttf_display_type ( const A *a )
{
/* NOTE: error checking of value returned from TV ttf add_row \
omitted */
(void) TV_ttf_add_row ( "i", TV_ttf_type_int, &(a->i) );
(void) TV_ttf_add_row ( "s", TV_ttf_type_ascii_string, a->s );
/* indicate success to TotalView */
TV_ttf_format_ok;
}
int TV_ttf_display_type ( const B *b )
{
/* NOTE: error checking of value returned from TV ttf add_row \
omitted */
(void) TV_ttf_add_row ( "a", "A", &(b->a) );
(void) TV_ttf_add_row ( "d", "double", &(b->d) );
/* indicate success to TotalView */
return TV_ttf_format_ok;
}
For brevity and clarity, we have omitted all error checking of the value returned from TV_ttf_add_row. We will discuss the possible values that a TV_ttf_display_type may return later.
For now, we just return a simple success.
We could have made one or both of the display callbacks a class method:
class A {
int i;
char *s;
public:
static int TV_ttf_display_type ( const A *a );
};
int A::TV_ttf_display_type ( const A *a )
{
/* as before */
}
and similarly for class B.
