LLVM API Documentation

Main Page | Namespace List | Class Hierarchy | Alphabetical List | Class List | Directories | File List | Namespace Members | Class Members | File Members | Related Pages

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