psystem::dbghelp_symbol_engine Class Reference

Provide an facility (using DbgHelp) for reading and mapping debugger symbols. More...

#include <dbghelp_symbol_engine.hpp>

Inheritance diagram for psystem::dbghelp_symbol_engine:

Collaboration diagram for psystem::dbghelp_symbol_engine:

Construction / Destruction
	dbghelp_symbol_engine (HANDLE h_process)
	Construct an instance of the symbol engine. More...
	~dbghelp_symbol_engine ()
	Free previously allocated resources for debug symbol usage. More...

Public Interface
std::unique_ptr< symbol >	find_symbol (address_t address)
	Create a psystem::symbol instance for a symbol at the provided memory address. More...

Member Data
HANDLE const	m_process_handle
	An open handle to the process used to gather symbol information.

Additional Inherited Members
Protected Member Functions inherited from psystem::not_copyable
	not_copyable (not_copyable const &)=delete
	Delete the copy constructor.
not_copyable &	operator= (not_copyable const &)=delete
	Delete the assignment operator.
constexpr	not_copyable () noexcept
	A simple CTOR suitable for noexcept and constexpr uses.
	~not_copyable () noexcept
	A simple CTOR suitable for noexcept uses.

Detailed Description

Provide an facility (using DbgHelp) for reading and mapping debugger symbols.

The DbgHelp library is a Windows-specific library for reading debugging symbols, mapping them to addresses, and even gathering source code locations where available. This interface encapsulates the library for use with the rest of the PSystem modules.

A governing philosophy of symbol engines in psystem is that they do not maintain any stateful information for the symbols themselves, they only provide a consistent facade for one or more symbol APIs.

Warning

According to the DbgHelp documentation, most all of the functions are single-threaded. Avoid accessing the methods here from multiple threads without some serialization strategy.

Author

Matt Bisson

Date

5 August, 2014

Since

PSystem 2.0

Version

PSystem 2.0

Constructor & Destructor Documentation

psystem::dbghelp_symbol_engine::dbghelp_symbol_engine ( HANDLE  h_process )

explicit

Construct an instance of the symbol engine.

Warning

Creating multiple instances of dbghelp_symbol_engine with the same process handle will result in undefined behavior.

Parameters

[in]

h_process

An open handle to the process for which symbols should be loaded.

Exceptions

psystem::exception::system_exception

If there was an error initializing the DbgHelp symbol server with the given process handle.

Todo:

Track process handles and throw an exception if the same one is accessed twice.

Todo:

This should be an except

Todo:

In order to not "invade process = TRUE" we need to replace the callbacks in StackWalk.

Todo:

Custom search path for symbols?

psystem::dbghelp_symbol_engine::~dbghelp_symbol_engine

(

)

Free previously allocated resources for debug symbol usage.

Todo:

Replace this when we have a logging facility.

Member Function Documentation

std::unique_ptr< symbol > psystem::dbghelp_symbol_engine::find_symbol

(

address_t

address

)

Create a psystem::symbol instance for a symbol at the provided memory address.

This is a factory method. After calling this method, ownership is transferred directly to the caller. Invoking this multiple times with the same address results in multiple symbol instances. It is not idempotent.

Parameters

[in]

address

The address to match to a debugger symbol.

Returns

If a symbol is found, this method returns a std::unique_ptr to a new instance of psystem::symbol with the information. If not, this method returns nullptr.

Exceptions

psystem::exception::system_exception

If there was a system error accessing the symbol from DbgHelp.

Todo:

Probably don't want to do this on the stack. In fact, since this is single-threaded, we might just allocate a static buffer?

Todo:

Strange to return an unique_ptr here...

---

The documentation for this class was generated from the following files:

• include/psystem/dbghelp_symbol_engine.hpp
• src/psystem/dbghelp_symbol_engine.cpp