1254721Semaste//===-- SymbolContextScope.h ------------------------------------*- C++ -*-===// 2254721Semaste// 3353358Sdim// Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions. 4353358Sdim// See https://llvm.org/LICENSE.txt for license information. 5353358Sdim// SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception 6254721Semaste// 7254721Semaste//===----------------------------------------------------------------------===// 8254721Semaste 9254721Semaste#ifndef liblldb_SymbolContextScope_h_ 10254721Semaste#define liblldb_SymbolContextScope_h_ 11254721Semaste 12254721Semaste#include "lldb/lldb-private.h" 13254721Semaste 14254721Semastenamespace lldb_private { 15254721Semaste 16353358Sdim/// \class SymbolContextScope SymbolContextScope.h 17341825Sdim/// "lldb/Symbol/SymbolContextScope.h" Inherit from this if your object is 18341825Sdim/// part of a symbol context 19254721Semaste/// and can reconstruct its symbol context. 20254721Semaste/// 21341825Sdim/// Many objects that are part of a symbol context that have pointers back to 22341825Sdim/// parent objects that own them. Any members of a symbol context that, once 23341825Sdim/// they are built, will not go away, can inherit from this pure virtual class 24341825Sdim/// and can then reconstruct their symbol context without having to keep a 25341825Sdim/// complete SymbolContext object in the object. 26254721Semaste/// 27254721Semaste/// Examples of these objects include: 28353358Sdim/// \li Module 29353358Sdim/// \li CompileUnit 30353358Sdim/// \li Function 31353358Sdim/// \li Block 32353358Sdim/// \li Symbol 33254721Semaste/// 34341825Sdim/// Other objects can store a "SymbolContextScope *" using any pointers to one 35341825Sdim/// of the above objects. This allows clients to hold onto a pointer that 36341825Sdim/// uniquely will identify a symbol context. Those clients can then always 37341825Sdim/// reconstruct the symbol context using the pointer, or use it to uniquely 38341825Sdim/// identify a symbol context for an object. 39254721Semaste/// 40341825Sdim/// Example objects include that currently use "SymbolContextScope *" objects 41341825Sdim/// include: 42353358Sdim/// \li Variable objects that can reconstruct where they are scoped 43254721Semaste/// by making sure the SymbolContextScope * comes from the scope 44254721Semaste/// in which the variable was declared. If a variable is a global, 45254721Semaste/// the appropriate CompileUnit * will be used when creating the 46254721Semaste/// variable. A static function variables, can the Block scope 47254721Semaste/// in which the variable is defined. Function arguments can use 48254721Semaste/// the Function object as their scope. The SymbolFile parsers 49254721Semaste/// will set these correctly as the variables are parsed. 50353358Sdim/// \li Type objects that know exactly in which scope they 51254721Semaste/// originated much like the variables above. 52353358Sdim/// \li StackID objects that are able to know that if the CFA 53314564Sdim/// (stack pointer at the beginning of a function) and the 54254721Semaste/// start PC for the function/symbol and the SymbolContextScope 55314564Sdim/// pointer (a unique pointer that identifies a symbol context 56254721Semaste/// location) match within the same thread, that the stack 57254721Semaste/// frame is the same as the previous stack frame. 58254721Semaste/// 59341825Sdim/// Objects that adhere to this protocol can reconstruct enough of a symbol 60341825Sdim/// context to allow functions that take a symbol context to be called. Lists 61341825Sdim/// can also be created using a SymbolContextScope* and and object pairs that 62341825Sdim/// allow large collections of objects to be passed around with minimal 63341825Sdim/// overhead. 64314564Sdimclass SymbolContextScope { 65254721Semastepublic: 66314564Sdim virtual ~SymbolContextScope() = default; 67254721Semaste 68314564Sdim /// Reconstruct the object's symbol context into \a sc. 69314564Sdim /// 70341825Sdim /// The object should fill in as much of the SymbolContext as it can so 71341825Sdim /// function calls that require a symbol context can be made for the given 72341825Sdim /// object. 73314564Sdim /// 74353358Sdim /// \param[out] sc 75314564Sdim /// A symbol context object pointer that gets filled in. 76314564Sdim virtual void CalculateSymbolContext(SymbolContext *sc) = 0; 77254721Semaste 78314564Sdim virtual lldb::ModuleSP CalculateSymbolContextModule() { 79314564Sdim return lldb::ModuleSP(); 80314564Sdim } 81254721Semaste 82314564Sdim virtual CompileUnit *CalculateSymbolContextCompileUnit() { return nullptr; } 83254721Semaste 84314564Sdim virtual Function *CalculateSymbolContextFunction() { return nullptr; } 85254721Semaste 86314564Sdim virtual Block *CalculateSymbolContextBlock() { return nullptr; } 87254721Semaste 88314564Sdim virtual Symbol *CalculateSymbolContextSymbol() { return nullptr; } 89254721Semaste 90314564Sdim /// Dump the object's symbol context to the stream \a s. 91314564Sdim /// 92341825Sdim /// The object should dump its symbol context to the stream \a s. This 93341825Sdim /// function is widely used in the DumpDebug and verbose output for lldb 94341825Sdim /// objects. 95314564Sdim /// 96353358Sdim /// \param[in] s 97314564Sdim /// The stream to which to dump the object's symbol context. 98314564Sdim virtual void DumpSymbolContext(Stream *s) = 0; 99254721Semaste}; 100254721Semaste 101254721Semaste} // namespace lldb_private 102254721Semaste 103296417Sdim#endif // liblldb_SymbolContextScope_h_ 104