typedef struct GTY(()) @{  @dots{}  void ** GTY ((use_param, @dots{})) entries;  @dots{}@} htab_t;@end smallexampleand then declare variables like this:@smallexample  static htab_t GTY ((param_is (union tree_node))) ict;@end smallexample@findex param@var{n}_is@findex use_param@var{n}@item param@var{n}_is (@var{type})@itemx use_param@var{n}In more complicated cases, the data structure might need to work onseveral different types, which might not necessarily all be pointers.For this, @code{param1_is} through @code{param9_is} may be used tospecify the real type of a field identified by @code{use_param1} through@code{use_param9}.@findex use_params@item use_paramsWhen a structure contains another structure that is parameterized,there's no need to do anything special, the inner structure inherits theparameters of the outer one.  When a structure contains a pointer to aparameterized structure, the type machinery won't automatically detectthis (it could, it just doesn't yet), so it's necessary to tell it thatthe pointed-to structure should use the same parameters as the outerstructure.  This is done by marking the pointer with the@code{use_params} option.@findex deletable@item deletable@code{deletable}, when applied to a global variable, indicates that whengarbage collection runs, there's no need to mark anything pointed toby this variable, it can just be set to @code{NULL} instead.  This is usedto keep a list of free structures around for re-use.@findex if_marked@item if_marked ("@var{expression}")Suppose you want some kinds of object to be unique, and so you put themin a hash table.  If garbage collection marks the hash table, theseobjects will never be freed, even if the last other reference to themgoes away.  GGC has special handling to deal with this: if you use the@code{if_marked} option on a global hash table, GGC will call theroutine whose name is the parameter to the option on each hash tableentry.  If the routine returns nonzero, the hash table entry willbe marked as usual.  If the routine returns zero, the hash table entrywill be deleted.The routine @code{ggc_marked_p} can be used to determine if an elementhas been marked already; in fact, the usual case is to use@code{if_marked ("ggc_marked_p")}.@findex mark_hook@item mark_hook ("@var{hook-routine-name}")If provided for a structure or union type, the given@var{hook-routine-name} (between double-quotes) is the name of aroutine called when the garbage collector has just marked the data asreachable. This routine should not change the data, or call any ggcroutine. Its only argument is a pointer to the just marked (const)structure or union.@findex maybe_undef@item maybe_undefWhen applied to a field, @code{maybe_undef} indicates that it's OK ifthe structure that this fields points to is never defined, so long asthis field is always @code{NULL}.  This is used to avoid requiringbackends to define certain optional structures.  It doesn't work withlanguage frontends.@findex nested_ptr@item nested_ptr (@var{type}, "@var{to expression}", "@var{from expression}")The type machinery expects all pointers to point to the start of anobject.  Sometimes for abstraction purposes it's convenient to havea pointer which points inside an object.  So long as it's possible toconvert the original object to and from the pointer, such pointerscan still be used.  @var{type} is the type of the original object,the @var{to expression} returns the pointer given the original object,and the @var{from expression} returns the original object giventhe pointer.  The pointer will be available using the @code{%h}escape.@findex chain_next@findex chain_prev@findex chain_circular@item chain_next ("@var{expression}")@itemx chain_prev ("@var{expression}")@itemx chain_circular ("@var{expression}")It's helpful for the type machinery to know if objects are oftenchained together in long lists; this lets it generate code that usesless stack space by iterating along the list instead of recursing downit.  @code{chain_next} is an expression for the next item in the list,@code{chain_prev} is an expression for the previous item.  For singlylinked lists, use only @code{chain_next}; for doubly linked lists, useboth.  The machinery requires that taking the next item of theprevious item gives the original item.  @code{chain_circular} is similarto @code{chain_next}, but can be used for circular single linked lists.@findex reorder@item reorder ("@var{function name}")Some data structures depend on the relative ordering of pointers.  Ifthe precompiled header machinery needs to change that ordering, itwill call the function referenced by the @code{reorder} option, beforechanging the pointers in the object that's pointed to by the field theoption applies to.  The function must take four arguments, with thesignature @samp{@w{void *, void *, gt_pointer_operator, void *}}.The first parameter is a pointer to the structure that contains theobject being updated, or the object itself if there is no containingstructure.  The second parameter is a cookie that should be ignored.The third parameter is a routine that, given a pointer, will update itto its correct new value.  The fourth parameter is a cookie that mustbe passed to the second parameter.PCH cannot handle data structures that depend on the absolute valuesof pointers.  @code{reorder} functions can be expensive.  Whenpossible, it is better to depend on properties of the data, like an IDnumber or the hash of a string instead.@findex special@item special ("@var{name}")The @code{special} option is used to mark types that have to be dealtwith by special case machinery.  The parameter is the name of thespecial case.  See @file{gengtype.c} for further details.  Avoidadding new special cases unless there is no other alternative.@end table@node GGC Roots@section Marking Roots for the Garbage Collector@cindex roots, marking@cindex marking rootsIn addition to keeping track of types, the type machinery also locatesthe global variables (@dfn{roots}) that the garbage collector startsat.  Roots must be declared using one of the following syntaxes:@itemize @bullet@item@code{extern GTY(([@var{options}])) @var{type} @var{name};}@item@code{static GTY(([@var{options}])) @var{type} @var{name};}@end itemize@noindentThe syntax@itemize @bullet@item@code{GTY(([@var{options}])) @var{type} @var{name};}@end itemize@noindentis @emph{not} accepted.  There should be an @code{extern} declarationof such a variable in a header somewhere---mark that, not thedefinition.  Or, if the variable is only used in one file, make it@code{static}.@node Files@section Source Files Containing Type Information@cindex generated files@cindex files, generatedWhenever you add @code{GTY} markers to a source file that previouslyhad none, or create a new source file containing @code{GTY} markers,there are three things you need to do:@enumerate@itemYou need to add the file to the list of source files the typemachinery scans.  There are four cases:@enumerate a@itemFor a back-end file, this is usually doneautomatically; if not, you should add it to @code{target_gtfiles} inthe appropriate port's entries in @file{config.gcc}.@itemFor files shared by all front ends, add the filename to the@code{GTFILES} variable in @file{Makefile.in}.@itemFor files that are part of one front end, add the filename to the@code{gtfiles} variable defined in the appropriate@file{config-lang.in}.  For C, the file is @file{c-config-lang.in}.@itemFor files that are part of some but not all front ends, add thefilename to the @code{gtfiles} variable of @emph{all} the front endsthat use it.@end enumerate@itemIf the file was a header file, you'll need to check that it's includedin the right place to be visible to the generated files.  For a back-endheader file, this should be done automatically.  For a front-end headerfile, it needs to be included by the same file that includes@file{gtype-@var{lang}.h}.  For other header files, it needs to beincluded in @file{gtype-desc.c}, which is a generated file, so add it to@code{ifiles} in @code{open_base_file} in @file{gengtype.c}.For source files that aren't header files, the machinery will generate aheader file that should be included in the source file you just changed.The file will be called @file{gt-@var{path}.h} where @var{path} is thepathname relative to the @file{gcc} directory with slashes replaced by@verb{|-|}, so for example the header file to be included in@file{cp/parser.c} is called @file{gt-cp-parser.c}.  Thegenerated header file should be included after everything else in thesource file.  Don't forget to mention this file as a dependency in the@file{Makefile}!@end enumerateFor language frontends, there is another file that needs to be includedsomewhere.  It will be called @file{gtype-@var{lang}.h}, where@var{lang} is the name of the subdirectory the language is contained in.