Applying Prototypes to Images

The properties of a prototype do not affect an object until you add it to an image by using the TV::image add command. Here is this command's format:

    TV::image add image_id   prototype proto_id

When you load a prototype, TotalView looks within its TV::image_load_callbacks variable. This variable contains a Tcl list of procedure names, each of which is invoked by TotalView whenever a new image is loaded by TotalView. This could occur when:

• A user invokes a command such as dload.
• TotalView resolves dynamic library dependencies.
• User code uses dlopen() to load a new image.

TotalView always initially sets this variable to a list containing the name of the TV::propagate_prototypes routine. This function applies all prototypes to every new image as it is loaded. Therefore, if you create prototypes before any image is loaded (for instance, by executing prototype creation code in a .tvdrc file), TV::propagate_prototypes tells TotalView to apply all prototypes to all images as they are loaded.

By adding other function names to the TV::image_load_callbacks list, you can tell TotalView to take additional actions. For instance, you could define prototypes for g++ STL only when /lib/libstdc++.so is loaded.

TotalView invokes the functions in order, beginning at the first function in the list.

If you create prototypes after images are loaded, and you want the prototypes to be applied to the existing images, you will need to apply them explicitly to these images. The following example shows the kind of procedure that you could write to apply prototypes to all images in the current focus.

# Given the identifier for a prototype object, add it to all 
# images used by processes in the current focus. 
proc apply_prototype_to_focus {proto_id} {
        set processes [TV::focus_processes]
    
    # Find the set of images.
    foreach process $processes {
        set images [TV::process get $process image_ids]
        foreach image $images {
            set image_names($image) true
        }
    }
    
    # Now add the prototype to the image.
    foreach image [array names image_names] {
        TV::image add $image prototype $proto_id
    }
}

Note:   You can change any of a prototype's properties before its added. As soon as you add one, however, its properties are frozen and TotalView does not allow you to alter them.

Here is how you would invoke this function:

apply_prototype_to_focus $proto_id