class Symbol
Defined at line 90 of file ../../src/developer/debug/zxdb/symbols/symbol.h
Represents the type of a variable. This is a deserialized version of the various DWARF DIEs
("Debug Information Entry" -- a record in the DWARF file) that define types.
SYMBOL MEMORY MODEL
-------------------
Symbols are reference counted and have references to other Symbols via a LazySymbol object which
allows lazy decoding of the DWARF data. These are not cached or re-used so we can get many
duplicate Symbol objects for the same DIE. Therefore, Symbol object identity is not a way to
compare two symbols. Even if these were unified, DWARF will often encode the same thing in each
compilation unit it is needed in, so object identity can never work in DWARF context.
This non-caching behavior is important to prevent reference cycles that would cause memory leaks.
Not only does each symbol reference its parent, there are complex and almost-arbitrary links
between DIEs that don't work well with the reference-counting used by symbols.
A downside to this design is that we might decode the same symbol multiple times and end up with
many copies of the same data, both of which are inefficient.
The main alternative would be to remove reference counting and instead maintain a per-module
mapping of DIE address to decoded symbols. Then links between Symbol objects can either be DIE
addresses that are looked up in the module every time they're needed (lets the module free things
that haven't been used in a while) or object pointers (avoids the intermediate lookup but means
objects can never be freed without unloading the whole module). This scheme would mean that
symbols will be freed when the module is removed, which will require weak pointers from the
expression system.
DIE ADDRESSES AND COMPILATION UNITS
-----------------------------------
In LLVM a DIE is indexed by its llvm::DWARFUnit and an offset within that. In contrast, our
LazySymbols use a single global index which is converted to a unit/offset as needed. Once we
decode a DIE, we don't need the offset at all, and we never needed the unit, so there are not
available.
If we find we need this information on each symbol in the future, it could be added. We would
want to add some caching system since currently make duplicate DwarfUnit objects for the same
LLVM One.
Currently the DwarfUnit is accessible by waking up the tree to the CompileUnit. The CompileUnit
stores a DwarfUnit pointer. Note that the CompileUnit is a DIE symbol while the DwarfUnit is the
container for the CompileUnit and everything else associated with an object file. Many offsets
in the symbols are relative to the DwarfUnit (note the main die_offset() is module-global).
Public Methods
LazySymbol GetLazySymbol ()Returns a lazy reference to this symbol. When creating LazySymbols, be sure not to store it
in such a way that it could create a reference cycle (so do not save it in any children of
this symbol or in anything it references).
Note that we don't provide a GetUncachedLazySymbol() variant. That would be easy but is not
currently needed and it's potentially slightly dangerous. The uncached variants are used to
avoid reference cycles, but if we have a test object, it will contain a hard reference. The
tests use some helpers to clean this up safely (the SymbolTestParentSetter). Returning an
UncachedLazySymbol here may create the impression that it can be used in a "parent" context
while this would not be safe for test data.
Defined at line 20 of file ../../src/developer/debug/zxdb/symbols/symbol.cc
uint64_t GetDieOffset ()Global offset of this symbol within the module. This can be 0 for most symbols created in tests
and for synthetic symbols like the built-in "int" type generated by the expression system.
This is mostly useful when doing low-level symbol operations and interacting with LLVM.
This offset is set by set_lazy_this().
Defined at line 29 of file ../../src/developer/debug/zxdb/symbols/symbol.cc
const std::string & GetAssignedName ()Returns the name associated with this symbol. This name comes from the corresponding record in
the DWARF format (hence "assigned"). It will NOT include namespace and struct qualifiers.
Anything without a name assigned on the particular DWARF record name will return an empty
string, even if that thing logically has a name that can be computed (as for ModifiedType).
This default implementation returns a reference to an empty string. Derived classes will
override as needed.
Most callers will want to use GetFullName().
Defined at line 35 of file ../../src/developer/debug/zxdb/symbols/symbol.cc
const std::string & GetFullName ()Returns the full user-visible name for this symbol. This will include all namespace and struct
qualifications, and will include things like const and "*" qualifiers on modified types.
It will not include a global qualifier ("::" at the beginning) because that's not desired in
most uses. If your use-case cares about controlling this, use GetIdentifier().
This implements caching. Derived classes override ComputeFullName() to control how the full
name is presented.
See also GetIdentifier().
Defined at line 40 of file ../../src/developer/debug/zxdb/symbols/symbol.cc
const Identifier & GetIdentifier ()Returns the name of this symbol as an identifier if possible.
Many symbols have identifier names, this normally includes anything with an assigned name:
functions, structs, typedefs and base types.
Some things don't have names that can be made into identifiers, this includes modified types
such as "const Foo*" since the "const" and the "*" don't fit into the normal identifier scheme.
These types will report an empty Identifier for GetIdentifier().
See also GetFullName(). GetFullName() will work for the modified type cases above since it just
returns a string, but it's not parseable.
Defined at line 46 of file ../../src/developer/debug/zxdb/symbols/symbol.cc
fxl::RefPtr<CompileUnit> GetCompileUnit ()Returns the DwarfUnit or CompileUnit that this symbol is associated with. Returns null on
failure. See the comment at the top of this class and above the DwarfUnit declaration for more.
Defined at line 52 of file ../../src/developer/debug/zxdb/symbols/symbol.cc
fxl::RefPtr<DwarfUnit> GetDwarfUnit ()Defined at line 75 of file ../../src/developer/debug/zxdb/symbols/symbol.cc
fxl::WeakPtr<ModuleSymbols> GetModuleSymbols ()Returns the module symbols associated with this symbol object. It can be null if the module
has been unloaded and there are still dangling references to symbols, and it can also be null
in some test situations.
Defined at line 82 of file ../../src/developer/debug/zxdb/symbols/symbol.cc
SymbolContext GetSymbolContext (const ProcessSymbols * process_symbols)Returns the symbol context for this symbol in the given process. This requires the process so
it can look up what the module load address is for this symbol's module (the same module can be
loaded into multiple processes).
The ProcessSymbols can be null. It will be treated as an invalid module (see below).
The module may not be valid. It could have been unloaded while there were dangling symbols,
or it can be null in some test situations. In these cases the resulting symbol context will
be a "relative" context -- see SymbolContext::is_relative().
Defined at line 89 of file ../../src/developer/debug/zxdb/symbols/symbol.cc
DwarfLang GetLanguage ()Computes and returns the language associated with this symbol. This will be kNone if the
language is not known or unset.
This requires decoding the compile unit so is not super efficient to get.
Defined at line 104 of file ../../src/developer/debug/zxdb/symbols/symbol.cc
template <typename Derived>const Derived * As ()Allows templatized conversion to a base class. Both const and non-const variants are supported
using the protected virtual functions below. This is basically dynamic_cast but we're required
to avoid compiling with RTTI.
const Collection* c = symbol->As
<Collection
>();
if (!c)
return false;
template <typename Derived>Derived * As ()void set_lazy_this (UncachedLazySymbol lazy)Sets the symbol factory pointer and DIE offset for this symbol (returned by GetDieOffset() and
GetLazySymbol(), see those for more).
It would intuitively make the most sense for this to be set in the constructor since it's a
fundamental property of the symbol.
The majority of symbols in production are created by the DwarfSymbolFactory, but the majority
of call sites that create symbols (by ~2 orders of magnitude) are tests. Defaulting the
factory/offset info and having a setter allows the DwarfSymbolFactory to set them while keeping
the test call sites cleaner.
Defined at line 114 of file ../../src/developer/debug/zxdb/symbols/symbol.h
DwarfTag tag ()Defined at line 123 of file ../../src/developer/debug/zxdb/symbols/symbol.h
const UncachedLazySymbol & parent ()The parent symbol.
Normally this is the symbol that contains this one in the symbol file.
In the case of function implementations with separate definitions, this will be the lexical
parent of the function (for example, a class or namespace) rather than the one containing the
code. This is how callers can navigate the type tree but it means the parent won't match the
record in the DWARF file.
For inline functions, it's important to know both the lexical scope which tells you the
class/namespace of the function being inlined (the parent()) as well as the function it's
inlined into. Function symbols have a special containing_block() to give the latter.
Defined at line 137 of file ../../src/developer/debug/zxdb/symbols/symbol.h
void set_parent (const UncachedLazySymbol & e)Defined at line 138 of file ../../src/developer/debug/zxdb/symbols/symbol.h
template <>const ArrayType * As<zxdb::ArrayType> ()Defined at line 229 of file ../../src/developer/debug/zxdb/symbols/symbol.h
template <>ArrayType * As<zxdb::ArrayType> ()Defined at line 229 of file ../../src/developer/debug/zxdb/symbols/symbol.h
template <>const BaseType * As<zxdb::BaseType> ()Defined at line 230 of file ../../src/developer/debug/zxdb/symbols/symbol.h
template <>BaseType * As<zxdb::BaseType> ()Defined at line 230 of file ../../src/developer/debug/zxdb/symbols/symbol.h
template <>const CallSite * As<zxdb::CallSite> ()Defined at line 231 of file ../../src/developer/debug/zxdb/symbols/symbol.h
template <>CallSite * As<zxdb::CallSite> ()Defined at line 231 of file ../../src/developer/debug/zxdb/symbols/symbol.h
template <>const CallSiteParameter * As<zxdb::CallSiteParameter> ()Defined at line 232 of file ../../src/developer/debug/zxdb/symbols/symbol.h
template <>CallSiteParameter * As<zxdb::CallSiteParameter> ()Defined at line 232 of file ../../src/developer/debug/zxdb/symbols/symbol.h
template <>const CodeBlock * As<zxdb::CodeBlock> ()Defined at line 233 of file ../../src/developer/debug/zxdb/symbols/symbol.h
template <>CodeBlock * As<zxdb::CodeBlock> ()Defined at line 233 of file ../../src/developer/debug/zxdb/symbols/symbol.h
template <>const Collection * As<zxdb::Collection> ()Defined at line 234 of file ../../src/developer/debug/zxdb/symbols/symbol.h
template <>Collection * As<zxdb::Collection> ()Defined at line 234 of file ../../src/developer/debug/zxdb/symbols/symbol.h
template <>const CompileUnit * As<zxdb::CompileUnit> ()Defined at line 235 of file ../../src/developer/debug/zxdb/symbols/symbol.h
template <>CompileUnit * As<zxdb::CompileUnit> ()Defined at line 235 of file ../../src/developer/debug/zxdb/symbols/symbol.h
template <>DataMember * As<zxdb::DataMember> ()Defined at line 236 of file ../../src/developer/debug/zxdb/symbols/symbol.h
template <>const DataMember * As<zxdb::DataMember> ()Defined at line 236 of file ../../src/developer/debug/zxdb/symbols/symbol.h
template <>const ElfSymbol * As<zxdb::ElfSymbol> ()Defined at line 237 of file ../../src/developer/debug/zxdb/symbols/symbol.h
template <>ElfSymbol * As<zxdb::ElfSymbol> ()Defined at line 237 of file ../../src/developer/debug/zxdb/symbols/symbol.h
template <>Enumeration * As<zxdb::Enumeration> ()Defined at line 238 of file ../../src/developer/debug/zxdb/symbols/symbol.h
template <>const Enumeration * As<zxdb::Enumeration> ()Defined at line 238 of file ../../src/developer/debug/zxdb/symbols/symbol.h
template <>Function * As<zxdb::Function> ()Defined at line 239 of file ../../src/developer/debug/zxdb/symbols/symbol.h
template <>const Function * As<zxdb::Function> ()Defined at line 239 of file ../../src/developer/debug/zxdb/symbols/symbol.h
template <>FunctionType * As<zxdb::FunctionType> ()Defined at line 240 of file ../../src/developer/debug/zxdb/symbols/symbol.h
template <>const FunctionType * As<zxdb::FunctionType> ()Defined at line 240 of file ../../src/developer/debug/zxdb/symbols/symbol.h
template <>InheritedFrom * As<zxdb::InheritedFrom> ()Defined at line 241 of file ../../src/developer/debug/zxdb/symbols/symbol.h
template <>const InheritedFrom * As<zxdb::InheritedFrom> ()Defined at line 241 of file ../../src/developer/debug/zxdb/symbols/symbol.h
template <>const MemberPtr * As<zxdb::MemberPtr> ()Defined at line 242 of file ../../src/developer/debug/zxdb/symbols/symbol.h
template <>MemberPtr * As<zxdb::MemberPtr> ()Defined at line 242 of file ../../src/developer/debug/zxdb/symbols/symbol.h
template <>ModifiedType * As<zxdb::ModifiedType> ()Defined at line 243 of file ../../src/developer/debug/zxdb/symbols/symbol.h
template <>const ModifiedType * As<zxdb::ModifiedType> ()Defined at line 243 of file ../../src/developer/debug/zxdb/symbols/symbol.h
template <>Namespace * As<zxdb::Namespace> ()Defined at line 244 of file ../../src/developer/debug/zxdb/symbols/symbol.h
template <>const Namespace * As<zxdb::Namespace> ()Defined at line 244 of file ../../src/developer/debug/zxdb/symbols/symbol.h
template <>TemplateParameter * As<zxdb::TemplateParameter> ()Defined at line 245 of file ../../src/developer/debug/zxdb/symbols/symbol.h
template <>const TemplateParameter * As<zxdb::TemplateParameter> ()Defined at line 245 of file ../../src/developer/debug/zxdb/symbols/symbol.h
template <>Type * As<zxdb::Type> ()Defined at line 246 of file ../../src/developer/debug/zxdb/symbols/symbol.h
template <>const Type * As<zxdb::Type> ()Defined at line 246 of file ../../src/developer/debug/zxdb/symbols/symbol.h
template <>Value * As<zxdb::Value> ()Defined at line 247 of file ../../src/developer/debug/zxdb/symbols/symbol.h
template <>const Value * As<zxdb::Value> ()Defined at line 247 of file ../../src/developer/debug/zxdb/symbols/symbol.h
template <>Variable * As<zxdb::Variable> ()Defined at line 248 of file ../../src/developer/debug/zxdb/symbols/symbol.h
template <>const Variable * As<zxdb::Variable> ()Defined at line 248 of file ../../src/developer/debug/zxdb/symbols/symbol.h
template <>Variant * As<zxdb::Variant> ()Defined at line 249 of file ../../src/developer/debug/zxdb/symbols/symbol.h
template <>const Variant * As<zxdb::Variant> ()Defined at line 249 of file ../../src/developer/debug/zxdb/symbols/symbol.h
template <>VariantPart * As<zxdb::VariantPart> ()Defined at line 250 of file ../../src/developer/debug/zxdb/symbols/symbol.h
template <>const VariantPart * As<zxdb::VariantPart> ()Defined at line 250 of file ../../src/developer/debug/zxdb/symbols/symbol.h
Protected Methods
void Symbol ()Construct via fxl::MakeRefCounted.
Defined at line 16 of file ../../src/developer/debug/zxdb/symbols/symbol.cc
void Symbol (DwarfTag tag)Defined at line 17 of file ../../src/developer/debug/zxdb/symbols/symbol.cc
void ~Symbol ()Defined at line 18 of file ../../src/developer/debug/zxdb/symbols/symbol.cc
const ArrayType * AsArrayType ()Manual RTTI. See "As<...>" template above for the public versions (these are protected just
so callers are consistent).
Defined at line 110 of file ../../src/developer/debug/zxdb/symbols/symbol.cc
const BaseType * AsBaseType ()Defined at line 111 of file ../../src/developer/debug/zxdb/symbols/symbol.cc
const CallSite * AsCallSite ()Defined at line 112 of file ../../src/developer/debug/zxdb/symbols/symbol.cc
const CallSiteParameter * AsCallSiteParameter ()Defined at line 113 of file ../../src/developer/debug/zxdb/symbols/symbol.cc
const CodeBlock * AsCodeBlock ()Defined at line 114 of file ../../src/developer/debug/zxdb/symbols/symbol.cc
const Collection * AsCollection ()Defined at line 116 of file ../../src/developer/debug/zxdb/symbols/symbol.cc
const CompileUnit * AsCompileUnit ()Defined at line 115 of file ../../src/developer/debug/zxdb/symbols/symbol.cc
const DataMember * AsDataMember ()Defined at line 117 of file ../../src/developer/debug/zxdb/symbols/symbol.cc
const ElfSymbol * AsElfSymbol ()Defined at line 118 of file ../../src/developer/debug/zxdb/symbols/symbol.cc
const Enumeration * AsEnumeration ()Defined at line 119 of file ../../src/developer/debug/zxdb/symbols/symbol.cc
const Function * AsFunction ()Defined at line 120 of file ../../src/developer/debug/zxdb/symbols/symbol.cc
const FunctionType * AsFunctionType ()Defined at line 121 of file ../../src/developer/debug/zxdb/symbols/symbol.cc
const InheritedFrom * AsInheritedFrom ()Defined at line 122 of file ../../src/developer/debug/zxdb/symbols/symbol.cc
const MemberPtr * AsMemberPtr ()Defined at line 123 of file ../../src/developer/debug/zxdb/symbols/symbol.cc
const ModifiedType * AsModifiedType ()Defined at line 124 of file ../../src/developer/debug/zxdb/symbols/symbol.cc
const Namespace * AsNamespace ()Defined at line 125 of file ../../src/developer/debug/zxdb/symbols/symbol.cc
const TemplateParameter * AsTemplateParameter ()Defined at line 126 of file ../../src/developer/debug/zxdb/symbols/symbol.cc
const Type * AsType ()Defined at line 127 of file ../../src/developer/debug/zxdb/symbols/symbol.cc
const Value * AsValue ()Defined at line 128 of file ../../src/developer/debug/zxdb/symbols/symbol.cc
const Variable * AsVariable ()Defined at line 129 of file ../../src/developer/debug/zxdb/symbols/symbol.cc
const Variant * AsVariant ()Defined at line 130 of file ../../src/developer/debug/zxdb/symbols/symbol.cc
const VariantPart * AsVariantPart ()Defined at line 131 of file ../../src/developer/debug/zxdb/symbols/symbol.cc
std::string ComputeFullName ()Computes the full name and identifier. Used by GetFullName() and GetIdentifier() which add a
caching layer.
Derived classes should override these to control how the name is presented. The default
implementation of ComputeIdentifier() returns the scope prefix (namespaces, structs) + the
assigned name. The default implementation of ComputeFullName() returns the stringified version
of the identifier.
The returned Identifier should be globally qualified.
Defined at line 133 of file ../../src/developer/debug/zxdb/symbols/symbol.cc
Identifier ComputeIdentifier ()Defined at line 135 of file ../../src/developer/debug/zxdb/symbols/symbol.cc
Friends
class MakeRefCountedHelperclass RefCountedThreadSafeclass LazySymbol