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
  23 /// "lldb/Symbol/SymbolContextScope.h"
  24 /// @brief Inherit from this if your object is part of a symbol context
  25 ///        and can reconstruct its symbol context.
  26 ///
  27 /// Many objects that are part of a symbol context that have pointers
  28 /// back to parent objects that own them. Any members of a symbol
  29 /// context that, once they are built, will not go away, can inherit
  30 /// from this pure virtual class and can then reconstruct their symbol
  31 /// context without having to keep a complete SymbolContext object in
  32 /// the object.
  33 ///
  34 /// Examples of these objects include:
  35 ///     @li Module
  36 ///     @li CompileUnit
  37 ///     @li Function
  38 ///     @li Block
  39 ///     @li Symbol
  40 ///
  41 /// Other objects can store a "SymbolContextScope *" using any pointers
  42 /// to one of the above objects. This allows clients to hold onto a
  43 /// pointer that uniquely will identify a symbol context. Those clients
  44 /// can then always reconstruct the symbol context using the pointer, or
  45 /// use it to uniquely identify a symbol context for an object.
  46 ///
  47 /// Example objects include that currently use "SymbolContextScope *"
  48 /// objects include:
  49 ///     @li Variable objects that can reconstruct where they are scoped
  50 ///         by making sure the SymbolContextScope * comes from the scope
  51 ///         in which the variable was declared. If a variable is a global,
  52 ///         the appropriate CompileUnit * will be used when creating the
  53 ///         variable. A static function variables, can the Block scope
  54 ///         in which the variable is defined. Function arguments can use
  55 ///         the Function object as their scope. The SymbolFile parsers
  56 ///         will set these correctly as the variables are parsed.
  57 ///     @li Type objects that know exactly in which scope they
  58 ///         originated much like the variables above.
  59 ///     @li StackID objects that are able to know that if the CFA
  60 ///         (stack pointer at the beginning of a function) and the
  61 ///         start PC for the function/symbol and the SymbolContextScope
  62 ///         pointer (a unique pointer that identifies a symbol context
  63 ///         location) match within the same thread, that the stack
  64 ///         frame is the same as the previous stack frame.
  65 ///
  66 /// Objects that adhere to this protocol can reconstruct enough of a
  67 /// symbol context to allow functions that take a symbol context to be
  68 /// called. Lists can also be created using a SymbolContextScope* and
  69 /// and object pairs that allow large collections of objects to be
  70 /// passed around with minimal overhead.
  71 //----------------------------------------------------------------------
  72 class SymbolContextScope {
  73 public:
  74   virtual ~SymbolContextScope() = default;
  75
  76   //------------------------------------------------------------------
  77   /// Reconstruct the object's symbol context into \a sc.
  78   ///
  79   /// The object should fill in as much of the SymbolContext as it
  80   /// can so function calls that require a symbol context can be made
  81   /// for the given object.
  82   ///
  83   /// @param[out] sc
  84   ///     A symbol context object pointer that gets filled in.
  85   //------------------------------------------------------------------
  86   virtual void CalculateSymbolContext(SymbolContext *sc) = 0;
  87
  88   virtual lldb::ModuleSP CalculateSymbolContextModule() {
  89     return lldb::ModuleSP();
  90   }
  91
  92   virtual CompileUnit *CalculateSymbolContextCompileUnit() { return nullptr; }
  93
  94   virtual Function *CalculateSymbolContextFunction() { return nullptr; }
  95
  96   virtual Block *CalculateSymbolContextBlock() { return nullptr; }
  97
  98   virtual Symbol *CalculateSymbolContextSymbol() { return nullptr; }
  99
 100   //------------------------------------------------------------------
 101   /// Dump the object's symbol context to the stream \a s.
 102   ///
 103   /// The object should dump its symbol context to the stream \a s.
 104   /// This function is widely used in the DumpDebug and verbose output
 105   /// for lldb objects.
 106   ///
 107   /// @param[in] s
 108   ///     The stream to which to dump the object's symbol context.
 109   //------------------------------------------------------------------
 110   virtual void DumpSymbolContext(Stream *s) = 0;
 111 };
 112
 113 } // namespace lldb_private
 114
 115 #endif // liblldb_SymbolContextScope_h_