PStack  2.0
Stack trace printer for MSVC and GCC binaries
List of all members
proclib::base_debug_event_listener Class Reference

A polymorphic interface for detecting events received by the debugger. More...

#include <base_debug_event_listener.hpp>

Inheritance diagram for proclib::base_debug_event_listener:
Inheritance graph
[legend]

Construction / Destruction

virtual ~base_debug_event_listener () noexcept
 Clean up base_debug_event_listener resources.
 
 base_debug_event_listener () noexcept
 Construct the base_debug_event_listener instance. More...
 

Public Interface

virtual bool create_process_event (psystem::process_id_t pid, psystem::thread_id_t tid, psystem::shared_handle<> const &file_handle, CREATE_PROCESS_DEBUG_INFO const &info) noexcept
 Invoked when the debugger sends an event to indicate process creation. More...
 
virtual bool create_thread_event (psystem::process_id_t pid, psystem::thread_id_t tid, CREATE_THREAD_DEBUG_INFO const &info) noexcept
 Invoked when the debugger sends an event to indicate thread creation. More...
 
virtual bool exception_event (psystem::process_id_t pid, psystem::thread_id_t tid, EXCEPTION_DEBUG_INFO const &info) noexcept
 Invoked when the debugger sends an event to indicate some exception in normal process execution. More...
 
virtual bool exit_process_event (psystem::process_id_t pid, psystem::thread_id_t tid, EXIT_PROCESS_DEBUG_INFO const &info) noexcept
 Invoked when the debugger sends an event to indicate that the process has exited. More...
 
virtual bool exit_thread_event (psystem::process_id_t pid, psystem::thread_id_t tid, EXIT_THREAD_DEBUG_INFO const &info) noexcept
 Invoked when the debugger sends an event to indicate that a thread has exited. More...
 
virtual bool load_dll_event (psystem::process_id_t pid, psystem::thread_id_t tid, psystem::shared_handle<> const &file_handle, LOAD_DLL_DEBUG_INFO const &info) noexcept
 Invoked when the debugger sends an event to indicate that a DLL hase been loaded. More...
 
virtual bool output_debug_string_event (psystem::process_id_t pid, psystem::thread_id_t tid, OUTPUT_DEBUG_STRING_INFO const &info) noexcept
 Invoked when the debugger encounters a trace message from the debuggee. More...
 
virtual bool rip_event (psystem::process_id_t pid, psystem::thread_id_t tid, RIP_INFO const &info) noexcept
 Invoked when the debugger encounters a fatal application exit or debugger error. More...
 
virtual bool unload_dll_event (psystem::process_id_t pid, psystem::thread_id_t tid, UNLOAD_DLL_DEBUG_INFO const &info) noexcept
 Invoked when the debugger encounters a DLL unload. More...
 

Detailed Description

A polymorphic interface for detecting events received by the debugger.

It is not possible to use this interface directly to listen for debugging events, but it does provide a default implementation for derived classes whereby the event is ignored.

To handle an event, derived classes should override one of the methods described by base_debug_event_listener's interface, and return true as the result. No exceptions may be thrown from an event handler.

Author
Matt Bisson
Date
5 August, 2014
Since
ProcLib 2.0
Version
ProcLib 2.0

Constructor & Destructor Documentation

proclib::base_debug_event_listener::base_debug_event_listener ( )
protectednoexcept

Construct the base_debug_event_listener instance.

The constructor is protected because it is essentially pointless to create (and register) an instance of the base listener.

Member Function Documentation

bool proclib::base_debug_event_listener::create_process_event ( psystem::process_id_t  pid,
psystem::thread_id_t  tid,
psystem::shared_handle<> const &  file_handle,
CREATE_PROCESS_DEBUG_INFO const &  info 
)
virtualnoexcept

Invoked when the debugger sends an event to indicate process creation.

This events is sent upon attachment to a running process, or when the debugger itself creates a process for debugging. This event is important also because it signifies that the executable module has been loaded, and that the main process thread has been created.

Parameters
[in]pidThe ID of the process that signaled this event.
[in]tidThe ID of the thread that is currently in the active state.
[in]file_handleThe "shared" handle to the open file that represents this process's module. The handle will be closed if no listeners copy the shared_handle.
[in]infoInformation that pertains specifically to this event. Note that any handles in the structure may be nullptr, and that the hFile member is only valid until exit_process_event().
Returns
This method should return true to indicate that it has taken action based on receiving the event, or false to indicate that it has not.

Reimplemented in pstack::pstack_event_handler, proclib::process_debugger::dispatching_event_listener, and pstack::debug_event_dumper.

bool proclib::base_debug_event_listener::create_thread_event ( psystem::process_id_t  pid,
psystem::thread_id_t  tid,
CREATE_THREAD_DEBUG_INFO const &  info 
)
virtualnoexcept

Invoked when the debugger sends an event to indicate thread creation.

This event is sent when a new thread is created during normal execution in a process being debugged, or when the debugger attaches to a process and encounters a preexisting thread of execution.

Parameters
[in]pidThe ID of the process that signaled this event.
[in]tidThe ID of the thread that was created or discovered.
[in]infoInformation that applies specifically to this event.
Returns
This method should return true to indicate that it has taken action based on receiving the event, or false to indicate that it has not.

Reimplemented in pstack::pstack_event_handler, proclib::process_debugger::dispatching_event_listener, and pstack::debug_event_dumper.

bool proclib::base_debug_event_listener::exception_event ( psystem::process_id_t  pid,
psystem::thread_id_t  tid,
EXCEPTION_DEBUG_INFO const &  info 
)
virtualnoexcept

Invoked when the debugger sends an event to indicate some exception in normal process execution.

An exception may be an unhandled C++ exception, it may be a system-level exception (i.e., sigsegv on UNIX or GPF on Windows plaforms), or it may simply indicate that the debugger has reached a breakpoint (which may be requested either by the debugger itself, or by a user-specified break).

Parameters
[in]pidThe ID of the process that signaled this event.
[in]tidThe ID of the thread that is currently in the active state.
[in]infoInformation that applies specifically to this event. This will contain the exception record, which in turn contains the cause of the exception.
Returns
This method should return true to indicate that it has taken action based on receiving the event, or false to indicate that it has not.

Reimplemented in pstack::pstack_event_handler, proclib::process_debugger::dispatching_event_listener, and pstack::debug_event_dumper.

bool proclib::base_debug_event_listener::exit_process_event ( psystem::process_id_t  pid,
psystem::thread_id_t  tid,
EXIT_PROCESS_DEBUG_INFO const &  info 
)
virtualnoexcept

Invoked when the debugger sends an event to indicate that the process has exited.

Parameters
[in]pidThe ID of the process that signaled this event.
[in]tidThe ID of the thread that was in the active state on exit.
[in]infoInformation that applies specifically to this event.
Returns
This method should return true to indicate that it has taken action based on receiving the event, or false to indicate that it has not.
Postcondition
All handles pertaining to this process are invalid.

Reimplemented in pstack::pstack_event_handler, proclib::process_debugger::dispatching_event_listener, and pstack::debug_event_dumper.

bool proclib::base_debug_event_listener::exit_thread_event ( psystem::process_id_t  pid,
psystem::thread_id_t  tid,
EXIT_THREAD_DEBUG_INFO const &  info 
)
virtualnoexcept

Invoked when the debugger sends an event to indicate that a thread has exited.

Parameters
[in]pidThe ID of the process that signaled this event.
[in]tidThe ID of the thread that just exited.
[in]infoInformation that applies specifically to this event.
Returns
This method should return true to indicate that it has taken action based on receiving the event, or false to indicate that it has not.
Postcondition
The thread handle retrieved from create_thread_event() is no longer valid.

Reimplemented in pstack::pstack_event_handler, proclib::process_debugger::dispatching_event_listener, and pstack::debug_event_dumper.

bool proclib::base_debug_event_listener::load_dll_event ( psystem::process_id_t  pid,
psystem::thread_id_t  tid,
psystem::shared_handle<> const &  file_handle,
LOAD_DLL_DEBUG_INFO const &  info 
)
virtualnoexcept

Invoked when the debugger sends an event to indicate that a DLL hase been loaded.

This callback may be triggered if a DLL has been loaded into a running process, or if the debugger discovers an already loaded DLL when attaching to a process.

Parameters
[in]pidThe ID of the process that signaled this event.
[in]tidThe ID of the thread that is currently in the active state.
[in]file_handleThe "shared" handle to the open file that represents this process's module. The handle will be closed if no listeners copy the shared_handle.
[in]infoInformation that applies specifically to this event. Note that any handles in the structure may be nullptr, and that the hFile member is only valid until unload_dll_event().
Returns
This method should return true to indicate that it has taken action based on receiving the event, or false to indicate that it has not.

Reimplemented in pstack::pstack_event_handler, proclib::process_debugger::dispatching_event_listener, and pstack::debug_event_dumper.

bool proclib::base_debug_event_listener::output_debug_string_event ( psystem::process_id_t  pid,
psystem::thread_id_t  tid,
OUTPUT_DEBUG_STRING_INFO const &  info 
)
virtualnoexcept

Invoked when the debugger encounters a trace message from the debuggee.

Parameters
[in]pidThe ID of the process that signaled this event.
[in]tidThe ID of the currently active thread.
[in]infoInformation that applies specifically to this event.
Returns
This method should return true to indicate that it has taken action based on receiving the event, or false to indicate that it has not.

Reimplemented in proclib::process_debugger::dispatching_event_listener, and pstack::debug_event_dumper.

bool proclib::base_debug_event_listener::rip_event ( psystem::process_id_t  pid,
psystem::thread_id_t  tid,
RIP_INFO const &  info 
)
virtualnoexcept

Invoked when the debugger encounters a fatal application exit or debugger error.

Technically, this event indicates that the debugger passed invalid data to the application, however the application itself generally causes this. The debugger receives exception_event() on any potential crash from the debuggee, and if it forwards this exception to the debuggee, it may result in a crash that triggers this event.

Parameters
[in]pidThe ID of the process that signaled this event.
[in]tidThe ID of the currently active thread.
[in]infoInformation that applies specifically to this event.
Returns
This method should return true to indicate that it has taken action based on receiving the event, or false to indicate that it has not.

Reimplemented in proclib::process_debugger::dispatching_event_listener, and pstack::debug_event_dumper.

bool proclib::base_debug_event_listener::unload_dll_event ( psystem::process_id_t  pid,
psystem::thread_id_t  tid,
UNLOAD_DLL_DEBUG_INFO const &  info 
)
virtualnoexcept

Invoked when the debugger encounters a DLL unload.

Parameters
[in]pidThe ID of the process that signaled this event.
[in]tidThe ID of the currently active thread.
[in]infoInformation that applies specifically to this event.
Returns
This method should return true to indicate that it has taken action based on receiving the event, or false to indicate that it has not.
Postcondition
The handle retrieved from the corresponding load_dll_event() is no longer valid.

Reimplemented in pstack::pstack_event_handler, proclib::process_debugger::dispatching_event_listener, and pstack::debug_event_dumper.

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