gcc/doc/gty.texi

   1 @c Copyright (C) 2002
   2 @c Free Software Foundation, Inc.
   3 @c This is part of the GCC manual.
   4 @c For copying conditions, see the file gcc.texi.
   5
   6 @node Type Information
   7 @chapter Memory Management and Type Information
   8 @cindex GGC
   9 @findex GTY
  10
  11 GCC uses some fairly sophisticated memory management techniques, which
  12 involve determining information about GCC's data structures from GCC's
  13 source code and using this information to perform garbage collection.
  14
  15 A full C parser would be too overcomplicated for this task, so a limited
  16 subset of C is interpreted and special markers are used to determine
  17 what parts of the source to look at.  The parser can also detect
  18 simple typedefs of the form @code{typedef struct ID1 *ID2;} and
  19 @code{typedef int ID3;}, and these don't need to be specially marked.
  20
  21 The two forms that do need to be marked are:
  22 @verbatim
  23 struct ID1 GTY(([options]))
  24 {
  25   [fields]
  26 };
  27
  28 typedef struct ID2 GTY(([options]))
  29 {
  30   [fields]
  31 } ID3;
  32 @end verbatim
  33
  34 @menu
  35 * GTY Options::         What goes inside a @code{GTY(())}.
  36 * GGC Roots::           Making global variables GGC roots.
  37 * Files::               How the generated files work.
  38 @end menu
  39
  40 @node GTY Options
  41 @section The Inside of a @code{GTY(())}
  42
  43 Sometimes the C code is not enough to fully describe the type structure.
  44 Extra information can be provided by using more @code{GTY} markers.
  45 These markers can be placed:
  46 @itemize @bullet
  47 @item
  48 In a structure definition, before the open brace;
  49 @item
  50 In a global variable declaration, after the keyword @code{static} or
  51 @code{extern}; and
  52 @item
  53 In a structure field definition, before the name of the field.
  54 @end itemize
  55
  56 The format of a marker is
  57 @verbatim
  58 GTY (([name] ([param]), [name] ([param]) ...))
  59 @end verbatim
  60 The parameter is either a string or a type name.
  61
  62 When the parameter is a string, often it is a fragment of C code.  Three
  63 special escapes may be available:
  64
  65 @cindex % in GTY option
  66 @table @code
  67 @item %h
  68 This expands to an expression that evaluates to the current structure.
  69 @item %1
  70 This expands to an expression that evaluates to the structure that
  71 immediately contains the current structure.
  72 @item %0
  73 This expands to an expression that evaluates to the outermost structure
  74 that contains the current structure.
  75 @end table
  76
  77 The available options are:
  78
  79 @table @code
  80 @findex length
  81 @item length
  82
  83 There are two places the type machinery will need to be explicitly told
  84 the length of an array.  The first case is when a structure ends in a
  85 variable-length array, like this:
  86 @verbatim
  87 struct rtvec_def GTY(()) {
  88   int num_elem;         /* number of elements */
  89   rtx GTY ((length ("%h.num_elem"))) elem[1];
  90 };
  91 @end verbatim
  92 In this case, the @code{length} option is used to override the specified
  93 array length (which should usually be @code{1}).  The parameter of the
  94 option is a fragment of C code that calculates the length.
  95
  96 The second case is when a structure or a global variable contains a
  97 pointer to an array, like this:
  98 @verbatim
  99   tree * GTY ((length ("%h.regno_pointer_align_length"))) regno_decl;
 100 @end verbatim
 101 In this case, @code{regno_decl} has been allocated by writing something like
 102 @verbatim
 103   x->regno_decl = ggc_alloc (x->regno_pointer_align_length * sizeof (tree));
 104 @end verbatim
 105 and the @code{length} provides the length of the field.
 106
 107 This second use of @code{length} also works on global variables, like:
 108 @verbatim
 109 static GTY((length ("reg_base_value_size"))) rtx *reg_base_value;
 110 @end verbatim
 111
 112 @findex skip
 113 @item skip
 114
 115 If @code{skip} is applied to a field, the type machinery will ignore it.
 116 This is somewhat dangerous; the only safe use is in a union when one
 117 field really isn't ever used.
 118
 119 @findex desc
 120 @findex tag
 121 @findex always
 122 @item desc
 123 @itemx tag
 124 @itemx always
 125
 126 The type machinery needs to be told which field of a @code{union} is
 127 currently active.  This is done by giving each field a constant @code{tag}
 128 value, and then specifying a discriminator using @code{desc}.  For example,
 129 @verbatim
 130 struct tree_binding GTY(())
 131 {
 132   struct tree_common common;
 133   union tree_binding_u {
 134     tree GTY ((tag ("0"))) scope;
 135     struct cp_binding_level * GTY ((tag ("1"))) level;
 136   } GTY ((desc ("BINDING_HAS_LEVEL_P ((tree)&%0)"))) scope;
 137   tree value;
 138 };
 139 @end verbatim
 140
 141 In the @code{desc} option, the ``current structure'' is the union that
 142 it discriminates.  Use @code{%1} to mean the structure containing it.
 143 (There are no escapes available to the @code{tag} option, since it's
 144 supposed to be a constant.)
 145
 146 You can use @code{always} to mean that this field is always used.
 147
 148 @findex param_is
 149 @findex use_param
 150 @item param_is
 151 @itemx use_param
 152
 153 Sometimes it's convenient to define some data structure to work on
 154 generic pointers (that is, @code{PTR}), and then use it with specific types.
 155 @code{param_is} specifies the real type pointed to, and @code{use_param}
 156 says where in the generic data structure that type should be put.
 157
 158 For instance, to have a @code{htab_t} that points to trees, one should write
 159 @verbatim
 160   htab_t GTY ((param_is (union tree_node))) ict;
 161 @end verbatim
 162
 163 @findex deletable
 164 @item deletable
 165
 166 @code{deletable}, when applied to a global variable, indicates that when
 167 garbage collection runs, there's no need to mark anything pointed to
 168 by this variable, it can just be set to @code{NULL} instead.  This is used
 169 to keep a list of free structures around for re-use.
 170
 171 @findex if_marked
 172 @item if_marked
 173
 174 Suppose you want some kinds of object to be unique, and so you put them
 175 in a hash table.  If garbage collection marks the hash table, these
 176 objects will never be freed, even if the last other reference to them
 177 goes away.  GGC has special handling to deal with this: if you use the
 178 @code{if_marked} option on a global hash table, GGC will call the
 179 routine whose name is the parameter to the option on each hash table
 180 entry.  If the routine returns nonzero, the hash table entry will
 181 be marked as usual.  If the routine returns zero, the hash table entry
 182 will be deleted.
 183
 184 The routine @code{ggc_marked_p} can be used to determine if an element
 185 has been marked already; in fact, the usual case is to use
 186 @code{if_marked ("ggc_marked_p")}.
 187
 188 @findex maybe_undef
 189 @item maybe_undef
 190
 191 When applied to a field, @code{maybe_undef} indicates that it's OK if
 192 the structure that this fields points to is never defined, so long as
 193 this field is always @code{NULL}.  This is used to avoid requiring
 194 backends to define certain optional structures.  It doesn't work with
 195 language frontends.
 196
 197 @findex special
 198 @item special
 199
 200 The @code{special} option is used for those bizarre cases that are just
 201 too hard to deal with otherwise.  Don't use it for new code.
 202
 203 @end table
 204
 205 @node GGC Roots
 206 @section Marking Roots for the Garbage Collector
 207 @cindex roots, marking
 208 @cindex marking roots
 209
 210 In addition to keeping track of types, the type machinery also locates
 211 the global variables that the garbage collector starts at.  There are
 212 two syntaxes it accepts to indicate a root:
 213
 214 @enumerate
 215 @item
 216 @verb{|extern GTY (([options])) [type] ID;|}
 217 @item
 218 @verb{|static GTY (([options])) [type] ID;|}
 219 @end enumerate
 220
 221 @node Files
 222 @section Source Files Containing Type Information
 223 @cindex generated files
 224 @cindex files, generated
 225
 226 Whenever you add @code{GTY} markers to a new source file, there are three
 227 things you need to do:
 228
 229 @enumerate
 230 @item
 231 You need to add the file to the list of source files the type machinery
 232 scans.  For a back-end file, this is done automatically.  For a
 233 front-end file, this is done by adding the filename to the
 234 @code{gtfiles} variable defined in @file{config-lang.in}.  For other
 235 files, this is done by adding the filename to the @code{GTFILES} variable
 236 in @file{Makefile.in}.
 237
 238 @item
 239 You need to include the file that the type machinery will generate in
 240 the source file you just changed.  The file will be called
 241 @file{gt-@var{path}.h} where @var{path} is the pathname from the
 242 @file{gcc} directory with slashes replaced by @verb{|-|}.  Don't forget
 243 to mention this file as a dependency in the @file{Makefile}!
 244
 245 @item
 246 Finally, you need to add a @file{Makefile} rule that will ensure this file
 247 can be built.  This is done by making it a dependency of @code{s-gtype},
 248 like this:
 249 @verbatim
 250 gt-path.h : s-gtype ; @true
 251 @end verbatim
 252 @end enumerate
 253
 254 For language frontends, there is another file that needs to be included
 255 somewhere.  It will be called @file{gtype-@var{lang}.h}, where
 256 @var{lang} is the name of the subdirectory the language is contained in.
 257 It will need @file{Makefile} rules just like the other generated files.