llvm/lldb/include/lldb/Symbol/SymbolContextScope.h

//===-- SymbolContextScope.h ------------------------------------*- C++ -*-===//
//
// Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
// See https://llvm.org/LICENSE.txt for license information.
// SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
//
//===----------------------------------------------------------------------===//

#ifndef LLDB_SYMBOL_SYMBOLCONTEXTSCOPE_H
#define LLDB_SYMBOL_SYMBOLCONTEXTSCOPE_H

#include "lldb/lldb-private.h"

namespace lldb_private {

/// \class SymbolContextScope SymbolContextScope.h
/// "lldb/Symbol/SymbolContextScope.h" Inherit from this if your object is
/// part of a symbol context
///        and can reconstruct its symbol context.
///
/// Many objects that are part of a symbol context that have pointers back to
/// parent objects that own them. Any members of a symbol context that, once
/// they are built, will not go away, can inherit from this pure virtual class
/// and can then reconstruct their symbol context without having to keep a
/// complete SymbolContext object in the object.
///
/// Examples of these objects include:
///     \li Module
///     \li CompileUnit
///     \li Function
///     \li Block
///     \li Symbol
///
/// Other objects can store a "SymbolContextScope *" using any pointers to one
/// of the above objects. This allows clients to hold onto a pointer that
/// uniquely will identify a symbol context. Those clients can then always
/// reconstruct the symbol context using the pointer, or use it to uniquely
/// identify a symbol context for an object.
///
/// Example objects include that currently use "SymbolContextScope *" objects
/// include:
///     \li Variable objects that can reconstruct where they are scoped
///         by making sure the SymbolContextScope * comes from the scope
///         in which the variable was declared. If a variable is a global,
///         the appropriate CompileUnit * will be used when creating the
///         variable. A static function variables, can the Block scope
///         in which the variable is defined. Function arguments can use
///         the Function object as their scope. The SymbolFile parsers
///         will set these correctly as the variables are parsed.
///     \li Type objects that know exactly in which scope they
///         originated much like the variables above.
///     \li StackID objects that are able to know that if the CFA
///         (stack pointer at the beginning of a function) and the
///         start PC for the function/symbol and the SymbolContextScope
///         pointer (a unique pointer that identifies a symbol context
///         location) match within the same thread, that the stack
///         frame is the same as the previous stack frame.
///
/// Objects that adhere to this protocol can reconstruct enough of a symbol
/// context to allow functions that take a symbol context to be called. Lists
/// can also be created using a SymbolContextScope* and and object pairs that
/// allow large collections of objects to be passed around with minimal
/// overhead.
class SymbolContextScope { … };

} // namespace lldb_private

#endif // LLDB_SYMBOL_SYMBOLCONTEXTSCOPE_H