Go to the previous, next section.

Structured Annotations

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.)

Go to the previous, next section.