Re: [cxx-conversion] Support garbage-collected C++ templates

[Diego Novillo <dnovillo at google dot com>]

On 12-08-09 03:12 , Laurynas Biveinis wrote:

> Might be also interesting to try valgrind. Good to hear the zone
> collector hasn't bitrotten once again.

Well, it seems it has now. I just tried --with-gc=zone in trunk and it 
failed. I have not merged trunk for 2-3 weeks, so something may have 
broken it in the meantime.

> >          * doc/gty.texi: Document support for C++ templates and
> >          user-provided markers.
>
> The 1st node in this doc file needs s/C/C++/g and perhaps some more
> explanation with an eye on C++.

Sorry.  I'm not sure what you are trying to say here.  I'm adding more 
details on the user-provided GTY keyword below.


Diego.

diff --git a/gcc/doc/gty.texi b/gcc/doc/gty.texi
index 472738e..2210441 100644
--- a/gcc/doc/gty.texi
+++ b/gcc/doc/gty.texi
@@ -68,6 +68,7 @@ These don't need to be marked.
 @menu
 * GTY Options::         What goes inside a @code{GTY(())}.
 * GGC Roots::           Making global variables GGC roots.
+* User GC::            Adding user-provided GC marking routines.
 * Files::               How the generated files work.
 * Invoking the garbage collector::   How to invoke the garbage collector.
 * Troubleshooting::     When something does not work as expected.
@@ -435,20 +436,53 @@ The @code{special} option is used to mark types 
that have to be dealt
 with by special case machinery.  The parameter is the name of the
 special case.  See @file{gengtype.c} for further details.  Avoid
 adding new special cases unless there is no other alternative.
+
+@findex user
+@item user
+
+The @code{user} option indicates that the code to mark structure
+fields is completely handled by user-provided routines.  Section
+@ref{User GC} for details on what functions need to be provided.
 @end table

+@node User GC
 @section Support for user-provided GC marking routines
+@cindex user gc
 The garbage collector supports types for which no automatic marking
 code is generated.  For these types, the user is required to provide
 four functions: one to act as a marker for garbage collection, and
-three functions to act as marker and pointer walking for pre-compiled
+two functions to act as marker and pointer walking for pre-compiled
 headers.

-User-provided types are currently supported for C++ template
-structures. When a template type @code{TP} is marked with @code{GTY},
-all instances of that type are considered user-provided types.  As
-such, the user needs to provide template functions to mark all the
-fields of the type.
+Given a structure @code{struct GTY((user)) my_struct}, the following 
functions
+should be defined to mark @code{my_struct}
+
+@smallexample
+void gt_ggc_mx (my_struct *p)
+@{
+  /* This marks field 'fld'.  */
+  gt_ggc_mx (p->fld);
+@}
+
+void gt_pch_nx (my_struct *p)
+@{
+  /* This marks field 'fld'.  */
+  gt_pch_nx (tp->fld);
+@}
+
+void gt_pch_nx (my_struct *p, gt_pointer_operator op, void *cookie)
+@{
+  /* For every field 'fld', call the given pointer operator.  */
+  op (&(tp->fld), cookie);
+@}
+@end smallexample
+
+@section User-provided marking routines for template types
+When a template type @code{TP} is marked with @code{GTY}, all
+instances of that type are considered user-provided types.  This means
+that the individual instances of @code{TP} do not need to marked with
+@code{GTY}.  The user needs to provide template functions to mark all
+the fields of the type.

 The following code snippets represent all the functions that need to
 be provided. Note that type @code{TP} may reference to more than one
@@ -509,8 +543,6 @@ will, in turn, walk all the pointers inside fields 
of @code{T}).
 In the case of @code{TP<T *>}, references to @code{T *} must be
 handled by calling the @code{op} function on the address of the
 pointer (see the code snippets above).
-
-@item Only template structures are supported at this time.
 @end enumerate

 @node GGC Roots