Go to the first, previous, next, last section, table of contents.
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
TREE_OBJ
INSTR_OBJ
SYMTAB_OBJ
SYM_OBJ
DEF_OBJ
TYPE_OBJ
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.
Go to the first, previous, next, last section, table of contents.