Add documentation about gengtype and inheritance

	* doc/gty.texi (GTY Options): Add note about inheritance to
	description of desc and tag.
	(Inheritance and GTY): New.

git-svn-id: svn+ssh://gcc.gnu.org/svn/gcc/trunk@204147 138bc75d-0d04-0410-961f-82ee72b054a4

diff --git a/gcc/ChangeLog b/gcc/ChangeLog
index 3a391b0..ac7c86b 100644 (file)
--- a/gcc/ChangeLog
+++ b/gcc/ChangeLog
@@ -1,5 +1,11 @@
 2013-10-29  David Malcolm  <dmalcolm@redhat.com>
 
+       * doc/gty.texi (GTY Options): Add note about inheritance to
+       description of desc and tag.
+       (Inheritance and GTY): New.
+
+2013-10-29  David Malcolm  <dmalcolm@redhat.com>
+
        * gengtype-parse.c (opts_have): Drop "static" so that
        we can use this from gengtype.c.
        * gengtype.c (set_gc_used_type): Mark any base class as used;

diff --git a/gcc/doc/gty.texi b/gcc/doc/gty.texi
index 82e8e4f..090f6a6 100644 (file)
--- a/gcc/doc/gty.texi
+++ b/gcc/doc/gty.texi
@@ -87,6 +87,7 @@ data members.
 
 @menu
 * GTY Options::         What goes inside a @code{GTY(())}.
+* Inheritance and GTY:: Adding GTY to a class hierarchy.
 * User GC::            Adding user-provided GC marking routines.
 * GGC Roots::           Making global variables GGC roots.
 * Files::               How the generated files work.
@@ -234,6 +235,10 @@ In this example, the value of BINDING_HAS_LEVEL_P when applied to a
 mechanism will treat the field @code{level} as being present and if 0,
 will treat the field @code{scope} as being present.
 
+The @code{desc} and @code{tag} options can also be used for inheritance
+to denote which subclass an instance is.  See @ref{Inheritance and GTY}
+for more information.
+
 @findex param_is
 @findex use_param
 @item param_is (@var{type})
@@ -470,6 +475,53 @@ fields is completely handled by user-provided routines.  See section
 @ref{User GC} for details on what functions need to be provided.
 @end table
 
+@node Inheritance and GTY
+@section Support for inheritance
+gengtype has some support for simple class hierarchies.  You can use
+this to have gengtype autogenerate marking routines, provided:
+
+@itemize @bullet
+@item
+There must be a concrete base class, with a discriminator expression
+that can be used to identify which subclass an instance is.
+@item
+Only single inheritance is used.
+@item
+None of the classes within the hierarchy are templates.
+@end itemize
+
+If your class hierarchy does not fit in this pattern, you must use
+@ref{User GC} instead.
+
+The base class and its discriminator must be identified using the ``desc''
+option.  Each concrete subclass must use the ``tag'' option to identify
+which value of the discriminator it corresponds to.
+
+@smallexample
+class GTY((desc("%h.kind"), tag("0"))) example_base
+@{
+public:
+    int kind;
+    tree a;
+@};
+
+class GTY((tag("1")) some_subclass : public example_base
+@{
+public:
+    tree b;
+@};
+
+class GTY((tag("2")) some_other_subclass : public example_base
+@{
+public:
+    tree c;
+@};
+@end smallexample
+
+The generated marking routines for the above will contain a ``switch''
+on ``kind'', visiting all appropriate fields.  For example, if kind is
+2, it will cast to ``some_other_subclass'' and visit fields a, b, and c.
+
 @node User GC
 @section Support for user-provided GC marking routines
 @cindex user gc