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
14namespace 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.
64class SymbolContextScope {
65public:
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