proclib::debug_engine Class Reference

A management interface for debugging applications. More...

#include <debug_engine.hpp>

Inheritance diagram for proclib::debug_engine:

Collaboration diagram for proclib::debug_engine:

Type Definitions
using	process_debuggers = std::map< psystem::process_id_t, std::unique_ptr< process_debugger > >
	Container for process_debuggers.

Construction / Destruction
	debug_engine (bool kill_on_exit=false) noexcept
	Construct an instance of the debug engine. More...
	~debug_engine () noexcept
	Clean up resources used by debug_engine. More...

Public Interface
process_debugger &	attach_to_process (psystem::process_id_t pid)
	Attach a debugger to a running process using the process ID (PID). More...
void	enable_debug_privilege () const
	Allows the current process to debug other processes. More...
process_debugger *	get_process_debugger (psystem::process_id_t pid) const
	Fetch a process_debugger instance. More...
bool	wait_for_event (DWORD ms=INFINITE) const
	Block the current thread until any debugger sees an event. More...

Member Data
process_debuggers	m_debuggers
	A set of attached debuggers indexed by process ID (PID)
bool const	m_kill_on_exit
	Was the debug_engine asked to kill attached processes on detach?

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

A management interface for debugging applications.

The debug_engine is responsible for attaching to processes, creating debugged processes, dispatching events from the debugger and so on. The engine is not specific to any one process, but it does manage the process_debugger instances, which provide access to process specific data.

Warning

Constructing multiple instances of this class causes undefined behavior when invoking attach_to_process() on the same PID.

Author

Matt Bisson

Date

5 August, 2014

Since

ProcLib 2.0

Version

ProcLib 2.0

Constructor & Destructor Documentation

proclib::debug_engine::debug_engine ( bool  kill_on_exit = false )

explicitnoexcept

Construct an instance of the debug engine.

Parameters

[in]

kill_on_exit

When the debugger detaches from a process, this flag determines the fate of the process being debugged. If true, the process exits when the debugger detaches, otherwise, it continues normal execution.

Warning

Unfortunately, Microsoft's debugger implementation makes this a global flag for all debuggers. It is advisable to only debug multiple processes when the flag will be consistent across all instances, and will never change.

proclib::debug_engine::~debug_engine ( )

noexcept

Clean up resources used by debug_engine.

This will deallocate all active process_debugger instances, and their data.

Member Function Documentation

process_debugger & proclib::debug_engine::attach_to_process

(

psystem::process_id_t

pid

)

Attach a debugger to a running process using the process ID (PID).

Upon attaching to a running process, the debugger immediately freezes the debuggee, and waits for debug events to be consumed (with wait_for_event()).

Parameters

[in]

pid

The ID of the process to which the debugger will attach.

Returns

A recently attached process_debugger instance that is being managed by this engine.

Exceptions

psystem::exception::system_exception

If the native debugger could not attach to the process.

Attention

Calls process_debugger::set_kill_process_on_exit() (which has global ramifications).

Precondition

get_process_debugger(pid) is unsuccessful.

Postcondition

get_process_debugger(pid) returns a valid process_debugger.

void proclib::debug_engine::enable_debug_privilege

(

)

const

Allows the current process to debug other processes.

The method must be executed at least once before attaching a debugger to any running processes.

Exceptions

psystem::exception::system_exception

If there was an error accessing the current process or altering its privileges with the OS.

process_debugger * proclib::debug_engine::get_process_debugger

(

psystem::process_id_t

pid

)

const

Fetch a process_debugger instance.

Parameters

[in]

pid

The ID of the process associated to a debugger.

Returns

A pointer to the found process_debugger instance. Its lifespan lasts as long as the debugger is attached to the process with this debug_engine. If no process_debugger is found, this method simply returns nullptr.

bool proclib::debug_engine::wait_for_event

(

DWORD

ms = INFINITE

)

const

Block the current thread until any debugger sees an event.

This method automatically forwards the received event on to the appropriate process_debugger. To register for events, invoke process_debugger::add_event_listener() with a custom instance of proclib::base_debug_event_listener.

Parameters

[in]

ms

The amount of time (in ms) to wait for the next event.

Returns

true if some event handler responded to the event in a non-trivial way, false otherwise.

Exceptions

psystem::exception::system_exception

If there was a problem waiting for an event or continuing execution after the event.

See also

proclib::base_debug_event_listener

proclib::process_debugger::add_event_listener()

Todo:

No way to determine time-out vs unhandled event

Todo:

LOG

Todo:

LOG

Todo:

LOG

---

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

• include/proclib/debug_engine.hpp
• src/proclib/debug_engine.cpp