-@c Copyright (C) 2002
+@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.
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.
+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
@item
In a structure definition, before the open brace;
@item
-In a global variable declaration, after the keyword @code{static} or
+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.
@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:
The second case is when a structure or a global variable contains a
pointer to an array, like this:
-@verbatim
- tree * GTY ((length ("%h.regno_pointer_align_length"))) regno_decl;
-@end verbatim
+@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
-@verbatim
- x->regno_decl = ggc_alloc (x->regno_pointer_align_length * sizeof (tree));
-@end verbatim
+@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;
+ static GTY((length ("reg_base_value_size")))
+ rtx *reg_base_value;
@end verbatim
@findex skip
@findex desc
@findex tag
-@findex always
+@findex default
@item desc
@itemx tag
-@itemx always
+@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}. For example,
-@verbatim
-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)"))) scope;
- tree value;
-};
-@end verbatim
+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.)
-You can use @code{always} to mean that this field is always used.
+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
@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 specific types.
-@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.
+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
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
@enumerate
@item
You need to add the file to the list of source files the type
-machinery scans. There are three cases:
+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}.
+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
+@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}.
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}.
+@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.
OSDN Git Service
