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.
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.
21 The two forms that do need to be marked are:
23 struct ID1 GTY(([options]))
28 typedef struct ID2 GTY(([options]))
35 * GTY Options:: What goes inside a @code{GTY(())}.
36 * GGC Roots:: Making global variables GGC roots.
37 * Files:: How the generated files work.
41 @section The Inside of a @code{GTY(())}
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:
48 In a structure definition, before the open brace;
50 In a global variable declaration, after the keyword @code{static} or
53 In a structure field definition, before the name of the field.
56 The format of a marker is
58 GTY (([name] ([param]), [name] ([param]) ...))
60 The parameter is either a string or a type name.
62 When the parameter is a string, often it is a fragment of C code. Three
63 special escapes may be available:
65 @cindex % in GTY option
68 This expands to an expression that evaluates to the current structure.
70 This expands to an expression that evaluates to the structure that
71 immediately contains the current structure.
73 This expands to an expression that evaluates to the outermost structure
74 that contains the current structure.
76 This expands to the string of the form @code{[i1][i2]...} that indexes
77 the array item currently being marked. For instance, if the field
78 being marked is @code{foo}, then @code{%1.foo%a} is the same as @code{%h}.
81 The available options are:
87 There are two places the type machinery will need to be explicitly told
88 the length of an array. The first case is when a structure ends in a
89 variable-length array, like this:
91 struct rtvec_def GTY(()) {
92 int num_elem; /* number of elements */
93 rtx GTY ((length ("%h.num_elem"))) elem[1];
96 In this case, the @code{length} option is used to override the specified
97 array length (which should usually be @code{1}). The parameter of the
98 option is a fragment of C code that calculates the length.
100 The second case is when a structure or a global variable contains a
101 pointer to an array, like this:
104 GTY ((length ("%h.regno_pointer_align_length"))) regno_decl;
106 In this case, @code{regno_decl} has been allocated by writing something like
109 ggc_alloc (x->regno_pointer_align_length * sizeof (tree));
111 and the @code{length} provides the length of the field.
113 This second use of @code{length} also works on global variables, like:
115 static GTY((length ("reg_base_value_size")))
122 If @code{skip} is applied to a field, the type machinery will ignore it.
123 This is somewhat dangerous; the only safe use is in a union when one
124 field really isn't ever used.
133 The type machinery needs to be told which field of a @code{union} is
134 currently active. This is done by giving each field a constant @code{tag}
135 value, and then specifying a discriminator using @code{desc}. For example,
137 struct tree_binding GTY(())
139 struct tree_common common;
140 union tree_binding_u @{
141 tree GTY ((tag ("0"))) scope;
142 struct cp_binding_level * GTY ((tag ("1"))) level;
143 @} GTY ((desc ("BINDING_HAS_LEVEL_P ((tree)&%0)"))) scope;
148 In the @code{desc} option, the ``current structure'' is the union that
149 it discriminates. Use @code{%1} to mean the structure containing it.
150 (There are no escapes available to the @code{tag} option, since it's
151 supposed to be a constant.)
153 Each @code{tag} should be different. If no @code{tag} is matched,
154 the field marked with @code{default} is used if there is one, otherwise
155 no field in the union will be marked.
162 Sometimes it's convenient to define some data structure to work on
163 generic pointers (that is, @code{PTR}) and then use it with a specific
164 type. @code{param_is} specifies the real type pointed to, and
165 @code{use_param} says where in the generic data structure that type
168 For instance, to have a @code{htab_t} that points to trees, one should write
170 htab_t GTY ((param_is (union tree_node))) ict;
173 @findex param@var{n}_is
174 @findex use_param@var{n}
175 @item param@var{n}_is
176 @itemx use_param@var{n}
178 In more complicated cases, the data structure might need to work on
179 several different types, which might not necessarily all be pointers.
180 For this, @code{param1_is} through @code{param9_is} may be used to
181 specify the real type of a field identified by @code{use_param1} through
187 When a structure contains another structure that is parameterized,
188 there's no need to do anything special, the inner stucture inherits the
189 parameters of the outer one. When a structure contains a pointer to a
190 parameterized structure, the type machinery won't automatically detect
191 this (it could, it just doesn't yet), so it's necessary to tell it that
192 the pointed-to structure should use the same parameters as the outer
193 structure. This is done by marking the pointer with the
194 @code{use_params} option.
199 @code{deletable}, when applied to a global variable, indicates that when
200 garbage collection runs, there's no need to mark anything pointed to
201 by this variable, it can just be set to @code{NULL} instead. This is used
202 to keep a list of free structures around for re-use.
207 Suppose you want some kinds of object to be unique, and so you put them
208 in a hash table. If garbage collection marks the hash table, these
209 objects will never be freed, even if the last other reference to them
210 goes away. GGC has special handling to deal with this: if you use the
211 @code{if_marked} option on a global hash table, GGC will call the
212 routine whose name is the parameter to the option on each hash table
213 entry. If the routine returns nonzero, the hash table entry will
214 be marked as usual. If the routine returns zero, the hash table entry
217 The routine @code{ggc_marked_p} can be used to determine if an element
218 has been marked already; in fact, the usual case is to use
219 @code{if_marked ("ggc_marked_p")}.
224 When applied to a field, @code{maybe_undef} indicates that it's OK if
225 the structure that this fields points to is never defined, so long as
226 this field is always @code{NULL}. This is used to avoid requiring
227 backends to define certain optional structures. It doesn't work with
233 The @code{special} option is used for those bizarre cases that are just
234 too hard to deal with otherwise. Don't use it for new code.
239 @section Marking Roots for the Garbage Collector
240 @cindex roots, marking
241 @cindex marking roots
243 In addition to keeping track of types, the type machinery also locates
244 the global variables that the garbage collector starts at. There are
245 two syntaxes it accepts to indicate a root:
249 @verb{|extern GTY (([options])) [type] ID;|}
251 @verb{|static GTY (([options])) [type] ID;|}
254 These are the only syntaxes that are accepted. In particular, if you
255 want to mark a variable that is only declared as
259 or similar, you should either make it @code{static} or you should create
260 a @code{extern} declaration in a header file somewhere.
263 @section Source Files Containing Type Information
264 @cindex generated files
265 @cindex files, generated
267 Whenever you add @code{GTY} markers to a new source file, there are three
268 things you need to do:
272 You need to add the file to the list of source files the type
273 machinery scans. There are three cases:
277 For a back-end file, this is usually done
278 automatically; if not, you should add it to @code{target_gtfiles} in
279 the appropriate port's entries in @file{config.gcc}.
282 For files shared by all front ends, this is done by adding the
283 filename to the @code{GTFILES} variable in @file{Makefile.in}.
286 For any other file used by a front end, this is done by adding the
287 filename to the @code{gtfiles} variable defined in
288 @file{config-lang.in}. For C, the file is @file{c-config-lang.in}.
289 This list should include all files that have GTY macros in them that
290 are used in that front end, other than those defined in the previous
291 list items. For example, it is common for front end writers to use
292 @file{c-common.c} and other files from the C front end, and these
293 should be included in the @file{gtfiles} variable for such front ends.
298 If the file was a header file, you'll need to check that it's included
299 in the right place to be visible to the generated files. For a back-end
300 header file, this should be done automatically. For a front-end header
301 file, it needs to be included by the same file that includes
302 @file{gtype-@var{lang}.h}. For other header files, it needs to be
303 included in @file{gtype-desc.c}, which is a generated file, so add it to
304 @code{ifiles} in @code{open_base_file} in @file{gengtype.c}.
306 For source files that aren't header files, the machinery will generate a
307 header file that should be included in the source file you just changed.
308 The file will be called @file{gt-@var{path}.h} where @var{path} is the
309 pathname relative to the @file{gcc} directory with slashes replaced by
310 @verb{|-|}, so for example the header file to be included in
311 @file{objc/objc-parse.c} is called @file{gt-objc-objc-parse.c}. The
312 generated header file should be included after everything else in the
313 source file. Don't forget to mention this file as a dependency in the
317 If a new @file{gt-@var{path}.h} file is needed, you need to arrange to
318 add a @file{Makefile} rule that will ensure this file can be built.
319 This is done by making it a dependency of @code{s-gtype}, like this:
321 gt-path.h : s-gtype ; @true
325 For language frontends, there is another file that needs to be included
326 somewhere. It will be called @file{gtype-@var{lang}.h}, where
327 @var{lang} is the name of the subdirectory the language is contained in.
328 It will need @file{Makefile} rules just like the other generated files.