[thirdparty/gcc.git] / gcc / doc / gccint / memory-management-and-type-information / support-for-inheritance.rst

..
  Copyright 1988-2022 Free Software Foundation, Inc.
  This is part of the GCC manual.
  For copying conditions, see the copyright.rst file.

.. _inheritance-and-gty:

Support for inheritance
***********************

gengtype has some support for simple class hierarchies.  You can use
this to have gengtype autogenerate marking routines, provided:

* There must be a concrete base class, with a discriminator expression
  that can be used to identify which subclass an instance is.

* Only single inheritance is used.

* None of the classes within the hierarchy are templates.

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.

Every class in the hierarchy must have a ``GTY(())`` marker, as
gengtype will only attempt to parse classes that have such a marker [#f1]_.

.. code-block:: c++

  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;
  };

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.

.. [#f1] Classes lacking such a marker will not be identified as being
  part of the hierarchy, and so the marking routines will not handle them,
  leading to a assertion failure within the marking routines due to an
  unknown tag value (assuming that assertions are enabled).
Commit	Line	Data
c63539ff ML	1	..
	2	Copyright 1988-2022 Free Software Foundation, Inc.
	3	This is part of the GCC manual.
	4	For copying conditions, see the copyright.rst file.
	5
	6	.. _inheritance-and-gty:
	7
	8	Support for inheritance
	9	***********************
	10
	11	gengtype has some support for simple class hierarchies. You can use
	12	this to have gengtype autogenerate marking routines, provided:
	13
	14	* There must be a concrete base class, with a discriminator expression
	15	that can be used to identify which subclass an instance is.
	16
	17	* Only single inheritance is used.
	18
	19	* None of the classes within the hierarchy are templates.
	20
	21	If your class hierarchy does not fit in this pattern, you must use
	22	:ref:`user-gc` instead.
	23
	24	The base class and its discriminator must be identified using the 'desc'
	25	option. Each concrete subclass must use the 'tag' option to identify
	26	which value of the discriminator it corresponds to.
	27
	28	Every class in the hierarchy must have a ``GTY(())`` marker, as
	29	gengtype will only attempt to parse classes that have such a marker [#f1]_.
	30
	31	.. code-block:: c++
	32
	33	class GTY((desc("%h.kind"), tag("0"))) example_base
	34	{
	35	public:
	36	int kind;
	37	tree a;
	38	};
	39
	40	class GTY((tag("1"))) some_subclass : public example_base
	41	{
	42	public:
	43	tree b;
	44	};
	45
	46	class GTY((tag("2"))) some_other_subclass : public example_base
	47	{
	48	public:
	49	tree c;
	50	};
	51
	52	The generated marking routines for the above will contain a 'switch'
	53	on 'kind', visiting all appropriate fields. For example, if kind is
	54	2, it will cast to 'some_other_subclass' and visit fields a, b, and c.
	55
	56	.. [#f1] Classes lacking such a marker will not be identified as being
	57	part of the hierarchy, and so the marking routines will not handle them,
	58	leading to a assertion failure within the marking routines due to an
3ed1b4ce	59	unknown tag value (assuming that assertions are enabled).