1 @c Copyright (C) 2002, 2003, 2004
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.
7 @chapter Memory Management and Type Information
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 and
14 implement precompiled headers.
16 A full C parser would be too overcomplicated for this task, so a limited
17 subset of C is interpreted and special markers are used to determine
18 what parts of the source to look at. The parser can also detect
19 simple typedefs of the form @code{typedef struct ID1 *ID2;} and
20 @code{typedef int ID3;}, and these don't need to be specially marked.
22 The two forms that do need to be marked are:
24 struct ID1 GTY(([options]))
29 typedef struct ID2 GTY(([options]))
36 * GTY Options:: What goes inside a @code{GTY(())}.
37 * GGC Roots:: Making global variables GGC roots.
38 * Files:: How the generated files work.
42 @section The Inside of a @code{GTY(())}
44 Sometimes the C code is not enough to fully describe the type structure.
45 Extra information can be provided by using more @code{GTY} markers.
46 These markers can be placed:
49 In a structure definition, before the open brace;
51 In a global variable declaration, after the keyword @code{static} or
54 In a structure field definition, before the name of the field.
57 The format of a marker is
59 GTY (([name] ([param]), [name] ([param]) ...))
61 The parameter is either a string or a type name.
63 When the parameter is a string, often it is a fragment of C code. Three
64 special escapes may be available:
66 @cindex % in GTY option
69 This expands to an expression that evaluates to the current structure.
71 This expands to an expression that evaluates to the structure that
72 immediately contains the current structure.
74 This expands to an expression that evaluates to the outermost structure
75 that contains the current structure.
77 This expands to the string of the form @code{[i1][i2]...} that indexes
78 the array item currently being marked. For instance, if the field
79 being marked is @code{foo}, then @code{%1.foo%a} is the same as @code{%h}.
82 The available options are:
88 There are two places the type machinery will need to be explicitly told
89 the length of an array. The first case is when a structure ends in a
90 variable-length array, like this:
92 struct rtvec_def GTY(()) {
93 int num_elem; /* number of elements */
94 rtx GTY ((length ("%h.num_elem"))) elem[1];
97 In this case, the @code{length} option is used to override the specified
98 array length (which should usually be @code{1}). The parameter of the
99 option is a fragment of C code that calculates the length.
101 The second case is when a structure or a global variable contains a
102 pointer to an array, like this:
105 GTY ((length ("%h.regno_pointer_align_length"))) regno_decl;
107 In this case, @code{regno_decl} has been allocated by writing something like
110 ggc_alloc (x->regno_pointer_align_length * sizeof (tree));
112 and the @code{length} provides the length of the field.
114 This second use of @code{length} also works on global variables, like:
116 static GTY((length ("reg_base_value_size")))
123 If @code{skip} is applied to a field, the type machinery will ignore it.
124 This is somewhat dangerous; the only safe use is in a union when one
125 field really isn't ever used.
134 The type machinery needs to be told which field of a @code{union} is
135 currently active. This is done by giving each field a constant
136 @code{tag} value, and then specifying a discriminator using @code{desc}.
137 The value of the expression given by @code{desc} is compared against
138 each @code{tag} value, each of which should be different. If no
139 @code{tag} is matched, the field marked with @code{default} is used if
140 there is one, otherwise no field in the union will be marked.
142 In the @code{desc} option, the ``current structure'' is the union that
143 it discriminates. Use @code{%1} to mean the structure containing it.
144 (There are no escapes available to the @code{tag} option, since it's
145 supposed to be a constant.)
149 struct tree_binding GTY(())
151 struct tree_common common;
152 union tree_binding_u @{
153 tree GTY ((tag ("0"))) scope;
154 struct cp_binding_level * GTY ((tag ("1"))) level;
155 @} GTY ((desc ("BINDING_HAS_LEVEL_P ((tree)&%0)"))) xscope;
160 In this example, the value of BINDING_HAS_LEVEL_P when applied to a
161 @code{struct tree_binding *} is presumed to be 0 or 1. If 1, the type
162 mechanism will treat the field @code{level} as being present and if 0,
163 will treat the field @code{scope} as being present.
170 Sometimes it's convenient to define some data structure to work on
171 generic pointers (that is, @code{PTR}) and then use it with a specific
172 type. @code{param_is} specifies the real type pointed to, and
173 @code{use_param} says where in the generic data structure that type
176 For instance, to have a @code{htab_t} that points to trees, one should write
178 htab_t GTY ((param_is (union tree_node))) ict;
181 @findex param@var{n}_is
182 @findex use_param@var{n}
183 @item param@var{n}_is
184 @itemx use_param@var{n}
186 In more complicated cases, the data structure might need to work on
187 several different types, which might not necessarily all be pointers.
188 For this, @code{param1_is} through @code{param9_is} may be used to
189 specify the real type of a field identified by @code{use_param1} through
195 When a structure contains another structure that is parameterized,
196 there's no need to do anything special, the inner structure inherits the
197 parameters of the outer one. When a structure contains a pointer to a
198 parameterized structure, the type machinery won't automatically detect
199 this (it could, it just doesn't yet), so it's necessary to tell it that
200 the pointed-to structure should use the same parameters as the outer
201 structure. This is done by marking the pointer with the
202 @code{use_params} option.
207 @code{deletable}, when applied to a global variable, indicates that when
208 garbage collection runs, there's no need to mark anything pointed to
209 by this variable, it can just be set to @code{NULL} instead. This is used
210 to keep a list of free structures around for re-use.
215 Suppose you want some kinds of object to be unique, and so you put them
216 in a hash table. If garbage collection marks the hash table, these
217 objects will never be freed, even if the last other reference to them
218 goes away. GGC has special handling to deal with this: if you use the
219 @code{if_marked} option on a global hash table, GGC will call the
220 routine whose name is the parameter to the option on each hash table
221 entry. If the routine returns nonzero, the hash table entry will
222 be marked as usual. If the routine returns zero, the hash table entry
225 The routine @code{ggc_marked_p} can be used to determine if an element
226 has been marked already; in fact, the usual case is to use
227 @code{if_marked ("ggc_marked_p")}.
232 When applied to a field, @code{maybe_undef} indicates that it's OK if
233 the structure that this fields points to is never defined, so long as
234 this field is always @code{NULL}. This is used to avoid requiring
235 backends to define certain optional structures. It doesn't work with
243 It's helpful for the type machinery to know if objects are often
244 chained together in long lists; this lets it generate code that uses
245 less stack space by iterating along the list instead of recursing down
246 it. @code{chain_next} is an expression for the next item in the list,
247 @code{chain_prev} is an expression for the previous item. The
248 machinery requires that taking the next item of the previous item
249 gives the original item.
254 Some data structures depend on the relative ordering of pointers. If
255 the type machinery needs to change that ordering, it will call the
256 function referenced by the @code{reorder} option, before changing the
257 pointers in the object that's pointed to by the field the option
258 applies to. The function must be of the type @code{void ()(void *,
259 void *, gt_pointer_operator, void *)}. The second parameter is the
260 pointed-to object; the third parameter is a routine that, given a
261 pointer, can update it to its new value. The fourth parameter is a
262 cookie to be passed to the third parameter. The first parameter is
263 the structure that contains the object, or the object itself if it is
266 No data structure may depend on the absolute value of pointers. Even
267 relying on relative orderings and using @code{reorder} functions can
268 be expensive. It is better to depend on properties of the data, like
269 an ID number or the hash of a string instead.
274 The @code{special} option is used for those bizarre cases that are just
275 too hard to deal with otherwise. Don't use it for new code.
280 @section Marking Roots for the Garbage Collector
281 @cindex roots, marking
282 @cindex marking roots
284 In addition to keeping track of types, the type machinery also locates
285 the global variables that the garbage collector starts at. There are
286 two syntaxes it accepts to indicate a root:
290 @verb{|extern GTY (([options])) [type] ID;|}
292 @verb{|static GTY (([options])) [type] ID;|}
295 These are the only syntaxes that are accepted. In particular, if you
296 want to mark a variable that is only declared as
300 or similar, you should either make it @code{static} or you should create
301 a @code{extern} declaration in a header file somewhere.
304 @section Source Files Containing Type Information
305 @cindex generated files
306 @cindex files, generated
308 Whenever you add @code{GTY} markers to a new source file, there are three
309 things you need to do:
313 You need to add the file to the list of source files the type
314 machinery scans. There are three cases:
318 For a back-end file, this is usually done
319 automatically; if not, you should add it to @code{target_gtfiles} in
320 the appropriate port's entries in @file{config.gcc}.
323 For files shared by all front ends, this is done by adding the
324 filename to the @code{GTFILES} variable in @file{Makefile.in}.
327 For any other file used by a front end, this is done by adding the
328 filename to the @code{gtfiles} variable defined in
329 @file{config-lang.in}. For C, the file is @file{c-config-lang.in}.
330 This list should include all files that have GTY macros in them that
331 are used in that front end, other than those defined in the previous
332 list items. For example, it is common for front end writers to use
333 @file{c-common.c} and other files from the C front end, and these
334 should be included in the @file{gtfiles} variable for such front ends.
339 If the file was a header file, you'll need to check that it's included
340 in the right place to be visible to the generated files. For a back-end
341 header file, this should be done automatically. For a front-end header
342 file, it needs to be included by the same file that includes
343 @file{gtype-@var{lang}.h}. For other header files, it needs to be
344 included in @file{gtype-desc.c}, which is a generated file, so add it to
345 @code{ifiles} in @code{open_base_file} in @file{gengtype.c}.
347 For source files that aren't header files, the machinery will generate a
348 header file that should be included in the source file you just changed.
349 The file will be called @file{gt-@var{path}.h} where @var{path} is the
350 pathname relative to the @file{gcc} directory with slashes replaced by
351 @verb{|-|}, so for example the header file to be included in
352 @file{objc/objc-parse.c} is called @file{gt-objc-objc-parse.c}. The
353 generated header file should be included after everything else in the
354 source file. Don't forget to mention this file as a dependency in the
358 If a new @file{gt-@var{path}.h} file is needed, you need to arrange to
359 add a @file{Makefile} rule that will ensure this file can be built.
360 This is done by making it a dependency of @code{s-gtype}, like this:
362 gt-path.h : s-gtype ; @true
366 For language frontends, there is another file that needs to be included
367 somewhere. It will be called @file{gtype-@var{lang}.h}, where
368 @var{lang} is the name of the subdirectory the language is contained in.
369 It will need @file{Makefile} rules just like the other generated files.