LCOV - code coverage report
Current view: top level - gcc - is-a.h (source / functions) Hit Total Coverage
Test: gcc.info Lines: 16 16 100.0 %
Date: 2020-04-04 11:58:09 Functions: 16 17 94.1 %
Legend: Lines: hit not hit | Branches: + taken - not taken # not executed Branches: 0 0 -

           Branch data     Line data    Source code
       1                 :            : /* Dynamic testing for abstract is-a relationships.
       2                 :            :    Copyright (C) 2012-2020 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                 :            : Each connection between types must be made by defining a specialization of the
     120                 :            : template member function 'test' of the template class 'is_a_helper'.  For
     121                 :            : example,
     122                 :            : 
     123                 :            :   template <>
     124                 :            :   template <>
     125                 :            :   inline bool
     126                 :            :   is_a_helper <cgraph_node *>::test (symtab_node *p)
     127                 :            :   {
     128                 :            :     return p->type == SYMTAB_FUNCTION;
     129                 :            :   }
     130                 :            : 
     131                 :            : If a simple reinterpret_cast between the pointer types is incorrect, then you
     132                 :            : must also specialize the template member function 'cast'.  Failure to do so
     133                 :            : when needed may result in a crash.  For example,
     134                 :            : 
     135                 :            :   template <>
     136                 :            :   template <>
     137                 :            :   inline bool
     138                 :            :   is_a_helper <cgraph_node *>::cast (symtab_node *p)
     139                 :            :   {
     140                 :            :     return &p->x_function;
     141                 :            :   }
     142                 :            : 
     143                 :            : */
     144                 :            : 
     145                 :            : #ifndef GCC_IS_A_H
     146                 :            : #define GCC_IS_A_H
     147                 :            : 
     148                 :            : /* A generic type conversion internal helper class.  */
     149                 :            : 
     150                 :            : template <typename T>
     151                 :            : struct is_a_helper
     152                 :            : {
     153                 :            :   template <typename U>
     154                 :            :   static inline bool test (U *p);
     155                 :            :   template <typename U>
     156                 :            :   static inline T cast (U *p);
     157                 :            : };
     158                 :            : 
     159                 :            : /* Note that we deliberately do not define the 'test' member template.  Not
     160                 :            :    doing so will result in a build-time error for type relationships that have
     161                 :            :    not been defined, rather than a run-time error.  See the discussion above
     162                 :            :    for when to define this member.  */
     163                 :            : 
     164                 :            : /* This is the generic implementation for casting from one type to another.
     165                 :            :    Do not use this routine directly; it is an internal function.  See the
     166                 :            :    discussion above for when to define this member.  */
     167                 :            : 
     168                 :            : template <typename T>
     169                 :            : template <typename U>
     170                 :            : inline T
     171                 :17936373469 : is_a_helper <T>::cast (U *p)
     172                 :            : {
     173                 :            :   return reinterpret_cast <T> (p);
     174                 :            : }
     175                 :            : 
     176                 :            : 
     177                 :            : /* The public interface.  */
     178                 :            : 
     179                 :            : /* A generic test for a type relationship.  See the discussion above for when
     180                 :            :    to use this function.  The question answered is "Is type T a derived type of
     181                 :            :    type U?".  */
     182                 :            : 
     183                 :            : template <typename T, typename U>
     184                 :            : inline bool
     185                 :>21486*10^7 : is_a (U *p)
     186                 :            : {
     187                 :>30601*10^7 :   return is_a_helper<T>::test (p);
     188                 :            : }
     189                 :            : 
     190                 :            : /* A generic conversion from a base type U to a derived type T.  See the
     191                 :            :    discussion above for when to use this function.  */
     192                 :            : 
     193                 :            : template <typename T, typename U>
     194                 :            : inline T
     195                 :19767650291 : as_a (U *p)
     196                 :            : {
     197                 :18471207286 :   gcc_checking_assert (is_a <T> (p));
     198                 :19769797768 :   return is_a_helper <T>::cast (p);
     199                 :            : }
     200                 :            : 
     201                 :            : /* Similar to as_a<>, but where the pointer can be NULL, even if
     202                 :            :    is_a_helper<T> doesn't check for NULL.  */
     203                 :            : 
     204                 :            : template <typename T, typename U>
     205                 :            : inline T
     206                 :>10318*10^7 : safe_as_a (U *p)
     207                 :            : {
     208                 :>10316*10^7 :   if (p)
     209                 :            :     {
     210                 :  755975096 :       gcc_checking_assert (is_a <T> (p));
     211                 :66835744489 :       return is_a_helper <T>::cast (p);
     212                 :            :     }
     213                 :            :   else
     214                 :            :     return NULL;
     215                 :            : }
     216                 :            : 
     217                 :            : /* A generic checked conversion from a base type U to a derived type T.  See
     218                 :            :    the discussion above for when to use this function.  */
     219                 :            : 
     220                 :            : template <typename T, typename U>
     221                 :            : inline T
     222                 :>13877*10^7 : dyn_cast (U *p)
     223                 :            : {
     224                 :79435003554 :   if (is_a <T> (p))
     225                 :>15055*10^7 :     return is_a_helper <T>::cast (p);
     226                 :            :   else
     227                 :  170767209 :     return static_cast <T> (0);
     228                 :            : }
     229                 :            : 
     230                 :            : /* Similar to dyn_cast, except that the pointer may be null.  */
     231                 :            : 
     232                 :            : template <typename T, typename U>
     233                 :            : inline T
     234                 :   46672955 : safe_dyn_cast (U *p)
     235                 :            : {
     236                 :  118616925 :   return p ? dyn_cast <T> (p) : 0;
     237                 :            : }
     238                 :            : 
     239                 :            : #endif  /* GCC_IS_A_H  */

Generated by: LCOV version 1.0

LCOV profile is generated on x86_64 machine using following configure options: configure --disable-bootstrap --enable-coverage=opt --enable-languages=c,c++,fortran,go,jit,lto --enable-host-shared. GCC test suite is run with the built compiler.