In many cases, flat annotations are cumbersome to use because the fields
in the immed value list are unlabeled and difficult to access.
With structured annotations, the data is held in a user-defined
structure. You can access this structured data by using the data
method and casting the result to the desired type. It may be helpful to
define macros to perform the type casts.
An important restriction on structured annotations is that if they are
to be stored in SUIF files, they are stored as immed lists.
Therefore, if you wish to write such an annotation to a file, you must
provide the annotation manager with functions to convert back and
forth between the immed lists and the structured data. When a
structured annotation is first read from an input file, the annotation
manager applies the function to convert the immed list to your
data structure. Similarly, when the annotation is written out, the
manager applies the function to convert it back to a list of
immed values.
The data in a structured annotation that defines a conversion function
must always be maintained in a form that can be converted to an
immed list. This is necessary because the library occasionally
needs to flatten annotations so that it can update the contents. For
example, when an annotation containing references to local symbols is
moved to another scope, the symbols may need to be updated. When this
occurs, the library also converts the data back to its structured form
after it has been updated.
Just as the library needs to temporarily flatten structured annotations,
you may need to do the same. The immeds and set_immeds
methods make this task much easier. The immeds method returns
the annotation data represented as an immed list. For a
structured annotation, it does this by using the conversion function
registered with the annotation manager to convert the structure to a
flat list. Note however that the result is a pointer to a new list,
whereas for flat annotations, it is a pointer to the actual annotation
data. Similarly, the set_immeds method replaces the annotation
data with the data in an immed list, but for structured
annotations, it first converts the data to the structured format. It
does not try to deallocate the previous contents of the data
field, so you are responsible for handling that. In summary, the
immeds and set_immeds methods allow you to access both
flat and structured annotation data as immed lists. The only
difference is that for structured annotations the immed lists are
not the actual annotation data, and consequently you may need to
deallocate the duplicate data structures.
Besides the conversion functions, the annotation manager records functions to deallocate and print the structured data. Both of these functions are optional. If the data fields for a particular kind of structured annotation contain pointers and you do not supply a function to deallocate the storage that they reference, it is your responsibility to ensure that that storage is deallocated elsewhere in your code. (For example, you may want to have the pointers all refer to entries in a table that is deallocated separately.)