SUIF Objects

Most of the significant classes in the SUIF library are derived from a common base class. This suif_object class includes a field with a pointer to a list of annotations. Thus, annotations can be attached to most objects in SUIF, and all of these objects share the same interface for accessing the annotations. The files `suifobj.h' and `suifobj.cc' contain the code for the suif_object class.

Besides the annotation list, each suif_object has a field to identify the kind of the object. The object_kind method retrieves the value from this field. The object_kinds enumerated type defines the possible values:

FILE_OBJ

File set entry. See section File Set Entries.

TREE_OBJ

Abstract syntax tree node. See section Tree Nodes.

INSTR_OBJ

SUIF instruction. See section Instructions and Expression Trees.

SYMTAB_OBJ

Symbol table. See section Symbol Tables.

SYM_OBJ

Symbol node. See section Symbols.

DEF_OBJ

Variable definition. See section Variable Definitions.

TYPE_OBJ

Type node. See section Types.

The rest of the methods in the suif_object class are related to handling annotations. First of all, the are_annotations method checks to see if an object has any annotations attached to it. If so, the annotes method can be used to retrieve a pointer to the list of annotations. Do not just grab the list of annotations and check to see if it is empty, but use are_annotations instead. Since many objects don't have any annotations, the library doesn't allocate annotation lists unless they are needed. Calling annotes will create a new list if one did not already exist, so to avoid creating a lot of empty lists use are_annotations first.

The prepend_annote and append_annote methods are a convenient way to add new annotations to an object. They simply create a new annotation using the specified name and data and then add it to the beginning or end, respectively, of the annotation list. If the object is only supposed to have one annotation with a particular name, the set_annote method works well for assigning new values for that annotation. If the object already has an annotation with the specified name, set_annote will replace the existing one (or the first one that it finds); otherwise, it just adds the new annotation at the end of the list.

There are two different methods to retrieve data from annotations attached to an object. The first, peek_annote, simply returns the data field from the first annotation that it finds with the specified name. If it doesn't find any annotations with that name, it returns a NULL pointer. The get_annote method does the same thing except that it is destructive. Besides returning the data from the annotation, it also removes the annotation from the list and destroys it. Note that with these methods it is impossible to distinguish the case where an annotation exists but has a NULL data field from the case where the annotation does not exist. If you want to retrieve the actual annotation objects instead of just their data fields, the annotation list (see section Annotation Lists) provides peek_annote and get_annote methods to do that.

When some kinds of SUIF objects (e.g. symbols and types) are copied, the annotations are omitted. If you want to copy the annotations as well as the base objects, the copy_annotes method must be called separately. This method works for any two SUIF objects; they do not have to be the same kind. If the target object already has some annotations, the new ones are appended to the end of the list. Unregistered annotations are not copied.

The suif_object class provides a print_annotes method for printing the annotation list to a text file. This is used by the print methods for the derived classes, but it could also be used directly by users. The optional depth parameter specifies the indentation level. Beware that a new-line character is printed before each annotation and thus you probably want to print a new-line after calling this method.

The num_output_annotes method checks to see if an object has any annotations, and if so, it counts the ones that will be written to the output file. This is primarily used by the SUIF library and most users will not need it.