-@c Copyright (C) 2002, 2003
+@c Copyright (C) 2002, 2003, 2004, 2007, 2008, 2009
@c Free Software Foundation, Inc.
@c This is part of the GCC manual.
@c For copying conditions, see the file gcc.texi.
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
+A full C parser would be too complicated 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(())}
+what parts of the source to look at. All @code{struct} and
+@code{union} declarations that define data structures that are
+allocated under control of the garbage collector must be marked. All
+global variables that hold pointers to garbage-collected memory must
+also be marked. Finally, all global variables that need to be saved
+and restored by a precompiled header must be marked. (The precompiled
+header mechanism can only save static variables if they're scalar.
+Complex data structures must be allocated in garbage-collected memory
+to be saved in a precompiled header.)
+
+The full format of a marker is
+@smallexample
+GTY (([@var{option}] [(@var{param})], [@var{option}] [(@var{param})] @dots{}))
+@end smallexample
+@noindent
+but in most cases no options are needed. The outer double parentheses
+are still necessary, though: @code{GTY(())}. Markers can appear:
-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;
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.
+Here are some examples of marking simple data structures and globals.
+
+@smallexample
+struct GTY(()) @var{tag}
+@{
+ @var{fields}@dots{}
+@};
-When the parameter is a string, often it is a fragment of C code. Three
-special escapes may be available:
+typedef struct GTY(()) @var{tag}
+@{
+ @var{fields}@dots{}
+@} *@var{typename};
+
+static GTY(()) struct @var{tag} *@var{list}; /* @r{points to GC memory} */
+static GTY(()) int @var{counter}; /* @r{save counter in a PCH} */
+@end smallexample
+
+The parser understands simple typedefs such as
+@code{typedef struct @var{tag} *@var{name};} and
+@code{typedef int @var{name};}.
+These don't need to be marked.
+
+@menu
+* GTY Options:: What goes inside a @code{GTY(())}.
+* GGC Roots:: Making global variables GGC roots.
+* Files:: How the generated files work.
+* Invoking the garbage collector:: How to invoke the garbage collector.
+@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 with @code{GTY} options
+and additional markers. Some options take a parameter, which may be
+either a string or a type name, depending on the parameter. If an
+option takes no parameter, it is acceptable either to omit the
+parameter entirely, or to provide an empty string as a parameter. For
+example, @code{@w{GTY ((skip))}} and @code{@w{GTY ((skip ("")))}} are
+equivalent.
+
+When the parameter is a string, often it is a fragment of C code. Four
+special escapes may be used in these strings, to refer to pieces of
+the data structure being marked:
@cindex % in GTY option
@table @code
@item %h
-This expands to an expression that evaluates to the current structure.
+The current structure.
@item %1
-This expands to an expression that evaluates to the structure that
-immediately contains the current structure.
+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.
+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}.
+A partial expression of the form @code{[i1][i2]@dots{}} that indexes
+the array item currently being marked.
@end table
+For instance, suppose that you have a structure of the form
+@smallexample
+struct A @{
+ @dots{}
+@};
+struct B @{
+ struct A foo[12];
+@};
+@end smallexample
+@noindent
+and @code{b} is a variable of type @code{struct B}. When marking
+@samp{b.foo[11]}, @code{%h} would expand to @samp{b.foo[11]},
+@code{%0} and @code{%1} would both expand to @samp{b}, and @code{%a}
+would expand to @samp{[11]}.
+
+As in ordinary C, adjacent strings will be concatenated; this is
+helpful when you have a complicated expression.
+@smallexample
+@group
+GTY ((chain_next ("TREE_CODE (&%h.generic) == INTEGER_TYPE"
+ " ? TYPE_NEXT_VARIANT (&%h.generic)"
+ " : TREE_CHAIN (&%h.generic)")))
+@end group
+@end smallexample
+
The available options are:
@table @code
@findex length
-@item length
+@item length ("@var{expression}")
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 */
+@smallexample
+struct GTY(()) rtvec_def @{
+ int num_elem; /* @r{number of elements} */
rtx GTY ((length ("%h.num_elem"))) elem[1];
-};
-@end verbatim
+@};
+@end smallexample
+
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.
@findex desc
@findex tag
@findex default
-@item desc
-@itemx tag
+@item desc ("@var{expression}")
+@itemx tag ("@var{constant}")
@itemx default
The type machinery needs to be told which field of a @code{union} is
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.)
+There are no escapes available to the @code{tag} option, since it is a
+constant.
For example,
@smallexample
-struct tree_binding GTY(())
+struct GTY(()) tree_binding
@{
struct tree_common common;
union tree_binding_u @{
@findex param_is
@findex use_param
-@item param_is
+@item param_is (@var{type})
@itemx use_param
Sometimes it's convenient to define some data structure to work on
@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
+For instance, to have a @code{htab_t} that points to trees, one would
+write the definition of @code{htab_t} like this:
+@smallexample
+typedef struct GTY(()) @{
+ @dots{}
+ void ** GTY ((use_param, @dots{})) entries;
+ @dots{}
+@} htab_t;
+@end smallexample
+and 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
+@item param@var{n}_is (@var{type})
@itemx use_param@var{n}
In more complicated cases, the data structure might need to work on
to keep a list of free structures around for re-use.
@findex if_marked
-@item if_marked
+@item if_marked ("@var{expression}")
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
has 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 a
+routine called when the garbage collector has just marked the data as
+reachable. This routine should not change the data, or call any ggc
+routine. Its only argument is a pointer to the just marked (const)
+structure or union.
+
@findex maybe_undef
@item maybe_undef
backends to define certain optional structures. It doesn't work with
language 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 an
+object. Sometimes for abstraction purposes it's convenient to have
+a pointer which points inside an object. So long as it's possible to
+convert the original object to and from the pointer, such pointers
+can 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 given
+the pointer. The pointer will be available using the @code{%h}
+escape.
+
@findex chain_next
@findex chain_prev
-@item chain_next
-@itemx 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 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.
+@code{chain_prev} is an expression for the previous item. For singly
+linked lists, use only @code{chain_next}; for doubly linked lists, use
+both. The machinery requires that taking the next item of the
+previous item gives the original item. @code{chain_circular} is similar
+to @code{chain_next}, but can be used for circular single linked lists.
@findex reorder
-@item reorder
+@item reorder ("@var{function name}")
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.
+the precompiled header 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 take four arguments, with the
+signature @samp{@w{void *, void *, gt_pointer_operator, void *}}.
+The first parameter is a pointer to the structure that contains the
+object being updated, or the object itself if there is no containing
+structure. The second parameter is a cookie that should be ignored.
+The third parameter is a routine that, given a pointer, will update it
+to its correct new value. The fourth parameter is a cookie that must
+be passed to the second parameter.
+
+PCH cannot handle data structures that depend on the absolute values
+of pointers. @code{reorder} functions can be expensive. When
+possible, 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.
+@item special ("@var{name}")
+The @code{special} option is used to mark types that have to be dealt
+with by special case machinery. The parameter is the name of the
+special case. See @file{gengtype.c} for further details. Avoid
+adding new special cases unless there is no other alternative.
@end table
@node GGC Roots
@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:
+the global variables (@dfn{roots}) that the garbage collector starts
+at. Roots must be declared using one of the following syntaxes:
-@enumerate
+@itemize @bullet
@item
-@verb{|extern GTY (([options])) [type] ID;|}
+@code{extern GTY(([@var{options}])) @var{type} @var{name};}
@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.
+@code{static GTY(([@var{options}])) @var{type} @var{name};}
+@end itemize
+@noindent
+The syntax
+@itemize @bullet
+@item
+@code{GTY(([@var{options}])) @var{type} @var{name};}
+@end itemize
+@noindent
+is @emph{not} accepted. There should be an @code{extern} declaration
+of such a variable in a header somewhere---mark that, not the
+definition. 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, generated
-Whenever you add @code{GTY} markers to a new source file, there are three
-things you need to do:
+Whenever you add @code{GTY} markers to a source file that previously
+had none, or create a new source file containing @code{GTY} markers,
+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:
+machinery scans. There are four cases:
@enumerate a
@item
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}.
+For files shared by all front ends, add 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
+For 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}.
-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.
+Headers should appear before non-headers in this list.
+@item
+For files that are part of some but not all front ends, add the
+filename to the @code{gtfiles} variable of @emph{all} the front ends
+that use it.
@end enumerate
@item
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
+@file{cp/parser.c} is called @file{gt-cp-parser.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.
+
+Plugins can add additional root tables. Run the @code{gengtype}
+utility in plugin mode as @code{gengtype -P pluginout.h @var{source-dir}
+@var{file-list} @var{plugin*.c}} with your plugin files
+@var{plugin*.c} using @code{GTY} to generate the @var{pluginout.h} file.
+The GCC build tree is needed to be present in that mode.
+
+
+@node Invoking the garbage collector
+@section How to invoke the garbage collector
+@cindex garbage collector, invocation
+@findex ggc_collect
+
+The GCC garbage collector GGC is only invoked explicitly. In contrast
+with many other garbage collectors, it is not implicitly invoked by
+allocation routines when a lot of memory has been consumed. So the
+only way to have GGC reclaim storage it to call the @code{ggc_collect}
+function explicitly. This call is an expensive operation, as it may
+have to scan the entire heap. Beware that local variables (on the GCC
+call stack) are not followed by such an invocation (as many other
+garbage collectors do): you should reference all your data from static
+or external @code{GTY}-ed variables, and it is advised to call
+@code{ggc_collect} with a shallow call stack. The GGC is an exact mark
+and sweep garbage collector (so it does not scan the call stack for
+pointers). In practice GCC passes don't often call @code{ggc_collect}
+themselves, because it is called by the pass manager between passes.
OSDN Git Service
