include/EDoc/Function.h

Go to the documentation of this file.

/*******************************************************************************

   Copyright (C) 2007 by Brendon Costa

   This library is free software; you can redistribute it and/or modify 
   it under the terms of the "LGPL Like" License defined in the file COPYING 
   that should have been distributed along with this source.

   This library 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.  

   You should have received a copy of the "LGPL Like" License 
   along with this library; see the file COPYING. if not, it can be 
   obtained from the EDoc++ website: 
   http://edoc.sourceforge.net/license.html

*******************************************************************************/
#ifndef EDOC_FUNCTION_H
#define EDOC_FUNCTION_H

#include "EDoc/StringIdentifiedObject.h"
#include "EDoc/exceptions.h"
#include "EDoc/CodeBlock.h"
#include "EDoc/PropogatingException.h"
#include "EDoc/exceptions.h"

#include <ostream>
#include <string>
#include <sstream>
#include <map>
#include <set>

namespace EDoc
{
   class PersistenceIFace;
   class IndexedDictionary;
   class Type;
   class PStack;
   class TranslationUnit;
   
   //===========================================================================
   /** \brief Represents a function in C/C++ code that has been encounterd
    * during compilation.
    *
    * The function object stores all information about encountered functions.
    * This includes information about functions that are called which do not
    * have implementations in the translation unit.
    */
   class Function : public StringIdentifiedObject
   {
   public:

      //------------------------------------------------------------------------
      /** \brief See StringIdentifiedObject::(Dictionary& dict_in, 
       * std::string key_name_in, bool populated_in=false)
       */
      Function(Dictionary& dict_in, std::string key_name_in);

      //------------------------------------------------------------------------
      /** \brief See StringIdentifiedObject(Dictionary& dict_in, 
       * int32_t index_in, bool populated_in=false)
       */
      Function(Dictionary& dict_in, int32_t index_in);

      //------------------------------------------------------------------------
      /** \brief Destructor.
       */
      virtual ~Function();

      //------------------------------------------------------------------------
      /** \brief Copies data from another object into this one.
       *
       * This can be used across different dictionaries and will only copy
       * object data but not identification information used in the
       * StringIdentifiedObject such as the key name.
       */
      Function& operator=(const Function& right);


      //------------------------------------------------------------------------
      /** \brief See StringIdentifiedObject::Read()
       */
      void Read(PersistenceIFace& file, IndexedDictionary& idict);

      //------------------------------------------------------------------------
      /** \brief See StringIdentifiedObject::Write()
       */
      void Write(PersistenceIFace& file) const;

      //------------------------------------------------------------------------
      /** \brief See StringIdentifiedObject::Merge()
       *
       * Merging two functions can occur in a few ways:
       *    -# One function has an implementation the other does not.
       *          This is simple to resolve and behaves like standard linking in
       *          that it keeps the implementation that exists.
       *
       *    -# Both functions have no implementations.
       *          The merge will only import a small amount of data like
       *          additional locations where its address may have been taken
       *          from etc.
       *
       *    -# Both functions have implementations but both implementations are
       *       the same.
       *          The merge will only import a small amount of data like
       *          additional locations where its address may have been taken
       *          from etc. This is normal occurance with functions like
       *          template functions that have "vague linkage".
       *
       *    -# Both functions have implementations but the implementations
       *       differ in a resolvable but unrealistic way.
       *          This should not occur, but may do so due to bad inputs or the
       *          user using certain features of the linker that are not
       *          advisable. In this case we merge the implementations such that
       *          it is the most restrictive union between the two
       *          implementations an we emit an error.
       *
       *    -# Both functions have implementations but the implementations
       *       differ in a way in which they can not be merged.
       *          This should never occur.
       *    .
       *
       */
      virtual void Merge(const StringIdentifiedObject& right);

      //------------------------------------------------------------------------
      /** \brief DictionarySpecific::ReplaceReferences()
       */
      virtual size_t ReplaceReferences(PStack& stack, 
         void* remove, void* replace);

      //------------------------------------------------------------------------
      /** \brief See DictionarySpecific::Print()
       */
      virtual std::ostream& Print(std::ostream& out, 
         std::string prefix="") const;

      //------------------------------------------------------------------------
      /** \brief See DictionarySpecific::Validate()
       */
      virtual void Validate(PStack& stack, const Dictionary& dict_in) const;

      //------------------------------------------------------------------------
      /** \brief See StringIdentifiedObject::GetRecordType()
       */
      virtual uint8_t GetRecordType() const;







      //------------------------------------------------------------------------
      /** \brief Returns a string with the user text that the function was
       * declared with.
       */
      inline std::string GetDeclaredName() const
      {
         return full_name;
      }

      //------------------------------------------------------------------------
      /** \brief Sets a string with the user text that the function was
       * declared with.
       */
      inline void SetDeclaredName(std::string name_in)
      {
         full_name = name_in;
      }

      //------------------------------------------------------------------------
      /** \brief Returns the unique linker id name (C++ Mangaled name).
       */
      inline std::string GetNormalisedName() const
      {
         return link_name;
      }
      

      //------------------------------------------------------------------------
      /** \brief Returns a user readable string with the functions exception
       * restriction specification.
       *
       * This is the throw () string after the function prototype.
       */
      std::string GetSpecString() const;

      //------------------------------------------------------------------------
      /** \brief Returns a user readable string listing all the source files
       * that this function has been referenced from within.
       *
       * Useful for debugging.
       */
      std::string GetRefInFilesString() const;

      //------------------------------------------------------------------------
      /** \brief See Dictionary::ExpandCallGraph()
       */
      void ExpandCallGraph();

      //------------------------------------------------------------------------
      /** \brief Returns a list of all exceptions that propogate from this
       * function that have not been suppressed.
       *
       * Must be called after Dictionary::CalculatePropogatingExceptions()
       */
      std::list<const PropogatingException*> GetVisiblePropExceptions() const;
      
      //------------------------------------------------------------------------
      /** \brief Returns true if this represents the main function.
       */
      bool IsMain() const;
      
      //------------------------------------------------------------------------
      /** \brief Returns true if this function is a "Static initializer".
       *
       * A static initializer function is used to initialize complex static data
       * in a translation unit. This called before the main function.
       */
      bool IsStaticInitialiser() const;
      
      //------------------------------------------------------------------------
      /** \brief Returns true if this represents a destructor for a class.
       */
      bool IsDestructor() const;
      
      //------------------------------------------------------------------------
      /** \brief Returns a list of pointers to propogating exceptions that can 
       * be used by the python wrappers in order to modify the propogating
       * exception objects.
       */
      std::list<EDoc::PropogatingException*> GetPropogatingExceptions();

      //------------------------------------------------------------------------
      /** \brief Returns a reference to the subst exception for this function.
       *
       * The special "substitution" exception is used to represent all 
       * exceptions that may propagate out of a function. It is used in 
       * particular cases where the list of known exceptions can not be known 
       * or calculated until a later date. So when the list of exceptions can 
       * be determined this exception instance is replaced with that 
       * complete list.
       *
       * This is primarily used in the calculation of propagating exceptions 
       * in recursive functions.
       */
      Exception& GetSubstException();

      //------------------------------------------------------------------------
      /** \brief If this function is part of a circular call graph then
       * this function will remove this instance from the circular 
       * set: circular.
       *
       * This is primarily just used for cleaning up on destruction. The
       * circular parameter is generally only created by the 
       * Dictionary::CalculatePropagatingExceptions()
       *
       * See "private" member circular
       */
      void RemoveFromCircular();

      //------------------------------------------------------------------------
      /** \brief Returns true if this function participates in a circular
       * callgraph.
       */
      bool IsCircular() const {return circular;}

      //------------------------------------------------------------------------
      /** \brief Returns true if this function participates in a circular
       * callgraph.
       */
      const std::set<Function*>& GetCircleSet() const 
      {
         EDOC_ASSERT(circular, "");
         return *circular;
      }

      //------------------------------------------------------------------------


      //------------------------------------------------------------------------
      // Public Primary Data values.
      //------------------------------------------------------------------------

      //------------------------------------------------------------------------
      /** \brief The linker string id used for identifying this function.
       *
       * When in C++ this is the mangled function name.
       */
      std::string link_name;

      //------------------------------------------------------------------------
      /** \brief The name of the function as declared by the user in the source
       * file.
       */
      std::string full_name;

      //------------------------------------------------------------------------
      /** \brief True if this funciton has public scope or false if it is
       * private to the translation unit it belongs to.
       */
      bool is_public;

      //------------------------------------------------------------------------
      /** \brief True if this function was inlined at compile time.
       *
       * Note: Inlined functions are treated a littlelike static functions. They
       * can safely have implementation variations between tanslation units.
       */
      bool is_inline;

      //------------------------------------------------------------------------
      /** \brief True if this function was generated implicitly by the compiler 
       * and explicitly created by the user.
       *
       * An example of an implicit function is a Default Constructor created
       * when no other constructors are provided.
       */
      bool is_implicit;

      //------------------------------------------------------------------------
      /** \brief True if an exception specification restriction exists for this
       * function.
       */
      bool has_exception_spec;

      //------------------------------------------------------------------------
      /** \brief If has_exception_spec is true lists the exception types that
       * are allowed to propogate out this function.
       */
      // @@@Brendon Make a list.
      std::vector<Type*> exception_spec;

      //------------------------------------------------------------------------
      /** \brief A list of source code locations where the address of this
       * function was taken for use with a function pointer etc.
       */
      // @@@Brendon Make a list.
      std::vector<Location> address_taken;

      //------------------------------------------------------------------------
      /** \brief The function pointer that represents the type of this funciton.
       *
       * This is used for matching function pointer calls to functions. See
       * FunctionType for more information.
       */
      FunctionType* function_pointer_type;

      //------------------------------------------------------------------------
      /** \brief The location in the source files where this functions prototype
       * was declared or its implementation was defined.
       */
      Location loc;

      //------------------------------------------------------------------------
      /** \brief True if this function was compiled in a translation unit where
       * exceptions were allowed.
       *
       * This is true when -fno-exceptions was not specified in C++
       * or -fexceptions was specified for C. If false then any exceptions that
       * enter or exit this function will cause a program abort.
       */
      bool exceptions_enabled;

      //------------------------------------------------------------------------
      /** \brief Returns the number of implementations of this function have
       * been processed.
       *
       * For most normal functions this should be 1. However for vague linkage
       * functions like template functions this may be more than 1. If 0 however
       * then there should be no valid data in the implementation member.
       */
      int processed_implementations;

      //------------------------------------------------------------------------
      /** \brief A reference to the unique translation unit instance that this
       * function belongs to.
       */
      TranslationUnit* translation_unit;
      
      //------------------------------------------------------------------------
      /** \brief The implementation for this function.
       *
       * The CodeBlock describes in a heirarchial format all function calls,
       * function pointer calls, and try/catch blocks that make up this
       * functions implementation.
       *
       * This member is not valid unless processed_implementations is not zero.
       */
      CodeBlock implementation;


      //------------------------------------------------------------------------
      // Public Derived Data values.
      //------------------------------------------------------------------------


      //------------------------------------------------------------------------
      /** \brief True if the propogating exceptions for this function have been
       * completely calculated.
       */
      bool calculated_propogating_exceptions;

      //------------------------------------------------------------------------
      /** \brief A list of all exceptions that may propogate out this function.
       */
      std::list<PropogatingException> propogating_exceptions;

      //------------------------------------------------------------------------
      /** \brief A list of functions that may be called as a result of a call to
       * this function due to them being matching virtuals in derived classes.
       *
       * List of functions that when this function is called it could result in
       * any of the functions in this list being called as they belong in
       * derived children and this function is virtual.
       *
       * \see See also virt_func_fallthrough
       */
      std::vector<Function*> derived_virtuals;

      //------------------------------------------------------------------------
      /** \brief Is a list of exceptions that would have propogated out this
       * function had they not been filtered out by the exception spec.
       *
       * This is a list of exceptions that would be filterested out by the
       * throw() specs. There should be an error emitted for each filtered
       * exception encountered. They do not propogate.
       *
       * \see See also exception_spec and has_exception_spec
       */
      std::vector<PropogatingException> filtered_exceptions;

      //------------------------------------------------------------------------
      /** \brief A list of all source files that this function is used from.
       */
      std::list<File*> referenced_in_files;


      //------------------------------------------------------------------------
      /** \brief True if this function is visible to the user or false if 
       * it will never be displayed to the user.
       *
       * This is used for suppressions.
       */
      bool visible;

      //------------------------------------------------------------------------
      /** \brief The subst exception for this function.
       *
       * \see GetSubstException()
       */
      Exception* subst_exception;
      
      //------------------------------------------------------------------------
      // Public Temporary Data values.
      //------------------------------------------------------------------------
      /** \brief USED ONLY FROM Dictionary::CalculatePropogatingExceptions()
       *
       * This is used as temporary storage while determining the callgraph
       * complexity of all functions. Realistically this data does not belong
       * here and should be placed elsewhere but as a speed optimisation it is
       * placed here.
       */
      int total_calls;
      
      //------------------------------------------------------------------------
      /** \brief USED ONLY FROM 
       *
       * This is used as a temporary cache of information and is calculated
       * at the same time as total_calls. If it has a reference to a instance
       * then this function is marked as being part of a circular call-graph.
       *
       * The memory for the instance of the std::set is shared among all 
       * Function instances that are part of the circle. Thus when the last of
       * the function instances is deleted then the std::set instance is also 
       * deleted.
       *
       * See RemoveFromCircular()
       */
      std::set<Function*>* circular;

      //------------------------------------------------------------------------
      /** \brief Function pointer for callback called after a function 
       * has finished having its propogating exceptions calculated.
       */
      typedef void(*OnProcessedFP)(Function& function, void* data);

      //------------------------------------------------------------------------
      /** \brief Set a callback function to be called immediatly after the
       * functions set of propogating exceptions have been calculated.
       *
       * This is generally used for suppressing any exceptions that propogate
       * from this function by making the exceptions invisible, without removing
       * them entirely. This feature is used by the default suppressions.
       *
       * \param fp Pointer to function to be called.
       *
       * \param data Some data to be passed to the function pointer when it 
       * is called.
       */
      void SetOnProcessed(OnProcessedFP fp, void* data)
      {
         on_processed = fp;
         on_processed_data = data;
      }
      
      //------------------------------------------------------------------------
      /** \brief Callback function pointer (See SetOnProcessed())
       */
      OnProcessedFP on_processed;

      //------------------------------------------------------------------------
      /** \brief Callback function pointers data (See SetOnProcessed())
       */
      void* on_processed_data;

      //------------------------------------------------------------------------
   };
   //===========================================================================
   typedef std::map<std::string, EDoc::Function*> FuncPMap;
   typedef std::list<EDoc::Function*> FuncPList;
   //---------------------------------------------------------------------------
}

#endif // EDOC_FUNCTION_H

---