gcc/doc/gccint/memory-management-and-type-information/support-for-user-provided-gc-marking-routines.rst

   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 .. index:: user gc
   7
   8 .. _user-gc:
   9
  10 Support for user-provided GC marking routines
  11 *********************************************
  12
  13 The garbage collector supports types for which no automatic marking
  14 code is generated.  For these types, the user is required to provide
  15 three functions: one to act as a marker for garbage collection, and
  16 two functions to act as marker and pointer walker for pre-compiled
  17 headers.
  18
  19 Given a structure ``struct GTY((user)) my_struct``, the following functions
  20 should be defined to mark ``my_struct`` :
  21
  22 .. code-block:: c++
  23
  24   void gt_ggc_mx (my_struct *p)
  25   {
  26     /* This marks field 'fld'.  */
  27     gt_ggc_mx (p->fld);
  28   }
  29
  30   void gt_pch_nx (my_struct *p)
  31   {
  32     /* This marks field 'fld'.  */
  33     gt_pch_nx (tp->fld);
  34   }
  35
  36   void gt_pch_nx (my_struct *p, gt_pointer_operator op, void *cookie)
  37   {
  38     /* For every field 'fld', call the given pointer operator.  */
  39     op (&(tp->fld), NULL, cookie);
  40   }
  41
  42 In general, each marker ``M`` should call ``M`` for every
  43 pointer field in the structure.  Fields that are not allocated in GC
  44 or are not pointers must be ignored.
  45
  46 For embedded lists (e.g., structures with a ``next`` or ``prev``
  47 pointer), the marker must follow the chain and mark every element in
  48 it.
  49
  50 Note that the rules for the pointer walker ``gt_pch_nx (my_struct
  51 *, gt_pointer_operator, void *)`` are slightly different.  In this
  52 case, the operation ``op`` must be applied to the *address* of
  53 every pointer field.
  54
  55 User-provided marking routines for template types
  56 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  57
  58 When a template type ``TP`` is marked with ``GTY``, all
  59 instances of that type are considered user-provided types.  This means
  60 that the individual instances of ``TP`` do not need to be marked
  61 with ``GTY``.  The user needs to provide template functions to mark
  62 all the fields of the type.
  63
  64 The following code snippets represent all the functions that need to
  65 be provided. Note that type ``TP`` may reference to more than one
  66 type. In these snippets, there is only one type ``T``, but there
  67 could be more.
  68
  69 .. code-block:: c++
  70
  71   template<typename T>
  72   void gt_ggc_mx (TP<T> *tp)
  73   {
  74     extern void gt_ggc_mx (T&);
  75
  76     /* This marks field 'fld' of type 'T'.  */
  77     gt_ggc_mx (tp->fld);
  78   }
  79
  80   template<typename T>
  81   void gt_pch_nx (TP<T> *tp)
  82   {
  83     extern void gt_pch_nx (T&);
  84
  85     /* This marks field 'fld' of type 'T'.  */
  86     gt_pch_nx (tp->fld);
  87   }
  88
  89   template<typename T>
  90   void gt_pch_nx (TP<T *> *tp, gt_pointer_operator op, void *cookie)
  91   {
  92     /* For every field 'fld' of 'tp' with type 'T *', call the given
  93        pointer operator.  */
  94     op (&(tp->fld), NULL, cookie);
  95   }
  96
  97   template<typename T>
  98   void gt_pch_nx (TP<T> *tp, gt_pointer_operator, void *cookie)
  99   {
 100     extern void gt_pch_nx (T *, gt_pointer_operator, void *);
 101
 102     /* For every field 'fld' of 'tp' with type 'T', call the pointer
 103        walker for all the fields of T.  */
 104     gt_pch_nx (&(tp->fld), op, cookie);
 105   }
 106
 107 Support for user-defined types is currently limited. The following
 108 restrictions apply:
 109
 110 * Type ``TP`` and all the argument types ``T`` must be
 111   marked with ``GTY``.
 112
 113 * Type ``TP`` can only have type names in its argument list.
 114
 115 * The pointer walker functions are different for ``TP<T>`` and
 116   ``TP<T *>``. In the case of ``TP<T>``, references to
 117   ``T`` must be handled by calling ``gt_pch_nx`` (which
 118   will, in turn, walk all the pointers inside fields of ``T``).
 119   In the case of ``TP<T *>``, references to ``T *`` must be
 120   handled by calling the ``op`` function on the address of the
 121   pointer (see the code snippets above).