| @c Copyright (C) 2002, 2003, 2004 |
| @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 GTY |
| |
| GCC uses some fairly sophisticated memory management techniques, which |
| involve determining information about GCC's data structures from GCC's |
| source code and using this information to perform garbage collection and |
| implement precompiled headers. |
| |
| A full C parser would be too overcomplicated for this task, so a limited |
| subset of C is interpreted and special markers are used to determine |
| what parts of the source to look at. The parser can also detect |
| simple typedefs of the form @code{typedef struct ID1 *ID2;} and |
| @code{typedef int ID3;}, and these don't need to be specially marked. |
| |
| The two forms that do need to be marked are: |
| @verbatim |
| struct ID1 GTY(([options])) |
| { |
| [fields] |
| }; |
| |
| typedef struct ID2 GTY(([options])) |
| { |
| [fields] |
| } ID3; |
| @end verbatim |
| |
| @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 type structure. |
| Extra information can be provided by using more @code{GTY} markers. |
| These markers can be placed: |
| @itemize @bullet |
| @item |
| In a structure definition, before the open brace; |
| @item |
| In a global variable declaration, after the keyword @code{static} or |
| @code{extern}; and |
| @item |
| In a structure field definition, before the name of the field. |
| @end itemize |
| |
| The format of a marker is |
| @verbatim |
| GTY (([name] ([param]), [name] ([param]) ...)) |
| @end verbatim |
| The parameter is either a string or a type name. |
| |
| When the parameter is a string, often it is a fragment of C code. Three |
| special escapes may be available: |
| |
| @cindex % in GTY option |
| @table @code |
| @item %h |
| This expands to an expression that evaluates to the current structure. |
| @item %1 |
| This expands to an expression that evaluates to the structure that |
| immediately contains the current structure. |
| @item %0 |
| This expands to an expression that evaluates to the outermost structure |
| that contains the current structure. |
| @item %a |
| This expands to the string of the form @code{[i1][i2]...} that indexes |
| the array item currently being marked. For instance, if the field |
| being marked is @code{foo}, then @code{%1.foo%a} is the same as @code{%h}. |
| @end table |
| |
| The available options are: |
| |
| @table @code |
| @findex length |
| @item length |
| |
| There are two places the type machinery will need to be explicitly told |
| the length of an array. The first case is when a structure ends in a |
| variable-length array, like this: |
| @verbatim |
| struct rtvec_def GTY(()) { |
| int num_elem; /* number of elements */ |
| rtx GTY ((length ("%h.num_elem"))) elem[1]; |
| }; |
| @end verbatim |
| In this case, the @code{length} option is used to override the specified |
| array length (which should usually be @code{1}). The parameter of the |
| option is a fragment of C code that calculates the length. |
| |
| The second case is when a structure or a global variable contains a |
| pointer to an array, like this: |
| @smallexample |
| tree * |
| GTY ((length ("%h.regno_pointer_align_length"))) regno_decl; |
| @end smallexample |
| In 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 smallexample |
| and 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 skip |
| |
| If @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 one |
| field really isn't ever used. |
| |
| @findex desc |
| @findex tag |
| @findex default |
| @item desc |
| @itemx tag |
| @itemx default |
| |
| The type machinery needs to be told which field of a @code{union} is |
| currently 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 against |
| each @code{tag} value, each of which should be different. If no |
| @code{tag} is matched, the field marked with @code{default} is used if |
| there is one, otherwise no field in the union will be marked. |
| |
| In the @code{desc} option, the ``current structure'' is the union that |
| it discriminates. Use @code{%1} to mean the structure containing it. |
| (There are no escapes available to the @code{tag} option, since it's |
| supposed to be a constant.) |
| |
| For example, |
| @smallexample |
| struct 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 smallexample |
| |
| In 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 type |
| mechanism 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 |
| @itemx use_param |
| |
| Sometimes it's convenient to define some data structure to work on |
| generic pointers (that is, @code{PTR}) and then use it with a specific |
| type. @code{param_is} specifies the real type pointed to, and |
| @code{use_param} says where in the generic data structure that type |
| should be put. |
| |
| For instance, to have a @code{htab_t} that points to trees, one should write |
| @verbatim |
| htab_t GTY ((param_is (union tree_node))) ict; |
| @end verbatim |
| |
| @findex param@var{n}_is |
| @findex use_param@var{n} |
| @item param@var{n}_is |
| @itemx use_param@var{n} |
| |
| In more complicated cases, the data structure might need to work on |
| several different types, which might not necessarily all be pointers. |
| For this, @code{param1_is} through @code{param9_is} may be used to |
| specify the real type of a field identified by @code{use_param1} through |
| @code{use_param9}. |
| |
| @findex use_params |
| @item use_params |
| |
| When a structure contains another structure that is parameterized, |
| there's no need to do anything special, the inner structure inherits the |
| parameters of the outer one. When a structure contains a pointer to a |
| parameterized structure, the type machinery won't automatically detect |
| this (it could, it just doesn't yet), so it's necessary to tell it that |
| the pointed-to structure should use the same parameters as the outer |
| structure. 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 when |
| garbage collection runs, there's no need to mark anything pointed to |
| by this variable, it can just be set to @code{NULL} instead. This is used |
| to keep a list of free structures around for re-use. |
| |
| @findex if_marked |
| @item if_marked |
| |
| Suppose you want some kinds of object to be unique, and so you put them |
| in a hash table. If garbage collection marks the hash table, these |
| objects will never be freed, even if the last other reference to them |
| goes 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 the |
| routine whose name is the parameter to the option on each hash table |
| entry. If the routine returns nonzero, the hash table entry will |
| be marked as usual. If the routine returns zero, the hash table entry |
| will be deleted. |
| |
| The routine @code{ggc_marked_p} can be used to determine if an element |
| has been marked already; in fact, the usual case is to use |
| @code{if_marked ("ggc_marked_p")}. |
| |
| @findex maybe_undef |
| @item maybe_undef |
| |
| When applied to a field, @code{maybe_undef} indicates that it's OK if |
| the structure that this fields points to is never defined, so long as |
| this field is always @code{NULL}. This is used to avoid requiring |
| backends to define certain optional structures. It doesn't work with |
| language frontends. |
| |
| @findex chain_next |
| @findex chain_prev |
| @item chain_next |
| @itemx chain_prev |
| |
| It's helpful for the type machinery to know if objects are often |
| chained together in long lists; this lets it generate code that uses |
| less stack space by iterating along the list instead of recursing down |
| it. @code{chain_next} is an expression for the next item in the list, |
| @code{chain_prev} is an expression for the previous item. The |
| machinery requires that taking the next item of the previous item |
| gives the original item. |
| |
| @findex reorder |
| @item reorder |
| |
| Some data structures depend on the relative ordering of pointers. If |
| the type machinery needs to change that ordering, it will call the |
| function referenced by the @code{reorder} option, before changing the |
| pointers in the object that's pointed to by the field the option |
| applies to. The function must be of the type @code{void ()(void *, |
| void *, gt_pointer_operator, void *)}. The second parameter is the |
| pointed-to object; the third parameter is a routine that, given a |
| pointer, can update it to its new value. The fourth parameter is a |
| cookie to be passed to the third parameter. The first parameter is |
| the structure that contains the object, or the object itself if it is |
| a structure. |
| |
| No data structure may depend on the absolute value of pointers. Even |
| relying on relative orderings and using @code{reorder} functions can |
| be expensive. It is better to depend on properties of the data, like |
| an ID number or the hash of a string instead. |
| |
| @findex special |
| @item special |
| |
| The @code{special} option is used for those bizarre cases that are just |
| too hard to deal with otherwise. Don't use it for new code. |
| |
| @end table |
| |
| @node GGC Roots |
| @section Marking Roots for the Garbage Collector |
| @cindex roots, marking |
| @cindex marking roots |
| |
| In addition to keeping track of types, the type machinery also locates |
| the global variables that the garbage collector starts at. There are |
| two syntaxes it accepts to indicate a root: |
| |
| @enumerate |
| @item |
| @verb{|extern GTY (([options])) [type] ID;|} |
| @item |
| @verb{|static GTY (([options])) [type] ID;|} |
| @end enumerate |
| |
| These are the only syntaxes that are accepted. In particular, if you |
| want to mark a variable that is only declared as |
| @verbatim |
| int ID; |
| @end verbatim |
| or similar, you should either make it @code{static} or you should create |
| a @code{extern} declaration in a header file somewhere. |
| |
| @node Files |
| @section Source Files Containing Type Information |
| @cindex generated files |
| @cindex files, generated |
| |
| Whenever you add @code{GTY} markers to a new source file, there are three |
| things you need to do: |
| |
| @enumerate |
| @item |
| You need to add the file to the list of source files the type |
| machinery scans. There are three cases: |
| |
| @enumerate a |
| @item |
| For a back-end file, this is usually done |
| automatically; if not, you should add it to @code{target_gtfiles} in |
| the appropriate port's entries in @file{config.gcc}. |
| |
| @item |
| For files shared by all front ends, this is done by adding the |
| filename to the @code{GTFILES} variable in @file{Makefile.in}. |
| |
| @item |
| For any other file used by a front end, this is done by adding the |
| filename to the @code{gtfiles} variable defined in |
| @file{config-lang.in}. For C, the file is @file{c-config-lang.in}. |
| This list should include all files that have GTY macros in them that |
| are used in that front end, other than those defined in the previous |
| list items. For example, it is common for front end writers to use |
| @file{c-common.c} and other files from the C front end, and these |
| should be included in the @file{gtfiles} variable for such front ends. |
| |
| @end enumerate |
| |
| @item |
| If the file was a header file, you'll need to check that it's included |
| in the right place to be visible to the generated files. For a back-end |
| header file, this should be done automatically. For a front-end header |
| file, it needs to be included by the same file that includes |
| @file{gtype-@var{lang}.h}. For other header files, it needs to be |
| included 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 a |
| header 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 the |
| pathname relative to the @file{gcc} directory with slashes replaced by |
| @verb{|-|}, so for example the header file to be included in |
| @file{objc/objc-parse.c} is called @file{gt-objc-objc-parse.c}. The |
| generated header file should be included after everything else in the |
| source file. Don't forget to mention this file as a dependency in the |
| @file{Makefile}! |
| |
| @item |
| If a new @file{gt-@var{path}.h} file is needed, you need to arrange to |
| add a @file{Makefile} rule that will ensure this file can be built. |
| This is done by making it a dependency of @code{s-gtype}, like this: |
| @verbatim |
| gt-path.h : s-gtype ; @true |
| @end verbatim |
| @end enumerate |
| |
| For language frontends, there is another file that needs to be included |
| somewhere. It will be called @file{gtype-@var{lang}.h}, where |
| @var{lang} is the name of the subdirectory the language is contained in. |
| It will need @file{Makefile} rules just like the other generated files. |