gty.texi (Invoking the garbage collector): Added new node and section documenting...

2009-01-14  Basile Starynkevitch  <basile@starynkevitch.net>
	* doc/gty.texi (Invoking the garbage collector): Added new node
	and section documenting ggc_collect.

From-SVN: r143375

diff --git a/gcc/ChangeLog b/gcc/ChangeLog
index 97e97422c5a4de13c347bfa9586b598c2b5e41fc..fba8a9461be821d499e9febeec7b86e9e244c622 100644 (file)
--- a/gcc/ChangeLog
+++ b/gcc/ChangeLog
@@ -1,3 +1,7 @@
+2009-01-14  Basile Starynkevitch  <basile@starynkevitch.net>
+       * doc/gty.texi (Invoking the garbage collector): Added new node
+       and section documenting ggc_collect.
+
 2009-01-14  Richard Guenther  <rguenther@suse.de>
 
        PR tree-optimization/38826

diff --git a/gcc/doc/gty.texi b/gcc/doc/gty.texi
index 17936146a2efcef6d070c566e893d9d78fab3473..c5c0f9ed051e01ab65518aca67772d33fd716f4e 100644 (file)
--- a/gcc/doc/gty.texi
+++ b/gcc/doc/gty.texi
@@ -1,4 +1,4 @@
-@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.
@@ -69,6 +69,7 @@ These don't need to be marked.
 * 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
@@ -448,3 +449,22 @@ source file.  Don't forget to mention this file as a dependency in 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.
+
+@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.