debugging.h File Reference

Assertion and tracing debugging functions and macros. More...

#include "gate/gate_core_api.h"
#include "gate/gatetypes.h"
#include "gate/results.h"

Macros
#define	GATE_DEBUG_ASSERT(xpression)
	Evaluates xpression and invokes gate_debug_assert() if expression if false.
#define	GATE_DEBUG_TRACE(msg)
	Prints msg to the debugger by invoking gate_debug_trace()
#define	GATE_DEBUG_TRACE_VALUE(num)
	Prints num to the debugger by invoking gate_debug_trace_value()
#define	GATE_DEBUG_TRACE_MSG_VALUE(msg, num)
	Prints msg and num to the debugger by invoking gate_debug_trace_msg_value()
#define	GATE_DEBUG_TRACE_PLATFORM_ERROR(msg)
	Prints msg and the current platform error code to the debugger by invoking gate_debug_trace_platform_error()
#define	GATE_DEBUG_TRACE_FAILED(result, msg)
	Prints msg to the debugger only if result indicates an error.
#define	GATE_DEBUG_TRACE_VALUE_FAILED(result, num)
	Prints num value to the debugger only if result indicates an error.
#define	GATE_DEBUG_TRACE_FAILED_RESULT(result)
	Prints result code to the debugger only if result indicates an error.
#define	GATE_DEBUG_TRACE_RESULT(result, origin, msg, error)
	Prints result , origin , msg and error_code to the debugger by invoking gate_debug_trace_result()

Functions
GATE_CORE_API void	gate_debug_breakpoint ()
	Executes a platform-native operation that lets a debugger detect a dynamic code breakpoint.
GATE_CORE_API void	gate_debug_assert (gate_bool_t xpression, char const *msg, char const *file, unsigned int line)
	Evaluates an expression and generates a debugging warning if the evaluation detects a failure.
GATE_CORE_API void	gate_debug_trace_messages (char const *const *msgs, gate_size_t msgs_count)
	Writes trace messages to the debugger.
GATE_CORE_API void	gate_debug_trace (char const *msg, char const *file, unsigned int line)
	Writes a debug trace message to the debugger.
GATE_CORE_API void	gate_debug_trace_value (char const *name, gate_int64_t value, char const *file, unsigned int line)
	Writes a named integer value to the debugger.
GATE_CORE_API void	gate_debug_trace_msg_value (char const *msg, char const *name, gate_int64_t value, char const *file, unsigned int line)
	Writes a text and a named integer value to the debugger.
GATE_CORE_API void	gate_debug_trace_platform_error (char const *msg, char const *file, unsigned int line)
	Writes a user defined message and a the current platform error code and its description to the debugger.
GATE_CORE_API void	gate_debug_trace_result (gate_result_t result, char const *origin, char const *msg, gate_int32_t error_code, char const *file, unsigned int line)
	Writes a result evaluation (result-code, origin, message, error-code) to the debugger.

Detailed Description

Assertion and tracing debugging functions and macros.

Function Documentation

gate_debug_assert()

GATE_CORE_API void gate_debug_assert	(	gate_bool_t	xpression,
		char const *	msg,
		char const *	file,
		unsigned int	line )

Evaluates an expression and generates a debugging warning if the evaluation detects a failure.

Parameters

[in]	xpression	Evaluated boolean expression
[in]	msg	NULL-terminated text message to be sent to debugger in case of a detected failure
[in]	file	NULL-terminated string naming the originating code file where the assertion was generated
[in]	line	Line number in the source file where the assertion was generation

gate_debug_trace_messages()

GATE_CORE_API void gate_debug_trace_messages	(	char const *const *	msgs,
		gate_size_t	msgs_count )

Writes trace messages to the debugger.

Parameters

[in]	msgs	Array of NULL-terminated text strings to be sent to the debugger
[in]	msgs_count	Count of text messages in msgs array

gate_debug_trace()

GATE_CORE_API void gate_debug_trace	(	char const *	msg,
		char const *	file,
		unsigned int	line )

Writes a debug trace message to the debugger.

Parameters

[in]	msg	NULL-terminated text string to be sent to the debugger
[in]	file	NULL-terminated filename of the source file where the trace message was generated
[in]	line	Line number of code in source file where the trace message was generated

gate_debug_trace_value()

GATE_CORE_API void gate_debug_trace_value	(	char const *	name,
		gate_int64_t	value,
		char const *	file,
		unsigned int	line )

Writes a named integer value to the debugger.

Prints a pair of "name = value", e.g. "my_variable = 12"

Parameters

[in]	name	NULL-terminated text string naming the value to be sent to the debugger
[in]	value	integer value to be sent to the debugger
[in]	file	NULL-terminated filename of the source file where the trace message was generated
[in]	line	Line number of code in source file where the trace message was generated

gate_debug_trace_msg_value()

GATE_CORE_API void gate_debug_trace_msg_value	(	char const *	msg,
		char const *	name,
		gate_int64_t	value,
		char const *	file,
		unsigned int	line )

Writes a text and a named integer value to the debugger.

Prints a pair of "msg; name = value", e.g. "My variable was changed; my_variable = 12"

Parameters

[in]	msg	NULL-terminated text string to be sent to the debugger
[in]	name	NULL-terminated text string naming the value to be sent to the debugger
[in]	value	integer value to be sent to the debugger
[in]	file	NULL-terminated filename of the source file where the trace message was generated
[in]	line	Line number of code in source file where the trace message was generated

gate_debug_trace_platform_error()

GATE_CORE_API void gate_debug_trace_platform_error	(	char const *	msg,
		char const *	file,
		unsigned int	line )

Writes a user defined message and a the current platform error code and its description to the debugger.

Adds the output of gate_platform_print_error() to the trace message

Parameters

[in]	msg	NULL-terminated text string to be sent to the debugger
[in]	file	NULL-terminated filename of the source file where the trace message was generated
[in]	line	Line number of code in source file where the trace message was generated

gate_debug_trace_result()

GATE_CORE_API void gate_debug_trace_result	(	gate_result_t	result,
		char const *	origin,
		char const *	msg,
		gate_int32_t	error_code,
		char const *	file,
		unsigned int	line )

Writes a result evaluation (result-code, origin, message, error-code) to the debugger.

The trace messages reflect the default members of a GATE C++ exception

Parameters

[in]	result	GATE_RESULT_* result code of an operation
[in]	origin	NULL-terminated text naming the origin of the result (like an external function name)
[in]	msg	user defined NULL-terminated text string
[in]	error_code	native error code from the origin of the result
[in]	file	NULL-terminated filename of the source file where the trace message was generated
[in]	line	Line number of code in source file where the trace message was generated