gty.texi (GTY Options): Clarify that variable_size produces allocators taking size in bytes...

2010-11-09  Laurynas Biveinis  <laurynas.biveinis@gmail.com>

	PR/46268
	* doc/gty.texi (GTY Options): Clarify that variable_size produces
	allocators taking size in bytes, compare with length option.  Add
	size calculation example.
	(Invoking the garbage collector): Ensure that sentences are
	followed by two spaces.  Describe that pointer fields must be
	initialized at ggc_collect call.
	(Troubleshooting): New section.

From-SVN: r166519

gcc/ChangeLog

@@ -1,3 +1,14 @@
+2010-11-10  Laurynas Biveinis  <laurynas.biveinis@gmail.com>
+
+	PR/46268
+	* doc/gty.texi (GTY Options): Clarify that variable_size produces
+	allocators taking size in bytes, compare with length option.  Add
+	size calculation example.
+	(Invoking the garbage collector): Ensure that sentences are
+	followed by two spaces.  Describe that pointer fields must be
+	initialized at ggc_collect call.
+	(Troubleshooting): New section.
+
 2010-11-09   Jan Hubicka  <jh@suse.cz>
 
 	PR tree-optimization/40436

gcc/doc/gty.texi

@@ -70,6 +70,7 @@ These don't need to be marked.
 * GGC Roots::           Making global variables GGC roots.
 * Files::               How the generated files work.
 * Invoking the garbage collector::   How to invoke the garbage collector.
+* Troubleshooting::     When something does not work as expected.
 @end menu
 
 @node GTY Options
@@ -355,10 +356,12 @@ number or the hash of a string instead.
 
 The type machinery expects the types to be of constant size.  When this
 is not true, for example, with structs that have array fields or unions,
-the type machinery cannot tell how many bytes need to be allocated at 
+the type machinery cannot tell how many bytes need to be allocated at
 each allocation.  The @code{variable_size} is used to mark such types.
-The type machinery then provides allocators that take a parameter 
-indicating an exact size of object being allocated.  
+The type machinery then provides allocators that take a parameter
+indicating an exact size of object being allocated.  Note that the size
+must be provided in bytes whereas the @code{length} option works with
+array lengths in number of elements.
 
 For example,
 @smallexample
@@ -374,6 +377,12 @@ memory as follows:
   field_vec = ggc_alloc_sorted_fields_type (size);
 @end smallexample
 
+If @var{field_vec->elts} stores @var{n} elements, then @var{size}
+could be calculated as follows:
+@smallexample
+  size_t size = sizeof (struct sorted_fields_type) + n * sizeof (tree);
+@end smallexample
+
 @findex special
 @item special ("@var{name}")
 
@@ -487,12 +496,43 @@ 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
+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
+@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}
+pointers).  In practice GCC passes don't often call @code{ggc_collect}
 themselves, because it is called by the pass manager between passes.
+
+At the time of the @code{ggc_collect} call all pointers in the GC-marked
+structures must be valid or @code{NULL}.  In practice this means that
+there should not be uninitialized pointer fields in the structures even
+if your code never reads or writes those fields at a particular
+instance.  One way to ensure this is to use cleared versions of
+allocators unless all the fields are initialized manually immediately
+after allocation.
+
+@node Troubleshooting
+@section Troubleshooting the garbage collector
+@cindex garbage collector, troubleshooting
+
+With the current garbage collector implementation, most issues should
+show up as GCC compilation errors.  Some of the most commonly
+encountered issues are described below.
+
+@itemize @bullet
+@item Gengtype does not produce allocators for a @code{GTY}-marked type.
+Gengtype checks if there is at least one possible path from GC roots to
+at least one instance of each type before outputting allocators.  If
+there is no such path, the @code{GTY} markers will be ignored and no
+allocators will be output.  Solve this by making sure that there exists
+at least one such path.  If creating it is unfeasible or raises a ``code
+smell'', consider if you really must use GC for allocating such type.
+
+@item Link-time errors about undefined @code{gt_ggc_r_foo_bar} and
+similarly-named symbols.  Check if your @file{foo_bar} source file has
+@code{#include "gt-foo_bar.h"} as its very last line.
+
+@end itemize