Defining Prototypes

A prototype contains the names of Tcl callback functions that are used at various times in the type transformation process, as follows:

• When TotalView is creating a type object, it validates the prototype by using a callback function that checks if the name of the prototype matches that of the data type.
   
• When TotalView is about to display an object with this prototype, it invokes callbacks that extract object properties.
   
• If a typedef is being set up, TotalView calls the typedef_callback.

As you will see, there are two styles of prototypes: arrays and structs. As part of the process of defining the prototype, you must tell TotalView which style you are creating.

The following properties are (or can be) included in all prototypes. Other sections in this chapter present the routines that are associated with these callbacks.

name

(required) The regular expression that TotalView uses to match types. It must be anchored (that is, start with a "^" character.

language

(required) The language for this prototype. It indicates how TotalView parses the program's data and generates bounds and indices for it.

validate_callback

(required) TotalView invokes this callback whenever a type that matches the prototype's name is defined. It returns a Boolean value indicating if it should be applied. This callback lets you have more than one prototype match a type name, and then investigate the type to determine if TotalView should apply the prototype.

The call structure for a validation callback is:

    validate_callback type_id

where type_id is the type identifier for the type being prototyped.

address_callback

Generates the address of the object's elements at run time. It returns either an absolute address, or an addressing expression that is appended to the address of the object to give the address of the field. (Returning an expression is the preferred method.)

For example, you might use a callback if the original data structure contains information on where the next data instance resides.

If you are creating a type for a distributed array, this procedure returns a two-element list. For more information, see The Distributed Addressing Callback.

The call structure for an address callback is:

    address_callback type_id object_addr index [replication]

where:

type_id: is the type identifier for the type being prototyped.

object_addr: is the address of the object.

index: is the index string for the array element or the index of the field in the structure.

replication: is only used for distributed array objects. It indicates that the result is an address and an index into the distribution to determine the process within which this element resides, since this is a distributed array.

type_callback

(required) TotalView invokes this callback when the prototype is modifying a type. Its format is:

    type_callback type_id

Array prototypes: Returns a value that is the type identifier for one of the array's elements.

Struct prototypes: Returns a list in the format of the struct_fields property that describes the struct type's fields. If a field in the type requires a callback, the addressing section of its field description should be the string callback rather than an addressing expression. In this case, TotalView uses the address_callback to generate the address of this field.

typedef_callback

Defines an new_type_id in terms of the old_type_id. You would use this callback when the prototype modifies old_type_id.

    typedef_callback new_type_id old_type_id

TotalView ignores any returned value.

The following three callbacks are only used with array prototypes:

bounds_callback

Returns either a string that specifies the bounds statically or a callback that TotalView calls when the object's address is known. If you are naming a callback, its call structure is:

    bounds_callback type_id object_address

The string returned by the callback describes the current bounds. This string must be in program's programming language. For example:

    C: [2][40]
    Fortran: (-2:10,-5:5)

If the bounds start with a bracket "[" or a parenthesis "(", TotalView assumes the bounds are static; otherwise, TotalView assumes that the returned value is the name of a callback function.

As the bracket characters ([ ]) are special characters in Tcl, you must escape them even in strings; for example \[20\] rather than [20].

rank_callback

Returns the array's rank. TotalView uses this callback when the prototype modifies a type. Its call structure is:

    rank_callback type_id

distribution_callback

Returns a list of process or thread identifiers that represent (in order) the processes/threads in which elements of this array exist. Only use this callback when your array is distributed over multiple processes. Its call structure is:

    distribution_callback type_id object_address

TotalView calls this callback with a replication index. The returned value must have an index into the distribution as well as an address.

Before using the TV::image add prototype command to add a prototype to an image, you must use the TV::prototype set command to set its properties. After a prototype is added to an image, you can no longer change its properties.