LLVM API Documentation

ProgramInfo.h

Go to the documentation of this file.
00001 //===- ProgramInfo.h - Information about the loaded program -----*- C++ -*-===//
00002 //
00003 //                     The LLVM Compiler Infrastructure
00004 //
00005 // This file was developed by the LLVM research group and is distributed under
00006 // the University of Illinois Open Source License. See LICENSE.TXT for details.
00007 //
00008 //===----------------------------------------------------------------------===//
00009 //
00010 // This file defines various pieces of information about the currently loaded
00011 // program.  One instance of this object is created every time a program is
00012 // loaded, and destroyed every time it is unloaded.
00013 //
00014 // The various pieces of information gathered about the source program are all
00015 // designed to be extended by various SourceLanguage implementations.  This
00016 // allows source languages to keep any extended information that they support in
00017 // the derived class portions of the class.
00018 //
00019 //===----------------------------------------------------------------------===//
00020 
00021 #ifndef LLVM_DEBUGGER_PROGRAMINFO_H
00022 #define LLVM_DEBUGGER_PROGRAMINFO_H
00023 
00024 #include "llvm/System/TimeValue.h"
00025 #include <string>
00026 #include <map>
00027 #include <vector>
00028 
00029 namespace llvm {
00030   class GlobalVariable;
00031   class Module;
00032   class SourceFile;
00033   class SourceLanguage;
00034   class ProgramInfo;
00035 
00036   /// SourceLanguageCache - SourceLanguage implementations are allowed to cache
00037   /// stuff in the ProgramInfo object.  The only requirement we have on these
00038   /// instances is that they are destroyable.
00039   struct SourceLanguageCache {
00040     virtual ~SourceLanguageCache() {}
00041   };
00042 
00043   /// SourceFileInfo - One instance of this structure is created for each
00044   /// source file in the program.
00045   ///
00046   class SourceFileInfo {
00047     /// BaseName - The filename of the source file.
00048     std::string BaseName;
00049 
00050     /// Directory - The working directory of this source file when it was
00051     /// compiled.
00052     std::string Directory;
00053 
00054     /// Version - The version of the LLVM debug information that this file was
00055     /// compiled with.
00056     unsigned Version;
00057 
00058     /// Language - The source language that the file was compiled with.  This
00059     /// pointer is never null.
00060     ///
00061     const SourceLanguage *Language;
00062 
00063     /// Descriptor - The LLVM Global Variable which describes the source file.
00064     ///
00065     const GlobalVariable *Descriptor;
00066 
00067     /// SourceText - The body of this source file, or null if it has not yet
00068     /// been loaded.
00069     mutable SourceFile *SourceText;
00070   public:
00071     SourceFileInfo(const GlobalVariable *Desc, const SourceLanguage &Lang);
00072     ~SourceFileInfo();
00073 
00074     const std::string &getBaseName() const { return BaseName; }
00075     const std::string &getDirectory() const { return Directory; }
00076     unsigned getDebugVersion() const { return Version; }
00077     const GlobalVariable *getDescriptor() const { return Descriptor; }
00078     SourceFile &getSourceText() const;
00079 
00080     const SourceLanguage &getLanguage() const { return *Language; }
00081   };
00082 
00083 
00084   /// SourceFunctionInfo - An instance of this class is used to represent each
00085   /// source function in the program.
00086   ///
00087   class SourceFunctionInfo {
00088     /// Name - This contains an abstract name that is potentially useful to the
00089     /// end-user.  If there is no explicit support for the current language,
00090     /// then this string is used to identify the function.
00091     std::string Name;
00092 
00093     /// Descriptor - The descriptor for this function.
00094     ///
00095     const GlobalVariable *Descriptor;
00096 
00097     /// SourceFile - The file that this function is defined in.
00098     ///
00099     const SourceFileInfo *SourceFile;
00100 
00101     /// LineNo, ColNo - The location of the first stop-point in the function.
00102     /// These are computed on demand.
00103     mutable unsigned LineNo, ColNo;
00104 
00105   public:
00106     SourceFunctionInfo(ProgramInfo &PI, const GlobalVariable *Desc);
00107     virtual ~SourceFunctionInfo() {}
00108 
00109     /// getSymbolicName - Return a human-readable symbolic name to identify the
00110     /// function (for example, in stack traces).
00111     virtual std::string getSymbolicName() const { return Name; }
00112 
00113     /// getDescriptor - This returns the descriptor for the function.
00114     ///
00115     const GlobalVariable *getDescriptor() const { return Descriptor; }
00116 
00117     /// getSourceFile - This returns the source file that defines the function.
00118     ///
00119     const SourceFileInfo &getSourceFile() const { return *SourceFile; }
00120 
00121     /// getSourceLocation - This method returns the location of the first
00122     /// stopping point in the function.  If the body of the function cannot be
00123     /// found, this returns zeros for both values.
00124     void getSourceLocation(unsigned &LineNo, unsigned &ColNo) const;
00125   };
00126 
00127 
00128   /// ProgramInfo - This object contains information about the loaded program.
00129   /// When a new program is loaded, an instance of this class is created.  When
00130   /// the program is unloaded, the instance is destroyed.  This object basically
00131   /// manages the lazy computation of information useful for the debugger.
00132   class ProgramInfo {
00133     Module *M;
00134 
00135     /// ProgramTimeStamp - This is the timestamp of the executable file that we
00136     /// currently have loaded into the debugger.
00137     sys::TimeValue ProgramTimeStamp;
00138 
00139     /// SourceFiles - This map is used to transform source file descriptors into
00140     /// their corresponding SourceFileInfo objects.  This mapping owns the
00141     /// memory for the SourceFileInfo objects.
00142     ///
00143     bool SourceFilesIsComplete;
00144     std::map<const GlobalVariable*, SourceFileInfo*> SourceFiles;
00145 
00146     /// SourceFileIndex - Mapping from source file basenames to the information
00147     /// about the file.  Note that there can be filename collisions, so this is
00148     /// a multimap.  This map is populated incrementally as the user interacts
00149     /// with the program, through the getSourceFileFromDesc method.  If ALL of
00150     /// the source files are needed, the getSourceFiles() method scans the
00151     /// entire program looking for them.
00152     ///
00153     std::multimap<std::string, SourceFileInfo*> SourceFileIndex;
00154 
00155     /// SourceFunctions - This map contains entries functions in the source
00156     /// program.  If SourceFunctionsIsComplete is true, then this is ALL of the
00157     /// functions in the program are in this map.
00158     bool SourceFunctionsIsComplete;
00159     std::map<const GlobalVariable*, SourceFunctionInfo*> SourceFunctions;
00160 
00161     /// LanguageCaches - Each source language is permitted to keep a per-program
00162     /// cache of information specific to whatever it needs.  This vector is
00163     /// effectively a small map from the languages that are active in the
00164     /// program to their caches.  This can be accessed by the language by the
00165     /// "getLanguageCache" method.
00166     std::vector<std::pair<const SourceLanguage*,
00167                           SourceLanguageCache*> > LanguageCaches;
00168   public:
00169     ProgramInfo(Module *m);
00170     ~ProgramInfo();
00171 
00172     /// getProgramTimeStamp - Return the time-stamp of the program when it was
00173     /// loaded.
00174     sys::TimeValue getProgramTimeStamp() const { return ProgramTimeStamp; }
00175 
00176     //===------------------------------------------------------------------===//
00177     // Interfaces to the source code files that make up the program.
00178     //
00179 
00180     /// getSourceFile - Return source file information for the specified source
00181     /// file descriptor object, adding it to the collection as needed.  This
00182     /// method always succeeds (is unambiguous), and is always efficient.
00183     ///
00184     const SourceFileInfo &getSourceFile(const GlobalVariable *Desc);
00185 
00186     /// getSourceFile - Look up the file with the specified name.  If there is
00187     /// more than one match for the specified filename, prompt the user to pick
00188     /// one.  If there is no source file that matches the specified name, throw
00189     /// an exception indicating that we can't find the file.  Otherwise, return
00190     /// the file information for that file.
00191     ///
00192     /// If the source file hasn't been discovered yet in the program, this
00193     /// method might have to index the whole program by calling the
00194     /// getSourceFiles() method.
00195     ///
00196     const SourceFileInfo &getSourceFile(const std::string &Filename);
00197 
00198     /// getSourceFiles - Index all of the source files in the program and return
00199     /// them.  This information is lazily computed the first time that it is
00200     /// requested.  Since this information can take a long time to compute, the
00201     /// user is given a chance to cancel it.  If this occurs, an exception is
00202     /// thrown.
00203     const std::map<const GlobalVariable*, SourceFileInfo*> &
00204     getSourceFiles(bool RequiresCompleteMap = true);
00205 
00206     //===------------------------------------------------------------------===//
00207     // Interfaces to the functions that make up the program.
00208     //
00209 
00210     /// getFunction - Return source function information for the specified
00211     /// function descriptor object, adding it to the collection as needed.  This
00212     /// method always succeeds (is unambiguous), and is always efficient.
00213     ///
00214     const SourceFunctionInfo &getFunction(const GlobalVariable *Desc);
00215 
00216     /// getSourceFunctions - Index all of the functions in the program and
00217     /// return them.  This information is lazily computed the first time that it
00218     /// is requested.  Since this information can take a long time to compute,
00219     /// the user is given a chance to cancel it.  If this occurs, an exception
00220     /// is thrown.
00221     const std::map<const GlobalVariable*, SourceFunctionInfo*> &
00222     getSourceFunctions(bool RequiresCompleteMap = true);
00223 
00224     /// addSourceFunctionsRead - Return true if the source functions map is
00225     /// complete: that is, all functions in the program have been read in.
00226     bool allSourceFunctionsRead() const { return SourceFunctionsIsComplete; }
00227 
00228     /// getLanguageCache - This method is used to build per-program caches of
00229     /// information, such as the functions or types visible to the program.
00230     /// This can be used by SourceLanguage implementations because it requires
00231     /// an accessible [sl]::CacheType typedef, where [sl] is the C++ type of the
00232     /// source-language subclass.
00233     template<typename SL>
00234     typename SL::CacheType &getLanguageCache(const SL *L) {
00235       for (unsigned i = 0, e = LanguageCaches.size(); i != e; ++i)
00236         if (LanguageCaches[i].first == L)
00237           return *(typename SL::CacheType*)LanguageCaches[i].second;
00238       typename SL::CacheType *NewCache = L->createSourceLanguageCache(*this);
00239       LanguageCaches.push_back(std::make_pair(L, NewCache));
00240       return *NewCache;
00241     }
00242   };
00243 
00244 } // end namespace llvm
00245 
00246 #endif