-@c Copyright (C) 2002, 2003, 2004, 2007, 2008
+@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.
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};
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
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
For example,
@smallexample
-struct tree_binding GTY(())
+struct GTY(()) tree_binding
@{
struct tree_common common;
union tree_binding_u @{
@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
@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}")
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
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.
+
+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.