@c Copyright (C) 2002, 2003, 2004, 2007, 2008@c Free Software Foundation, Inc.@c This is part of the GCC manual.@c For copying conditions, see the file gcc.texi.@node Type Information@chapter Memory Management and Type Information@cindex GGC@findex GTYGCC uses some fairly sophisticated memory management techniques, whichinvolve determining information about GCC's data structures from GCC'ssource code and using this information to perform garbage collection andimplement precompiled headers.A full C parser would be too complicated for this task, so a limitedsubset of C is interpreted and special markers are used to determinewhat parts of the source to look at.  All @code{struct} and@code{union} declarations that define data structures that areallocated under control of the garbage collector must be marked.  Allglobal variables that hold pointers to garbage-collected memory mustalso be marked.  Finally, all global variables that need to be savedand restored by a precompiled header must be marked.  (The precompiledheader mechanism can only save static variables if they're scalar.Complex data structures must be allocated in garbage-collected memoryto be saved in a precompiled header.)The full format of a marker is@smallexampleGTY (([@var{option}] [(@var{param})], [@var{option}] [(@var{param})] @dots{}))@end smallexample@noindentbut in most cases no options are needed.  The outer double parenthesesare still necessary, though: @code{GTY(())}.  Markers can appear:@itemize @bullet@itemIn a structure definition, before the open brace;@itemIn a global variable declaration, after the keyword @code{static} or@code{extern}; and@itemIn a structure field definition, before the name of the field.@end itemizeHere are some examples of marking simple data structures and globals.@smallexamplestruct @var{tag} GTY(())@{  @var{fields}@dots{}@};typedef struct @var{tag} GTY(())@{  @var{fields}@dots{}@} *@var{typename};static GTY(()) struct @var{tag} *@var{list};   /* @r{points to GC memory} */static GTY(()) int @var{counter};        /* @r{save counter in a PCH} */@end smallexampleThe parser understands simple typedefs such as@code{typedef struct @var{tag} *@var{name};} and@code{typedef int @var{name};}.These don't need to be marked.@menu* GTY Options::		What goes inside a @code{GTY(())}.* GGC Roots::		Making global variables GGC roots.* Files::		How the generated files work.@end menu@node GTY Options@section The Inside of a @code{GTY(())}Sometimes the C code is not enough to fully describe the typestructure.  Extra information can be provided with @code{GTY} optionsand additional markers.  Some options take a parameter, which may beeither a string or a type name, depending on the parameter.  If anoption takes no parameter, it is acceptable either to omit theparameter entirely, or to provide an empty string as a parameter.  Forexample, @code{@w{GTY ((skip))}} and @code{@w{GTY ((skip ("")))}} areequivalent.When the parameter is a string, often it is a fragment of C code.  Fourspecial escapes may be used in these strings, to refer to pieces ofthe data structure being marked:@cindex % in GTY option@table @code@item %hThe current structure.@item %1The structure that immediately contains the current structure.@item %0The outermost structure that contains the current structure.@item %aA partial expression of the form @code{[i1][i2]@dots{}} that indexesthe array item currently being marked.@end tableFor instance, suppose that you have a structure of the form@smallexamplestruct A @{  @dots{}@};struct B @{  struct A foo[12];@};@end smallexample@noindentand @code{b} is a variable of type @code{struct B}.  When marking@samp{b.foo[11]}, @code{%h} would expand to @samp{b.foo[11]},@code{%0} and @code{%1} would both expand to @samp{b}, and @code{%a}would expand to @samp{[11]}.As in ordinary C, adjacent strings will be concatenated; this ishelpful when you have a complicated expression.@smallexample@groupGTY ((chain_next ("TREE_CODE (&%h.generic) == INTEGER_TYPE"                  " ? TYPE_NEXT_VARIANT (&%h.generic)"                  " : TREE_CHAIN (&%h.generic)")))@end group@end smallexampleThe available options are:@table @code@findex length@item length ("@var{expression}")There are two places the type machinery will need to be explicitly toldthe length of an array.  The first case is when a structure ends in avariable-length array, like this:@smallexamplestruct rtvec_def GTY(()) @{  int num_elem;		/* @r{number of elements} */  rtx GTY ((length ("%h.num_elem"))) elem[1];@};@end smallexampleIn this case, the @code{length} option is used to override the specifiedarray length (which should usually be @code{1}).  The parameter of theoption is a fragment of C code that calculates the length.The second case is when a structure or a global variable contains apointer to an array, like this:@smallexampletree *  GTY ((length ("%h.regno_pointer_align_length"))) regno_decl;@end smallexampleIn this case, @code{regno_decl} has been allocated by writing something like@smallexample  x->regno_decl =    ggc_alloc (x->regno_pointer_align_length * sizeof (tree));@end smallexampleand the @code{length} provides the length of the field.This second use of @code{length} also works on global variables, like:@verbatim  static GTY((length ("reg_base_value_size")))    rtx *reg_base_value;@end verbatim@findex skip@item skipIf @code{skip} is applied to a field, the type machinery will ignore it.This is somewhat dangerous; the only safe use is in a union when onefield really isn't ever used.@findex desc@findex tag@findex default@item desc ("@var{expression}")@itemx tag ("@var{constant}")@itemx defaultThe type machinery needs to be told which field of a @code{union} iscurrently active.  This is done by giving each field a constant@code{tag} value, and then specifying a discriminator using @code{desc}.The value of the expression given by @code{desc} is compared againsteach @code{tag} value, each of which should be different.  If no@code{tag} is matched, the field marked with @code{default} is used ifthere is one, otherwise no field in the union will be marked.In the @code{desc} option, the ``current structure'' is the union thatit discriminates.  Use @code{%1} to mean the structure containing it.There are no escapes available to the @code{tag} option, since it is aconstant.For example,@smallexamplestruct tree_binding GTY(())@{  struct tree_common common;  union tree_binding_u @{    tree GTY ((tag ("0"))) scope;    struct cp_binding_level * GTY ((tag ("1"))) level;  @} GTY ((desc ("BINDING_HAS_LEVEL_P ((tree)&%0)"))) xscope;  tree value;@};@end smallexampleIn this example, the value of BINDING_HAS_LEVEL_P when applied to a@code{struct tree_binding *} is presumed to be 0 or 1.  If 1, the typemechanism will treat the field @code{level} as being present and if 0,will treat the field @code{scope} as being present.@findex param_is@findex use_param@item param_is (@var{type})@itemx use_paramSometimes it's convenient to define some data structure to work ongeneric pointers (that is, @code{PTR}) and then use it with a specifictype.  @code{param_is} specifies the real type pointed to, and@code{use_param} says where in the generic data structure that typeshould be put.For instance, to have a @code{htab_t} that points to trees, one wouldwrite the definition of @code{htab_t} like this:@smallexample