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

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