html/suif1_72.html

   1 <HTML>
   2 <HEAD>
   3 <!-- This HTML file has been created by texi2html 1.54
   4      from suif1.texi on 28 April 1999 -->
   5
   6 <TITLE>The SUIF Version 1 Library - Structured Annotes</TITLE>
   7 <link href="suif1_73.html" rel=Next>
   8 <link href="suif1_71.html" rel=Previous>
   9 <link href="suif1_toc.html" rel=ToC>
  10
  11 </HEAD>
  12 <BODY>
  13 <p>Go to the <A HREF="suif1_1.html">first</A>, <A HREF="suif1_71.html">previous</A>, <A HREF="suif1_73.html">next</A>, <A HREF="suif1_113.html">last</A> section, <A HREF="suif1_toc.html">table of contents</A>.
  14 <P><HR><P>
  15
  16
  17 <H2><A NAME="SEC72" HREF="suif1_toc.html#TOC72">Structured Annotations</A></H2>
  18 <P>
  19 <A NAME="IDX554"></A>
  20 <A NAME="IDX555"></A>
  21
  22 </P>
  23 <P>
  24 In many cases, flat annotations are cumbersome to use because the fields
  25 in the <CODE>immed</CODE> value list are unlabeled and difficult to access.
  26 With <STRONG>structured annotations</STRONG>, the data is held in a user-defined
  27 structure.  You can access this structured data by using the <CODE>data</CODE>
  28 method and casting the result to the desired type.  It may be helpful to
  29 define macros to perform the type casts.
  30
  31 </P>
  32 <P>
  33 An important restriction on structured annotations is that if they are
  34 to be stored in SUIF files, they are stored as <CODE>immed</CODE> lists.
  35 Therefore, if you wish to write such an annotation to a file, you must
  36 provide the annotation manager with functions to convert back and
  37 forth between the <CODE>immed</CODE> lists and the structured data.  When a
  38 structured annotation is first read from an input file, the annotation
  39 manager applies the function to convert the <CODE>immed</CODE> list to your
  40 data structure.  Similarly, when the annotation is written out, the
  41 manager applies the function to convert it back to a list of
  42 <CODE>immed</CODE> values.
  43
  44 </P>
  45 <P>
  46 The data in a structured annotation that defines a conversion function
  47 must always be maintained in a form that can be converted to an
  48 <CODE>immed</CODE> list.  This is necessary because the library occasionally
  49 needs to flatten annotations so that it can update the contents.  For
  50 example, when an annotation containing references to local symbols is
  51 moved to another scope, the symbols may need to be updated.  When this
  52 occurs, the library also converts the data back to its structured form
  53 after it has been updated.
  54
  55 </P>
  56 <P>
  57 Just as the library needs to temporarily flatten structured annotations,
  58 you may need to do the same.  The <CODE>immeds</CODE> and <CODE>set_immeds</CODE>
  59 methods make this task much easier.  The <CODE>immeds</CODE> method returns
  60 the annotation data represented as an <CODE>immed</CODE> list.  For a
  61 structured annotation, it does this by using the conversion function
  62 registered with the annotation manager to convert the structure to a
  63 flat list.  Note however that the result is a pointer to a new list,
  64 whereas for flat annotations, it is a pointer to the actual annotation
  65 data.  Similarly, the <CODE>set_immeds</CODE> method replaces the annotation
  66 data with the data in an <CODE>immed</CODE> list, but for structured
  67 annotations, it first converts the data to the structured format.  It
  68 does <EM>not</EM> try to deallocate the previous contents of the data
  69 field, so you are responsible for handling that.  In summary, the
  70 <CODE>immeds</CODE> and <CODE>set_immeds</CODE> methods allow you to access both
  71 flat and structured annotation data as <CODE>immed</CODE> lists.  The only
  72 difference is that for structured annotations the <CODE>immed</CODE> lists are
  73 not the actual annotation data, and consequently you may need to
  74 deallocate the duplicate data structures.
  75
  76 </P>
  77 <P>
  78 Besides the conversion functions, the annotation manager records
  79 functions to deallocate and print the structured data.  Both of these
  80 functions are optional.  If the data fields for a particular kind of
  81 structured annotation contain pointers and you do not supply a function
  82 to deallocate the storage that they reference, it is your responsibility
  83 to ensure that that storage is deallocated elsewhere in your code.  (For
  84 example, you may want to have the pointers all refer to entries in a
  85 table that is deallocated separately.)
  86
  87 </P>
  88
  89 <P><HR><P>
  90 <p>Go to the <A HREF="suif1_1.html">first</A>, <A HREF="suif1_71.html">previous</A>, <A HREF="suif1_73.html">next</A>, <A HREF="suif1_113.html">last</A> section, <A HREF="suif1_toc.html">table of contents</A>.
  91 </BODY>
  92 </HTML>