X-Git-Url: http://git.sourceforge.jp/view?a=blobdiff_plain;f=gcc%2Fdoc%2Fgty.texi;h=56da9b55fc97cdf34a7c748d3f0e451bb8044228;hb=c3d15dba88361e996cde4beb76ef2e4f44e3fa7d;hp=05d9b9e6699df4fa9850b9a1704552d2b788031b;hpb=7035b2ab9789880dfe54b3d18299b944ef796df6;p=pf3gnuchains%2Fgcc-fork.git

diff --git a/gcc/doc/gty.texi b/gcc/doc/gty.texi
index 05d9b9e6699..56da9b55fc9 100644
--- a/gcc/doc/gty.texi
+++ b/gcc/doc/gty.texi
@@ -1,4 +1,4 @@
-@c Copyright (C) 2002, 2003, 2004
+@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.
@@ -46,12 +46,12 @@ In a structure field definition, before the name of the field.
 Here are some examples of marking simple data structures and globals.
 
 @smallexample
-struct @var{tag} GTY(())
+struct GTY(()) @var{tag}
 @{
   @var{fields}@dots{}
 @};
 
-typedef struct @var{tag} GTY(())
+typedef struct GTY(()) @var{tag}
 @{
   @var{fields}@dots{}
 @} *@var{typename};
@@ -61,14 +61,15 @@ 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 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.
+* 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
@@ -96,14 +97,14 @@ The structure that immediately contains the current structure.
 @item %0
 The outermost structure that contains the current structure.
 @item %a
-A partial expression of the form @code{[i1][i2]...} that indexes
+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];
@@ -135,8 +136,8 @@ 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:
 @smallexample
-struct rtvec_def GTY(()) @{
-  int num_elem;		/* @r{number of elements} */
+struct GTY(()) rtvec_def @{
+  int num_elem;         /* @r{number of elements} */
   rtx GTY ((length ("%h.num_elem"))) elem[1];
 @};
 @end smallexample
@@ -193,7 +194,7 @@ constant.
 
 For example,
 @smallexample
-struct tree_binding GTY(())
+struct GTY(()) tree_binding
 @{
   struct tree_common common;
   union tree_binding_u @{
@@ -231,7 +232,7 @@ typedef struct GTY(()) @{
 @end smallexample
 and then declare variables like this:
 @smallexample
-  htab_t GTY ((param_is (union tree_node))) ict;
+  static htab_t GTY ((param_is (union tree_node))) ict;
 @end smallexample
 
 @findex param@var{n}_is
@@ -282,6 +283,16 @@ 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 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
 
@@ -291,10 +302,25 @@ 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 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
+@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
@@ -303,7 +329,8 @@ it.  @code{chain_next} is an expression for the next item in the list,
 @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.
+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 ("@var{function name}")
@@ -390,6 +417,7 @@ For files shared by all front ends, add the filename to the
 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}.
+Headers should appear before non-headers in this list.
 
 @item
 For files that are part of some but not all front ends, add the
@@ -411,21 +439,39 @@ 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
+@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.