html/suif1_57.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 - Sub-Variables</TITLE>
   7 <link href="suif1_58.html" rel=Next>
   8 <link href="suif1_56.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_56.html">previous</A>, <A HREF="suif1_58.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 <H3><A NAME="SEC57" HREF="suif1_toc.html#TOC57">Sub-Variables</A></H3>
  18 <P>
  19 <A NAME="IDX392"></A>
  20
  21 </P>
  22 <P>
  23 The data objects represented by variable symbols are allowed to
  24 overlap, but only in a carefully controlled way.  The mechanism that
  25 allows this is the existence of sub-variables.  One variable symbol is
  26 allowed to be a sub-variable of another, occupying a portion of the
  27 parent variable symbol specified by an offset and the types of the two
  28 variables.  This allows arbitrary hierarchies of variable symbols and
  29 the relations among them are known at all times.
  30
  31 </P>
  32 <P>
  33 For any hierarchy, there will always be one root ancestor in terms of
  34 which everything else can be specified.  If neither of two variables
  35 is a sub-variable of anything else, the two variables are guaranteed
  36 to be completely independent objects.
  37
  38 </P>
  39 <P>
  40 Use of sub-variables is optional.  Anything that can be represented
  41 with the sub-variable can be represented in terms of its parent by
  42 loading from the parent's address plus the offset and with the type of
  43 the child variable.
  44
  45 </P>
  46 <P>
  47 Sub-variable names are independent of their parent variable symbols.
  48 Whether or not they have the <CODE>userdef</CODE> flag set is also independent
  49 of the parent.  There is nothing inconsistent in having a parent which
  50 is user-defined and a sub-variable which is not (if some stage of the
  51 compiler decides a particular piece of a larger user-defined object has
  52 some special property and wants a handle on it), and neither is there
  53 anything inconsistent in a sub-variable that is user-defined in a parent
  54 which is not (user-defined variables that are equivalenced cause the
  55 system to create a new aggregate object).
  56
  57 </P>
  58 <P>
  59 Among the properties general to the <CODE>sym_node</CODE> class that may be
  60 changed by the user, the only one for which sub-variables have any
  61 special restriction is the symbol table in which they reside.
  62 A sub-variable should be in the same symbol table as its parent.  They
  63 may be temporarily in different symbol tables while being moved
  64 around, so the library doesn't enforce the restriction that they
  65 always be in the same symbol table at all times.  The library does
  66 enforce the restrictions that they must be in the same table when a
  67 symbol is first linked in as a sub-variable by the
  68 <CODE>var_sym::add_child</CODE> method and when the owning symbol table of
  69 the parent or child variable is written out.
  70
  71 </P>
  72 <P>
  73 <A NAME="IDX393"></A>
  74 Among properties specific to variable symbols that the user has
  75 control over, some may be set independently in sub-variables, and some
  76 are kept consistent between sub-variables and their parents.  For the
  77 properties that are kept consistent, the value of the property in the
  78 sub-variable is slaved to that in the parent.  In that case, either
  79 setting or getting the property from the sub-variable has exactly the
  80 same effect as getting or setting it from the parent variable.  If and
  81 when the sub-variable is removed from being a sub-variable by the
  82 <CODE>var_sym::remove_child</CODE> method, the current values of those
  83 properties in the sub-variable are set to the values of the parent at
  84 the time of separation and can be changed independently from then on.
  85
  86 </P>
  87 <P>
  88 <A NAME="IDX394"></A>
  89 <A NAME="IDX395"></A>
  90 Sub-variables are attached to parent variables by the <CODE>add_child</CODE>
  91 method.  The user tells the parent which variable symbol is to be the
  92 sub-variable and at what offset it begins and the library makes it a
  93 sub-variable.  If it is ever necessary to remove a sub-variable, the
  94 <CODE>remove_child</CODE> method may be used.  It undoes what
  95 <CODE>add_child</CODE> did making the sub-variable into a fully independent
  96 variable.  The argument of <CODE>remove_child</CODE> must already be a
  97 sub-variable of the given variable.  This method should be called
  98 before a sub-variable is deleted, or else there will be dangling
  99 pointers from the parent.
 100
 101 </P>
 102 <P>
 103 <A NAME="IDX396"></A>
 104 <A NAME="IDX397"></A>
 105 Two methods, <CODE>parent_var</CODE> and <CODE>offset</CODE>, provide a way to see
 106 whether a variable is a sub-variable, and if so what variable it is a
 107 sub-variable of and where it is in that variable.  If a variable is
 108 not a sub-variable, <CODE>parent_var</CODE> will return <CODE>NULL</CODE>.  If it
 109 is a sub-variable, this method will return the variable symbol for the
 110 variable of which it is a sub-variable.  If it is a sub-variable, the
 111 <CODE>offset</CODE> method will return the offset in bits of the beginning
 112 of the sub-variable from the beginning of the parent variable.  If
 113 called on a variable that is not a sub-variable, <CODE>offset</CODE> will
 114 return zero.
 115
 116 </P>
 117 <P>
 118 <A NAME="IDX398"></A>
 119 <A NAME="IDX399"></A>
 120 There are also methods provided to access all the variables that are
 121 sub-variables of a given variable.  The <CODE>num_children</CODE> method
 122 will return the number of sub-variables for a given variable symbol.
 123 Given a non-negative number less than the number of children, the
 124 <CODE>child_var</CODE> method will return one of the sub-variables.  The
 125 ordering of the sub-variables is the order in which they were added,
 126 starting with zero for the oldest remaining sub-variable.  For
 127 example, <CODE>child_var(2)</CODE> will return the sub-variable that was the
 128 third added of those that are still sub-variables.  Hence calling this
 129 method for each integer from zero through the number of children minus
 130 one will give all the sub-variables.  It is an error to call
 131 <CODE>child_var</CODE> with an argument greater than or equal to the number
 132 of sub-variables or less than zero.
 133
 134 </P>
 135 <P>
 136 <A NAME="IDX400"></A>
 137 <A NAME="IDX401"></A>
 138 <A NAME="IDX402"></A>
 139 Given a variable that may or may not be a sub-variable, the
 140 <CODE>root_ancestor</CODE> will return the unique ancestor of a sub-variable
 141 that is not itself a sub-variable, or the variable itself if it is not
 142 a sub-variable.  The <CODE>root_offset</CODE> method will return the offset
 143 of the variable within that root ancestor, which will be the sum of
 144 all the offsets along the path up.  The <CODE>overlaps</CODE> method is
 145 provided to determine whether any two variables overlap to any extent.
 146 If the result is <CODE>TRUE</CODE>, then they definitely overlap, at least
 147 in part; otherwise, the result is <CODE>FALSE</CODE>, and the variables do
 148 not overlap at all.
 149
 150 </P>
 151 <P>
 152 <A NAME="IDX403"></A>
 153 It is often useful to know whether a given portion of a variable
 154 treated as a given type has a corresponding sub-variable.  The
 155 <CODE>find_child</CODE> method will answer that question.  If such a
 156 sub-variable exists, it will return a pointer to it, otherwise it will
 157 return NULL.
 158
 159 </P>
 160 <P>
 161 <A NAME="IDX404"></A>
 162 As an alternative to attaching an existing variable symbol as a
 163 sub-variable to another variable, the <CODE>build_child</CODE> method is
 164 provided.  Given a location and type within a variable and a name, it
 165 creates an sub-variable, installs it in the proper symbol table if the
 166 parent variable was in a symbol table, and adds it as a sub-variable,
 167 all at once.
 168
 169 </P>
 170
 171 <P><HR><P>
 172 <p>Go to the <A HREF="suif1_1.html">first</A>, <A HREF="suif1_56.html">previous</A>, <A HREF="suif1_58.html">next</A>, <A HREF="suif1_113.html">last</A> section, <A HREF="suif1_toc.html">table of contents</A>.
 173 </BODY>
 174 </HTML>