contrib/llvm/tools/lldb/include/lldb/Symbol/SymbolContextScope.h

   1 //===-- SymbolContextScope.h ------------------------------------*- C++ -*-===//
   2 //
   3 //                     The LLVM Compiler Infrastructure
   4 //
   5 // This file is distributed under the University of Illinois Open Source
   6 // License. See LICENSE.TXT for details.
   7 //
   8 //===----------------------------------------------------------------------===//
   9
  10 #ifndef liblldb_SymbolContextScope_h_
  11 #define liblldb_SymbolContextScope_h_
  12
  13 // C Includes
  14 // C++ Includes
  15 // Other libraries and framework includes
  16 // Project includes
  17 #include "lldb/lldb-private.h"
  18
  19 namespace lldb_private {
  20
  21 //----------------------------------------------------------------------
  22 /// @class SymbolContextScope SymbolContextScope.h "lldb/Symbol/SymbolContextScope.h"
  23 /// @brief Inherit from this if your object is part of a symbol context
  24 ///        and can reconstruct its symbol context.
  25 ///
  26 /// Many objects that are part of a symbol context that have pointers
  27 /// back to parent objects that own them. Any members of a symbol
  28 /// context that, once they are built, will not go away, can inherit
  29 /// from this pure virtual class and can then reconstruct their symbol
  30 /// context without having to keep a complete SymbolContext object in
  31 /// the object.
  32 ///
  33 /// Examples of these objects include:
  34 ///     @li Module
  35 ///     @li CompileUnit
  36 ///     @li Function
  37 ///     @li Block
  38 ///     @li Symbol
  39 ///
  40 /// Other objects can store a "SymbolContextScope *" using any pointers
  41 /// to one of the above objects. This allows clients to hold onto a
  42 /// pointer that uniquely will identify a symbol context. Those clients
  43 /// can then always reconstruct the symbol context using the pointer, or
  44 /// use it to uniquely identify a symbol context for an object.
  45 ///
  46 /// Example objects include that currently use "SymbolContextScope *"
  47 /// objects include:
  48 ///     @li Variable objects that can reconstruct where they are scoped
  49 ///         by making sure the SymbolContextScope * comes from the scope
  50 ///         in which the variable was declared. If a variable is a global,
  51 ///         the appropriate CompileUnit * will be used when creating the
  52 ///         variable. A static function variables, can the Block scope
  53 ///         in which the variable is defined. Function arguments can use
  54 ///         the Function object as their scope. The SymbolFile parsers
  55 ///         will set these correctly as the variables are parsed.
  56 ///     @li Type objects that know exactly in which scope they
  57 ///         originated much like the variables above.
  58 ///     @li StackID objects that are able to know that if the CFA
  59 ///         (stack pointer at the beginning of a function) and the
  60 ///         start PC for the function/symbol and the SymbolContextScope
  61 ///         pointer (a unique pointer that identifies a symbol context
  62 ///         location) match within the same thread, that the stack
  63 ///         frame is the same as the previous stack frame.
  64 ///
  65 /// Objects that adhere to this protocol can reconstruct enough of a
  66 /// symbol context to allow functions that take a symbol context to be
  67 /// called. Lists can also be created using a SymbolContextScope* and
  68 /// and object pairs that allow large collections of objects to be
  69 /// passed around with minimal overhead.
  70 //----------------------------------------------------------------------
  71 class SymbolContextScope
  72 {
  73 public:
  74     virtual
  75     ~SymbolContextScope () {}
  76
  77     //------------------------------------------------------------------
  78     /// Reconstruct the object's symbolc context into \a sc.
  79     ///
  80     /// The object should fill in as much of the SymbolContext as it
  81     /// can so function calls that require a symbol context can be made
  82     /// for the given object.
  83     ///
  84     /// @param[out] sc
  85     ///     A symbol context object pointer that gets filled in.
  86     //------------------------------------------------------------------
  87     virtual void
  88     CalculateSymbolContext (SymbolContext *sc) = 0;
  89
  90
  91     virtual lldb::ModuleSP
  92     CalculateSymbolContextModule ()
  93     {
  94         return lldb::ModuleSP();
  95     }
  96
  97     virtual CompileUnit *
  98     CalculateSymbolContextCompileUnit ()
  99     {
 100         return NULL;
 101     }
 102
 103     virtual Function *
 104     CalculateSymbolContextFunction ()
 105     {
 106         return NULL;
 107     }
 108
 109     virtual Block *
 110     CalculateSymbolContextBlock ()
 111     {
 112         return NULL;
 113     }
 114
 115     virtual Symbol *
 116     CalculateSymbolContextSymbol ()
 117     {
 118         return NULL;
 119     }
 120
 121     //------------------------------------------------------------------
 122     /// Dump the object's symbolc context to the stream \a s.
 123     ///
 124     /// The object should dump its symbol context to the stream \a s.
 125     /// This function is widely used in the DumpDebug and verbose output
 126     /// for lldb objets.
 127     ///
 128     /// @param[in] s
 129     ///     The stream to which to dump the object's symbol context.
 130     //------------------------------------------------------------------
 131     virtual void
 132     DumpSymbolContext (Stream *s) = 0;
 133 };
 134
 135 } // namespace lldb_private
 136
 137 #endif  // liblldb_SymbolContextScope_h_