Crate win_dbg_logger

A logger for use with Windows debuggers.

Windows allows applications to output a string directly to debuggers. This is very useful in situations where other forms of logging are not available. For example, stderr is not available for GUI apps.

Windows provides the OutputDebugString entry point, which allows apps to print a debug string. Internally, OutputDebugString is implemented by raising an SEH exception, which the debugger catches and handles.

Raising an exception has a significant cost, when run under a debugger, because the debugger halts all threads in the target process. So you should avoid using this logger for high rates of output, because doing so will slow down your app.

Like many Windows entry points, OutputDebugString is actually two entry points: OutputDebugStringA (multi-byte encodings) and OutputDebugStringW (UTF-16). In most cases, the *A version is implemented using a “thunk” which converts its arguments to UTF-16 and then calls the *W version. However, OutputDebugStringA is one of the few entry points where the opposite is true.

This crate can be compiled and used on non-Windows platforms, but it does nothing. This is intended to minimize the impact on code that takes a dependency on this crate.

Structs

DebuggerLogger

This implements log::Log, and so can be used as a logging provider. It forwards log messages to the Windows OutputDebugString API.

Statics

DEBUGGER_LOGGER

This is a static instance of DebuggerLogger. Since DebuggerLogger contains no state, this can be directly registered using log::set_logger.

Functions

init

Sets the DebuggerLogger as the currently-active logger.

is_debugger_present

Checks whether a debugger is attached to the current process.

output_debug_string

Calls the OutputDebugString API to log a string.

rust_win_dbg_logger_init_debug

This can be called from C/C++ code to register the debug logger.

rust_win_dbg_logger_init_error

This can be called from C/C++ code to register the debug logger.

rust_win_dbg_logger_init_info

This can be called from C/C++ code to register the debug logger.

rust_win_dbg_logger_init_trace

This can be called from C/C++ code to register the debug logger.

rust_win_dbg_logger_init_warn

This can be called from C/C++ code to register the debug logger.