1 //===-- SymbolContextScope.h ------------------------------------*- C++ -*-===//
3 // The LLVM Compiler Infrastructure
5 // This file is distributed under the University of Illinois Open Source
6 // License. See LICENSE.TXT for details.
8 //===----------------------------------------------------------------------===//
10 #ifndef liblldb_SymbolContextScope_h_
11 #define liblldb_SymbolContextScope_h_
15 // Other libraries and framework includes
17 #include "lldb/lldb-private.h"
19 namespace lldb_private {
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.
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
34 /// Examples of these objects include:
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.
47 /// Example objects include that currently use "SymbolContextScope *"
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.
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 {
74 virtual ~SymbolContextScope() = default;
76 //------------------------------------------------------------------
77 /// Reconstruct the object's symbol context into \a sc.
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.
84 /// A symbol context object pointer that gets filled in.
85 //------------------------------------------------------------------
86 virtual void CalculateSymbolContext(SymbolContext *sc) = 0;
88 virtual lldb::ModuleSP CalculateSymbolContextModule() {
89 return lldb::ModuleSP();
92 virtual CompileUnit *CalculateSymbolContextCompileUnit() { return nullptr; }
94 virtual Function *CalculateSymbolContextFunction() { return nullptr; }
96 virtual Block *CalculateSymbolContextBlock() { return nullptr; }
98 virtual Symbol *CalculateSymbolContextSymbol() { return nullptr; }
100 //------------------------------------------------------------------
101 /// Dump the object's symbol context to the stream \a s.
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.
108 /// The stream to which to dump the object's symbol context.
109 //------------------------------------------------------------------
110 virtual void DumpSymbolContext(Stream *s) = 0;
113 } // namespace lldb_private
115 #endif // liblldb_SymbolContextScope_h_