gcc/is-a.h

   1 /* Dynamic testing for abstract is-a relationships.
   2    Copyright (C) 2012-2016 Free Software Foundation, Inc.
   3    Contributed by Lawrence Crowl.
   4
   5 This file is part of GCC.
   6
   7 GCC is free software; you can redistribute it and/or modify it under
   8 the terms of the GNU General Public License as published by the Free
   9 Software Foundation; either version 3, or (at your option) any later
  10 version.
  11
  12 GCC is distributed in the hope that it will be useful, but WITHOUT ANY
  13 WARRANTY; without even the implied warranty of MERCHANTABILITY or
  14 FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
  15 for more details.
  16
  17 You should have received a copy of the GNU General Public License
  18 along with GCC; see the file COPYING3.  If not see
  19 <http://www.gnu.org/licenses/>.  */
  20
  21
  22 /* This header generic type query and conversion functions.
  23
  24
  25 USING THE GENERIC TYPE FACILITY
  26
  27
  28 The user functions are:
  29
  30 bool is_a <TYPE> (pointer)
  31
  32     Tests whether the pointer actually points to a more derived TYPE.
  33
  34     Suppose you have a symtab_node *ptr, AKA symtab_node *ptr.  You can test
  35     whether it points to a 'derived' cgraph_node as follows.
  36
  37       if (is_a <cgraph_node *> (ptr))
  38         ....
  39
  40
  41 TYPE as_a <TYPE> (pointer)
  42
  43     Converts pointer to a TYPE.
  44
  45     You can just assume that it is such a node.
  46
  47       do_something_with (as_a <cgraph_node *> *ptr);
  48
  49 TYPE safe_as_a <TYPE> (pointer)
  50
  51     Like as_a <TYPE> (pointer), but where pointer could be NULL.  This
  52     adds a check against NULL where the regular is_a_helper hook for TYPE
  53     assumes non-NULL.
  54
  55       do_something_with (safe_as_a <cgraph_node *> *ptr);
  56
  57 TYPE dyn_cast <TYPE> (pointer)
  58
  59     Converts pointer to TYPE if and only if "is_a <TYPE> pointer".  Otherwise,
  60     returns NULL.  This function is essentially a checked down cast.
  61
  62     This functions reduce compile time and increase type safety when treating a
  63     generic item as a more specific item.
  64
  65     You can test and obtain a pointer to the 'derived' type in one indivisible
  66     operation.
  67
  68       if (cgraph_node *cptr = dyn_cast <cgraph_node *> (ptr))
  69         ....
  70
  71     As an example, the code change is from
  72
  73       if (symtab_function_p (node))
  74         {
  75           struct cgraph_node *cnode = cgraph (node);
  76           ....
  77         }
  78
  79     to
  80
  81       if (cgraph_node *cnode = dyn_cast <cgraph_node *> (node))
  82         {
  83           ....
  84         }
  85
  86     The necessary conditional test defines a variable that holds a known good
  87     pointer to the specific item and avoids subsequent conversion calls and
  88     the assertion checks that may come with them.
  89
  90     When, the property test is embedded within a larger condition, the
  91     variable declaration gets pulled out of the condition.  (This approach
  92     leaves some room for using the variable inappropriately.)
  93
  94       if (symtab_variable_p (node) && varpool (node)->finalized)
  95         varpool_analyze_node (varpool (node));
  96
  97     becomes
  98
  99       varpool_node *vnode = dyn_cast <varpool_node *> (node);
 100       if (vnode && vnode->finalized)
 101         varpool_analyze_node (vnode);
 102
 103     Note that we have converted two sets of assertions in the calls to varpool
 104     into safe and efficient use of a variable.
 105
 106
 107 If you use these functions and get a 'inline function not defined' or a
 108 'missing symbol' error message for 'is_a_helper<....>::test', it means that
 109 the connection between the types has not been made.  See below.
 110
 111
 112 EXTENDING THE GENERIC TYPE FACILITY
 113
 114 Each connection between types must be made by defining a specialization of the
 115 template member function 'test' of the template class 'is_a_helper'.  For
 116 example,
 117
 118   template <>
 119   template <>
 120   inline bool
 121   is_a_helper <cgraph_node *>::test (symtab_node *p)
 122   {
 123     return p->type == SYMTAB_FUNCTION;
 124   }
 125
 126 If a simple reinterpret_cast between the pointer types is incorrect, then you
 127 must also specialize the template member function 'cast'.  Failure to do so
 128 when needed may result in a crash.  For example,
 129
 130   template <>
 131   template <>
 132   inline bool
 133   is_a_helper <cgraph_node *>::cast (symtab_node *p)
 134   {
 135     return &p->x_function;
 136   }
 137
 138 */
 139
 140 #ifndef GCC_IS_A_H
 141 #define GCC_IS_A_H
 142
 143 /* A generic type conversion internal helper class.  */
 144
 145 template <typename T>
 146 struct is_a_helper
 147 {
 148   template <typename U>
 149   static inline bool test (U *p);
 150   template <typename U>
 151   static inline T cast (U *p);
 152 };
 153
 154 /* Note that we deliberately do not define the 'test' member template.  Not
 155    doing so will result in a build-time error for type relationships that have
 156    not been defined, rather than a run-time error.  See the discussion above
 157    for when to define this member.  */
 158
 159 /* This is the generic implementation for casting from one type to another.
 160    Do not use this routine directly; it is an internal function.  See the
 161    discussion above for when to define this member.  */
 162
 163 template <typename T>
 164 template <typename U>
 165 inline T
 166 is_a_helper <T>::cast (U *p)
 167 {
 168   return reinterpret_cast <T> (p);
 169 }
 170
 171
 172 /* The public interface.  */
 173
 174 /* A generic test for a type relationship.  See the discussion above for when
 175    to use this function.  The question answered is "Is type T a derived type of
 176    type U?".  */
 177
 178 template <typename T, typename U>
 179 inline bool
 180 is_a (U *p)
 181 {
 182   return is_a_helper<T>::test (p);
 183 }
 184
 185 /* A generic conversion from a base type U to a derived type T.  See the
 186    discussion above for when to use this function.  */
 187
 188 template <typename T, typename U>
 189 inline T
 190 as_a (U *p)
 191 {
 192   gcc_checking_assert (is_a <T> (p));
 193   return is_a_helper <T>::cast (p);
 194 }
 195
 196 /* Similar to as_a<>, but where the pointer can be NULL, even if
 197    is_a_helper<T> doesn't check for NULL.  */
 198
 199 template <typename T, typename U>
 200 inline T
 201 safe_as_a (U *p)
 202 {
 203   if (p)
 204     {
 205       gcc_checking_assert (is_a <T> (p));
 206       return is_a_helper <T>::cast (p);
 207     }
 208   else
 209     return NULL;
 210 }
 211
 212 /* A generic checked conversion from a base type U to a derived type T.  See
 213    the discussion above for when to use this function.  */
 214
 215 template <typename T, typename U>
 216 inline T
 217 dyn_cast (U *p)
 218 {
 219   if (is_a <T> (p))
 220     return is_a_helper <T>::cast (p);
 221   else
 222     return static_cast <T> (0);
 223 }
 224
 225 #endif  /* GCC_IS_A_H  */