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 LLDB_SYMBOL_SYMBOLCONTEXTSCOPE_H 10 #define LLDB_SYMBOL_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 CalculateSymbolContextModule()78 virtual lldb::ModuleSP CalculateSymbolContextModule() { 79 return lldb::ModuleSP(); 80 } 81 CalculateSymbolContextCompileUnit()82 virtual CompileUnit *CalculateSymbolContextCompileUnit() { return nullptr; } 83 CalculateSymbolContextFunction()84 virtual Function *CalculateSymbolContextFunction() { return nullptr; } 85 CalculateSymbolContextBlock()86 virtual Block *CalculateSymbolContextBlock() { return nullptr; } 87 CalculateSymbolContextSymbol()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 // LLDB_SYMBOL_SYMBOLCONTEXTSCOPE_H 104