diff options
author | Laurynas Biveinis <laurynas.biveinis@gmail.com> | 2010-11-10 04:54:52 +0000 |
---|---|---|
committer | Laurynas Biveinis <lauras@gcc.gnu.org> | 2010-11-10 04:54:52 +0000 |
commit | e65f1db78c2bba088536e57bae37e18deb3ccfad (patch) | |
tree | 8372c50214c47e934cc2a513baf5938cb4ec4198 /gcc/doc/gty.texi | |
parent | 0f292566eb5211a5b2c603b7a5867279d60a40e1 (diff) | |
download | gcc-e65f1db78c2bba088536e57bae37e18deb3ccfad.zip gcc-e65f1db78c2bba088536e57bae37e18deb3ccfad.tar.gz gcc-e65f1db78c2bba088536e57bae37e18deb3ccfad.tar.bz2 |
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
Diffstat (limited to 'gcc/doc/gty.texi')
-rw-r--r-- | gcc/doc/gty.texi | 54 |
1 files changed, 47 insertions, 7 deletions
diff --git a/gcc/doc/gty.texi b/gcc/doc/gty.texi index 05a279c..bc52f91 100644 --- a/gcc/doc/gty.texi +++ b/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 |