Subversion Repositories altor32

/* Dynamic testing for abstract is-a relationships.

   Copyright (C) 2012 Free Software Foundation, Inc.

   Contributed by Lawrence Crowl.

This file is part of GCC.

GCC is free software; you can redistribute it and/or modify it under

the terms of the GNU General Public License as published by the Free

Software Foundation; either version 3, or (at your option) any later

version.

GCC is distributed in the hope that it will be useful, but WITHOUT ANY

WARRANTY; without even the implied warranty of MERCHANTABILITY or

FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License

for more details.

You should have received a copy of the GNU General Public License

along with GCC; see the file COPYING3.  If not see

<http://www.gnu.org/licenses/>.  */

/* This header generic type query and conversion functions.

USING THE GENERIC TYPE FACILITY

The user functions are:

bool is_a <TYPE> (pointer)

    Tests whether the pointer actually points to a more derived TYPE.

    Suppose you have a symtab_node_def *ptr, AKA symtab_node ptr.  You can test

    whether it points to a 'derived' cgraph_node as follows.

      if (is_a <cgraph_node> (ptr))

        ....

TYPE *as_a <TYPE> (pointer)

    Converts pointer to a TYPE*.

    You can just assume that it is such a node.

      do_something_with (as_a <cgraph_node> *ptr);

TYPE *dyn_cast <TYPE> (pointer)

    Converts pointer to TYPE* if and only if "is_a <TYPE> pointer".  Otherwise,

    returns NULL.  This function is essentially a checked down cast.

    This functions reduce compile time and increase type safety when treating a

    generic item as a more specific item.

    You can test and obtain a pointer to the 'derived' type in one indivisible

    operation.

      if (cgraph_node *cptr = dyn_cast <cgraph_node> (ptr))

        ....

    As an example, the code change is from

      if (symtab_function_p (node))

        {

          struct cgraph_node *cnode = cgraph (node);

          ....

        }

    to

      if (cgraph_node *cnode = dyn_cast <cgraph_node> (node))

        {

          ....

        }

    The necessary conditional test defines a variable that holds a known good

    pointer to the specific item and avoids subsequent conversion calls and

    the assertion checks that may come with them.

    When, the property test is embedded within a larger condition, the

    variable declaration gets pulled out of the condition.  (This approach

    leaves some room for using the variable inappropriately.)

      if (symtab_variable_p (node) && varpool (node)->finalized)

        varpool_analyze_node (varpool (node));

    becomes

      varpool_node *vnode = dyn_cast <varpool_node> (node);

      if (vnode && vnode->finalized)

        varpool_analyze_node (vnode);

    Note that we have converted two sets of assertions in the calls to varpool

    into safe and efficient use of a variable.

If you use these functions and get a 'inline function not defined' or a

'missing symbol' error message for 'is_a_helper<....>::test', it means that

the connection between the types has not been made.  See below.

EXTENDING THE GENERIC TYPE FACILITY

Each connection between types must be made by defining a specialization of the

template member function 'test' of the template class 'is_a_helper'.  For

example,

  template <>

  template <>

  inline bool

  is_a_helper <cgraph_node>::test (symtab_node_def *p)

  {

    return p->symbol.type == SYMTAB_FUNCTION;

  }

If a simple reinterpret_cast between the pointer types is incorrect, then you

must also specialize the template member function 'cast'.  Failure to do so

when needed may result in a crash.  For example,

  template <>

  template <>

  inline bool

  is_a_helper <cgraph_node>::cast (symtab_node_def *p)

  {

    return &p->x_function;

  }

*/

#ifndef GCC_IS_A_H

#define GCC_IS_A_H

/* A generic type conversion internal helper class.  */

template <typename T>

struct is_a_helper

{

  template <typename U>

  static inline bool test (U *p);

  template <typename U>

  static inline T *cast (U *p);

};

/* Note that we deliberately do not define the 'test' member template.  Not

   doing so will result in a build-time error for type relationships that have

   not been defined, rather than a run-time error.  See the discussion above

   for when to define this member.  */

/* This is the generic implementation for casting from one type to another.

   Do not use this routine directly; it is an internal function.  See the

   discussion above for when to define this member.  */

template <typename T>

template <typename U>

inline T *

is_a_helper <T>::cast (U *p)

{

  return reinterpret_cast <T *> (p);

}

/* The public interface.  */

/* A generic test for a type relationship.  See the discussion above for when

   to use this function.  The question answered is "Is type T a derived type of

   type U?".  */

template <typename T, typename U>

inline bool

is_a (U *p)

{

  return is_a_helper<T>::test (p);

}

/* A generic conversion from a base type U to a derived type T.  See the

   discussion above for when to use this function.  */

template <typename T, typename U>

inline T *

as_a (U *p)

{

  gcc_assert (is_a <T> (p));

  return is_a_helper <T>::cast (p);

}

/* A generic checked conversion from a base type U to a derived type T.  See

   the discussion above for when to use this function.  */

template <typename T, typename U>

inline T *

dyn_cast (U *p)

{

  if (is_a <T> (p))

    return is_a_helper <T>::cast (p);

  else

    return static_cast <T *> (0);

}

#endif  /* GCC_IS_A_H  */