lldb/Symbol/SymbolContextScope.h

0001 //===-- SymbolContextScope.h ------------------------------------*- C++ -*-===//
0002 //
0003 // Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
0004 // See https://llvm.org/LICENSE.txt for license information.
0005 // SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
0006 //
0007 //===----------------------------------------------------------------------===//
0008
0009 #ifndef LLDB_SYMBOL_SYMBOLCONTEXTSCOPE_H
0010 #define LLDB_SYMBOL_SYMBOLCONTEXTSCOPE_H
0011
0012 #include "lldb/lldb-private.h"
0013
0014 namespace lldb_private {
0015
0016 /// \class SymbolContextScope SymbolContextScope.h
0017 /// "lldb/Symbol/SymbolContextScope.h" Inherit from this if your object is
0018 /// part of a symbol context
0019 ///        and can reconstruct its symbol context.
0020 ///
0021 /// Many objects that are part of a symbol context that have pointers back to
0022 /// parent objects that own them. Any members of a symbol context that, once
0023 /// they are built, will not go away, can inherit from this pure virtual class
0024 /// and can then reconstruct their symbol context without having to keep a
0025 /// complete SymbolContext object in the object.
0026 ///
0027 /// Examples of these objects include:
0028 ///     \li Module
0029 ///     \li CompileUnit
0030 ///     \li Function
0031 ///     \li Block
0032 ///     \li Symbol
0033 ///
0034 /// Other objects can store a "SymbolContextScope *" using any pointers to one
0035 /// of the above objects. This allows clients to hold onto a pointer that
0036 /// uniquely will identify a symbol context. Those clients can then always
0037 /// reconstruct the symbol context using the pointer, or use it to uniquely
0038 /// identify a symbol context for an object.
0039 ///
0040 /// Example objects include that currently use "SymbolContextScope *" objects
0041 /// include:
0042 ///     \li Variable objects that can reconstruct where they are scoped
0043 ///         by making sure the SymbolContextScope * comes from the scope
0044 ///         in which the variable was declared. If a variable is a global,
0045 ///         the appropriate CompileUnit * will be used when creating the
0046 ///         variable. A static function variables, can the Block scope
0047 ///         in which the variable is defined. Function arguments can use
0048 ///         the Function object as their scope. The SymbolFile parsers
0049 ///         will set these correctly as the variables are parsed.
0050 ///     \li Type objects that know exactly in which scope they
0051 ///         originated much like the variables above.
0052 ///     \li StackID objects that are able to know that if the CFA
0053 ///         (stack pointer at the beginning of a function) and the
0054 ///         start PC for the function/symbol and the SymbolContextScope
0055 ///         pointer (a unique pointer that identifies a symbol context
0056 ///         location) match within the same thread, that the stack
0057 ///         frame is the same as the previous stack frame.
0058 ///
0059 /// Objects that adhere to this protocol can reconstruct enough of a symbol
0060 /// context to allow functions that take a symbol context to be called. Lists
0061 /// can also be created using a SymbolContextScope* and and object pairs that
0062 /// allow large collections of objects to be passed around with minimal
0063 /// overhead.
0064 class SymbolContextScope {
0065 public:
0066   virtual ~SymbolContextScope() = default;
0067
0068   /// Reconstruct the object's symbol context into \a sc.
0069   ///
0070   /// The object should fill in as much of the SymbolContext as it can so
0071   /// function calls that require a symbol context can be made for the given
0072   /// object.
0073   ///
0074   /// \param[out] sc
0075   ///     A symbol context object pointer that gets filled in.
0076   virtual void CalculateSymbolContext(SymbolContext *sc) = 0;
0077
0078   virtual lldb::ModuleSP CalculateSymbolContextModule() {
0079     return lldb::ModuleSP();
0080   }
0081
0082   virtual CompileUnit *CalculateSymbolContextCompileUnit() { return nullptr; }
0083
0084   virtual Function *CalculateSymbolContextFunction() { return nullptr; }
0085
0086   virtual Block *CalculateSymbolContextBlock() { return nullptr; }
0087
0088   virtual Symbol *CalculateSymbolContextSymbol() { return nullptr; }
0089
0090   /// Dump the object's symbol context to the stream \a s.
0091   ///
0092   /// The object should dump its symbol context to the stream \a s. This
0093   /// function is widely used in the DumpDebug and verbose output for lldb
0094   /// objects.
0095   ///
0096   /// \param[in] s
0097   ///     The stream to which to dump the object's symbol context.
0098   virtual void DumpSymbolContext(Stream *s) = 0;
0099 };
0100
0101 } // namespace lldb_private
0102
0103 #endif // LLDB_SYMBOL_SYMBOLCONTEXTSCOPE_H