UTDebug.h File Reference
Go to the source code of this file.
Classes |
| struct | ValidReadBlock_t |
Defines |
| #define | debug_printf debug_printf_IMPL |
| #define | debug_printf1 debug_printf_IMPL |
| #define | debug_printf2 debug_printf_IMPL |
| #define | debug_printf3 debug_printf_IMPL |
| #define | debug_printf4 debug_printf_IMPL |
| #define | debug_printf5 debug_printf_IMPL |
| #define | debug_printf6 debug_printf_IMPL |
| #define | debug_printf7 debug_printf_IMPL |
| #define | debug_printf8 debug_printf_IMPL |
| #define | debug_printf9 debug_printf_IMPL |
| #define | rel_debug_printf debug_printf_IMPL |
| #define | assert(exp) |
| #define | rel_assert(exp) |
| #define | debug_error(message) |
| #define | rel_error(message) |
Functions |
| void | enable_debug_print_to_file (stringliteral *path, bool exclusive, bool append, int buffer_size) |
| void | enable_debug_print_to_file (const Path_t &path, bool exclusive, bool append, int buffer_size) |
| void | enable_debug_print_to_stream (takes OutputStream_t *stream, bool exclusive) |
| void | flush_debug_printf (void) |
| void | debugger (void) |
| bool | running_in_debugger (void) |
| void | suicide (void) |
| uint | get_call_stack (uint skip_levels, uint max_levels, out void **call_stack) |
| void | debug_print_call_stack (stringliteral *label, uint skip_levels, uint print_levels) |
| bool | is_valid_read_pointer (const void *block_address, int block_size, struct ValidReadBlock_t *optimize) |
| bool | is_valid_string_pointer (const utf8 *string) |
| bool | is_valid_unicode_pointer (const wchar_t *string) |
Define Documentation
| #define debug_printf debug_printf_IMPL |
Generates printf-style debug output which is visible even for applications which are not associated with a command prompt. The output will be generated in debug builds, but not in release builds. In release builds, the debug_printf will be removed by the preprocessor. Because debug_printf is actually a preprocessor macro, debug_printf in its generic form as in debug_printf("i=%d",i) will result in a compilation error in release builds. debug_printf with additional parameters can be used temporarily in debug builds, however to perform release builds uses of debug_printf with parameters must either be removed or replaced with debug_printf1 for one additional parameter, debug_printf2 for two additional parameters and so on. The format string is ANSI-standard compliant, supporting "%lld" and "%ls" to represent int64 and wchar_t* respectively, for example. When printing pointers, don't use "%x", use "%p" instead. Don't use "%08p" either, assuming 32-bit addresses. Use 0p so that the field width will be automatically adjusted to the pointer size.
Definition at line 62 of file UTDebug.h.
| #define debug_printf1 debug_printf_IMPL |
| #define debug_printf2 debug_printf_IMPL |
| #define debug_printf3 debug_printf_IMPL |
| #define debug_printf4 debug_printf_IMPL |
| #define debug_printf5 debug_printf_IMPL |
| #define debug_printf6 debug_printf_IMPL |
| #define debug_printf7 debug_printf_IMPL |
| #define debug_printf8 debug_printf_IMPL |
| #define debug_printf9 debug_printf_IMPL |
| #define rel_debug_printf debug_printf_IMPL |
Generates printf-style debug output by a mechanism identical to debug_printf but which is output even in release builds.
Definition at line 91 of file UTDebug.h.
Value:CAST_VOID( (exp) \
|| ( assert_PLUS( #exp, \
__FILE__, \
__LINE__ ), \
false ) )
assert is defined in assert.h, and behaves according to the ANSI C standard, but has been overridden to provide extended debugging information.
On most systems, the diagnostic feedback provided when an assert fires is limited to an expression, source file name, and line number. This is frequently inadequate, particularly so when an assertion fails in a general utility class. Therefore, the UT library overrides the implementation of assert to provide a full call stack from the point of the error, and to mirror that information to an assert log file. The replacement implementation also ensures that the thread which asserted is blocked until the assertion failure dialog is dismissed, preventing the assert implementation from, on Windows at least, continuing to "pump" the main event loop and allowing assertions to fire down the call stack with the effect of assert dialogs piling up until the thread runs out of stack space.
Definition at line 175 of file UTDebug.h.
| #define rel_assert |
( |
exp |
|
) |
|
Value:CAST_VOID( (exp) \
|| ( assert_PLUS( #exp, \
__FILE__, \
__LINE__ ), \
false ) )
Like assert, but is included in release builds.
Definition at line 193 of file UTDebug.h.
| #define debug_error |
( |
message |
|
) |
|
Value:assert_PLUS( message, \
__FILE__, \
__LINE__ )
Acts as if an assert failed, but prints a message and is excluded in release builds.
Definition at line 205 of file UTDebug.h.
| #define rel_error |
( |
message |
|
) |
|
Value:assert_PLUS( message, \
__FILE__, \
__LINE__ )
Acts as if an assert failed, but prints a message and is included in release builds.
Definition at line 217 of file UTDebug.h.
Function Documentation
| void enable_debug_print_to_file |
( |
stringliteral * |
path, |
|
|
bool |
exclusive, |
|
|
bool |
append, |
|
|
int |
buffer_size | |
|
) |
| | |
Causes debug_printf, etc to also write the output to a file. If exclusive is true, output will go only to the file, not to stderr or OutputDebugString. Output is buffered, so it is necessary to eventually close the file by calling the function again with path = NULL and exclusive = false. The file will be automatically flushed if an assertion fires.
| void enable_debug_print_to_file |
( |
const Path_t & |
path, |
|
|
bool |
exclusive, |
|
|
bool |
append, |
|
|
int |
buffer_size | |
|
) |
| | |
Causes debug_printf, etc to also write the output to a file. If exclusive is true, output will go only to the file, not to stderr or OutputDebugString. Output is buffered, so it is necessary to eventually close the file by calling the function again with path = NULL and exclusive = false. The file will be automatically flushed if an assertion fires.
| void enable_debug_print_to_stream |
( |
takes OutputStream_t * |
stream, |
|
|
bool |
exclusive | |
|
) |
| | |
Causes debug_printf, etc to also write the output to a stream. If exclusive is true, output will go only to the stream, not to stderr or OutputDebugString. The debug_printf mechanism takes posession of and responsibility for deleting the stream. Use of enable_debug_print_to_file creates an OutputStream_t subclass which is installed via this mechanism, so if the file mechanism had been used previously, the file will be closed. Likewise, if the file mechanism is used after having installed an output stream, the output stream will be closed. The stream will be automatically flushed if an assertion fires.
| void flush_debug_printf |
( |
void |
|
) |
|
Flushes the file or stream to which debug_printf is being directed.
Drops into the debugger unconditionally and immediately.
| bool running_in_debugger |
( |
void |
|
) |
|
Returns true if the application is running in a debugger.
Exits the process without performing any sort of cleanup or memory checking This shoud only be done if some sort of feedback had been provided to the user previously as to the nature of the error.
| uint get_call_stack |
( |
uint |
skip_levels, |
|
|
uint |
max_levels, |
|
|
out void ** |
call_stack | |
|
) |
| | |
Obtains the return address of the call stack beginning either with the current stack frame pointer or the specified stack frame pointer. Returns the number of levels obtained. To aid in interpreting the call stack, the DebugSymbolInfo_t class can be used.
- Parameters:
-
| skip_levels | How many stack frames to skip before obtaining the call stack. If skip_levels is zero, the first frame will be the location in the function which called get_call_stack. |
| max_levels | The maximum number of stack frames to obtain. |
| call_stack | The caller must pass a pointer to an array of void* with max_levels elements. If skip_levels is zero, the first element in call_stack will be the address from which get_call_stack was called. On CPUs like the x86 or x86_64 family, which do not have uniform length instructions, it will be one byte before the return address, which is a few bytes after the beginning of the instruction which was used to call get_call_stack. That is good enough for symbol and source code line lookup, which is what this function is really intended for. |
Prints the specified levels of call stack using rel_debug_printf.
- Parameters:
-
| label | The label that will precede the call stack output. If the label ends with a linefeed character, each output stack frame will be indented by four spaces. If the label does not end with a linefeed character, the first stack frame will be printed on the same line as label, after it, and each subsequent stack frame will be printed on its own line, indented by the number of characters in the label. |
| skip_levels | How many stack frames to skip before obtaining the call stack. If skip_levels is zero, the first frame will be the location in the function which called debug_print_call_stack. |
| print_levels | The number of levels of call stack to print |
| bool is_valid_read_pointer |
( |
const void * |
block_address, |
|
|
int |
block_size, |
|
|
struct ValidReadBlock_t * |
optimize | |
|
) |
| | |
Returns true if the specified pointer is valid for reading. If this function will be called multiple times, operating on data which is reasonably well assured to be in proximity across multiple calls, a ValidReadBlock_t can passed through optimize. The optimization information is not guaranteed to be valid later. It can be used for one operation, such as walking the stack. The optimization information cannot be saved indefinitely. optimize can be NULL.
| bool is_valid_string_pointer |
( |
const utf8 * |
string |
) |
|
Returns true if the specified pointer is valid for reading a string.
| bool is_valid_unicode_pointer |
( |
const wchar_t * |
string |
) |
|
Returns true if the specified pointer is valid for reading a string.
