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 | |
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 // LLDB_SYMBOL_SYMBOLCONTEXTSCOPE_H |
104 | |