SymbolContextScope.h revision 254721 
1//===-- SymbolContextScope.h ------------------------------------*- C++ -*-===//
2//
3//                     The LLVM Compiler Infrastructure
4//
5// This file is distributed under the University of Illinois Open Source
6// License. See LICENSE.TXT for details.
7//
8//===----------------------------------------------------------------------===//
9
10#ifndef liblldb_SymbolContextScope_h_
11#define liblldb_SymbolContextScope_h_
12
13// C Includes
14// C++ Includes
15// Other libraries and framework includes
16// Project includes
17#include "lldb/lldb-private.h"
18
19namespace lldb_private {
20
21//----------------------------------------------------------------------
22/// @class SymbolContextScope SymbolContextScope.h "lldb/Symbol/SymbolContextScope.h"
23/// @brief Inherit from this if your object is part of a symbol context
24///        and can reconstruct its symbol context.
25///
26/// Many objects that are part of a symbol context that have pointers
27/// back to parent objects that own them. Any members of a symbol
28/// context that, once they are built, will not go away, can inherit
29/// from this pure virtual class and can then reconstruct their symbol
30/// context without having to keep a complete SymbolContext object in
31/// the object.
32///
33/// Examples of these objects include:
34///     @li Module
35///     @li CompileUnit
36///     @li Function
37///     @li Block
38///     @li Symbol
39///
40/// Other objects can store a "SymbolContextScope *" using any pointers
41/// to one of the above objects. This allows clients to hold onto a
42/// pointer that uniquely will identify a symbol context. Those clients
43/// can then always reconstruct the symbol context using the pointer, or
44/// use it to uniquely identify a symbol context for an object.
45///
46/// Example objects include that currently use "SymbolContextScope *"
47/// objects include:
48///     @li Variable objects that can reconstruct where they are scoped
49///         by making sure the SymbolContextScope * comes from the scope
50///         in which the variable was declared. If a variable is a global,
51///         the appropriate CompileUnit * will be used when creating the
52///         variable. A static function variables, can the Block scope
53///         in which the variable is defined. Function arguments can use
54///         the Function object as their scope. The SymbolFile parsers
55///         will set these correctly as the variables are parsed.
56///     @li Type objects that know exactly in which scope they
57///         originated much like the variables above.
58///     @li StackID objects that are able to know that if the CFA
59///         (stack pointer at the beginning of a function) and the
60///         start PC for the function/symbol and the SymbolContextScope
61///         pointer (a unique pointer that identifies a symbol context
62///         location) match within the same thread, that the stack
63///         frame is the same as the previous stack frame.
64///
65/// Objects that adhere to this protocol can reconstruct enough of a
66/// symbol context to allow functions that take a symbol context to be
67/// called. Lists can also be created using a SymbolContextScope* and
68/// and object pairs that allow large collections of objects to be
69/// passed around with minimal overhead.
70//----------------------------------------------------------------------
71class SymbolContextScope
72{
73public:
74    virtual
75    ~SymbolContextScope () {}
76
77    //------------------------------------------------------------------
78    /// Reconstruct the object's symbolc context into \a sc.
79    ///
80    /// The object should fill in as much of the SymbolContext as it
81    /// can so function calls that require a symbol context can be made
82    /// for the given object.
83    ///
84    /// @param[out] sc
85    ///     A symbol context object pointer that gets filled in.
86    //------------------------------------------------------------------
87    virtual void
88    CalculateSymbolContext (SymbolContext *sc) = 0;
89
90
91    virtual lldb::ModuleSP
92    CalculateSymbolContextModule ()
93    {
94        return lldb::ModuleSP();
95    }
96
97    virtual CompileUnit *
98    CalculateSymbolContextCompileUnit ()
99    {
100        return NULL;
101    }
102
103    virtual Function *
104    CalculateSymbolContextFunction ()
105    {
106        return NULL;
107    }
108
109    virtual Block *
110    CalculateSymbolContextBlock ()
111    {
112        return NULL;
113    }
114
115    virtual Symbol *
116    CalculateSymbolContextSymbol ()
117    {
118        return NULL;
119    }
120
121    //------------------------------------------------------------------
122    /// Dump the object's symbolc context to the stream \a s.
123    ///
124    /// The object should dump its symbol context to the stream \a s.
125    /// This function is widely used in the DumpDebug and verbose output
126    /// for lldb objets.
127    ///
128    /// @param[in] s
129    ///     The stream to which to dump the object's symbol context.
130    //------------------------------------------------------------------
131    virtual void
132    DumpSymbolContext (Stream *s) = 0;
133};
134
135} // namespace lldb_private
136
137#endif  // liblldb_SymbolContextScope_h_
138