gcc/is-a.h

   1 /* Dynamic testing for abstract is-a relationships.
   2    Copyright (C) 2012-2024 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 TYPE safe_dyn_cast <TYPE> (pointer)
 107
 108     Like dyn_cast <TYPE> (pointer), except that it accepts null pointers
 109     and returns null results for them.
 110
 111
 112 If you use these functions and get a 'inline function not defined' or a
 113 'missing symbol' error message for 'is_a_helper<....>::test', it means that
 114 the connection between the types has not been made.  See below.
 115
 116
 117 EXTENDING THE GENERIC TYPE FACILITY
 118
 119 Method 1
 120 --------
 121
 122 If DERIVED is derived from BASE, and if BASE contains enough information
 123 to determine whether an object is actually an instance of DERIVED,
 124 then you can make the above routines work for DERIVED by defining
 125 a specialization of is_a_helper such as:
 126
 127   template<>
 128   struct is_a_helper<DERIVED *> : static_is_a_helper<DERIVED *>
 129   {
 130     static inline bool test (const BASE *p) { return ...; }
 131   };
 132
 133 This test function should return true if P is an instanced of DERIVED.
 134 This on its own is enough; the comments below for method 2 do not apply.
 135
 136 Method 2
 137 --------
 138
 139 Alternatively, if two types are connected in ways other than C++
 140 inheritance, each connection between them must be made by defining a
 141 specialization of the template member function 'test' of the template
 142 class 'is_a_helper'.  For example,
 143
 144   template <>
 145   template <>
 146   inline bool
 147   is_a_helper <cgraph_node *>::test (symtab_node *p)
 148   {
 149     return p->type == SYMTAB_FUNCTION;
 150   }
 151
 152 If a simple reinterpret_cast between the pointer types is incorrect, then you
 153 must also specialize the template member function 'cast'.  Failure to do so
 154 when needed may result in a crash.  For example,
 155
 156   template <>
 157   template <>
 158   inline bool
 159   is_a_helper <cgraph_node *>::cast (symtab_node *p)
 160   {
 161     return &p->x_function;
 162   }
 163
 164 */
 165
 166 #ifndef GCC_IS_A_H
 167 #define GCC_IS_A_H
 168
 169 /* A base class that specializations of is_a_helper can use if casting
 170    U * to T is simply a reinterpret_cast.  */
 171
 172 template <typename T>
 173 struct reinterpret_is_a_helper
 174 {
 175   template <typename U>
 176   static inline T cast (U *p) { return reinterpret_cast <T> (p); }
 177 };
 178
 179 /* A base class that specializations of is_a_helper can use if casting
 180    U * to T is simply a static_cast.  This is more type-safe than
 181    reinterpret_is_a_helper.  */
 182
 183 template <typename T>
 184 struct static_is_a_helper
 185 {
 186   template <typename U>
 187   static inline T cast (U *p) { return static_cast <T> (p); }
 188 };
 189
 190 /* A generic type conversion internal helper class.  */
 191
 192 template <typename T>
 193 struct is_a_helper : reinterpret_is_a_helper<T>
 194 {
 195   template <typename U>
 196   static inline bool test (U *p);
 197 };
 198
 199 /* Reuse the definition of is_a_helper<T *> to implement
 200    is_a_helper<const T *>.  */
 201
 202 template <typename T>
 203 struct is_a_helper<const T *>
 204 {
 205   template <typename U>
 206   static inline const T *cast (const U *p)
 207   {
 208     return is_a_helper<T *>::cast (const_cast <U *> (p));
 209   }
 210   template <typename U>
 211   static inline bool test (const U *p)
 212   {
 213     return is_a_helper<T *>::test (p);
 214   }
 215 };
 216
 217 /* Note that we deliberately do not define the 'test' member template.  Not
 218    doing so will result in a build-time error for type relationships that have
 219    not been defined, rather than a run-time error.  See the discussion above
 220    for when to define this member.  */
 221
 222 /* The public interface.  */
 223
 224 /* A generic test for a type relationship.  See the discussion above for when
 225    to use this function.  The question answered is "Is type T a derived type of
 226    type U?".  */
 227
 228 template <typename T, typename U>
 229 inline bool
 230 is_a (U *p)
 231 {
 232   return is_a_helper<T>::test (p);
 233 }
 234
 235 /* Similar to is_a<>, but where the pointer can be NULL, even if
 236    is_a_helper<T> doesn't check for NULL.  */
 237
 238 template <typename T, typename U>
 239 inline bool
 240 safe_is_a (U *p)
 241 {
 242   if (p)
 243     return is_a_helper <T>::test (p);
 244   else
 245     return false;
 246 }
 247
 248 /* A generic conversion from a base type U to a derived type T.  See the
 249    discussion above for when to use this function.  */
 250
 251 template <typename T, typename U>
 252 inline T
 253 as_a (U *p)
 254 {
 255   gcc_checking_assert (is_a <T> (p));
 256   return is_a_helper <T>::cast (p);
 257 }
 258
 259 /* Similar to as_a<>, but where the pointer can be NULL, even if
 260    is_a_helper<T> doesn't check for NULL.  */
 261
 262 template <typename T, typename U>
 263 inline T
 264 safe_as_a (U *p)
 265 {
 266   if (p)
 267     {
 268       gcc_checking_assert (is_a <T> (p));
 269       return is_a_helper <T>::cast (p);
 270     }
 271   else
 272     return NULL;
 273 }
 274
 275 /* A generic checked conversion from a base type U to a derived type T.  See
 276    the discussion above for when to use this function.  */
 277
 278 template <typename T, typename U>
 279 inline T
 280 dyn_cast (U *p)
 281 {
 282   if (is_a <T> (p))
 283     return is_a_helper <T>::cast (p);
 284   else
 285     return static_cast <T> (0);
 286 }
 287
 288 /* Similar to dyn_cast, except that the pointer may be null.  */
 289
 290 template <typename T, typename U>
 291 inline T
 292 safe_dyn_cast (U *p)
 293 {
 294   return p ? dyn_cast <T> (p) : 0;
 295 }
 296
 297 #endif  /* GCC_IS_A_H  */