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_BREAKPOINT do { } while(0)

#define	GATE_DEBUG_ASSERT(xpression) do { } while(0)
	Evaluates `xpression` and invokes gate_debug_assert() if expression if `false`.

#define	GATE_DEBUG_TRACE(msg) do { } while(0)
	Prints `msg` to the debugger by invoking gate_debug_trace()

#define	GATE_DEBUG_TRACE_VALUE(num) do { } while(0)
	Prints `num` to the debugger by invoking gate_debug_trace_value()

#define	GATE_DEBUG_TRACE_MSG_VALUE(msg, num) do { } while(0)
	Prints `msg` and `num` to the debugger by invoking gate_debug_trace_msg_value()

#define	GATE_DEBUG_TRACE_PLATFORM_ERROR(msg) do { } while(0)
	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) do { } while(0)
	Prints `msg` to the debugger only if `result` indicates an error.

#define	GATE_DEBUG_TRACE_VALUE_FAILED(result, num) do { } while(0)
	Prints `num` value to the debugger only if `result` indicates an error.

#define	GATE_DEBUG_TRACE_FAILED_RESULT(result) do { } while(0)
	Prints `result` code to the debugger only if `result` indicates an error.

#define	GATE_DEBUG_TRACE_RESULT(result, origin, msg, error) do { } while(0)
	Prints `result` , `origin` , `msg` and `error_code` to the debugger by invoking gate_debug_trace_result()

#define	GATE_BREAK_IF_FAILED_TRACE(result, msg)

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.

Macro Definition Documentation

◆ GATE_BREAK_IF_FAILED_TRACE

#define GATE_BREAK_IF_FAILED_TRACE	(		result,
			msg )

Value:

    { \
        if(GATE_FAILED((result))) \
        { \
            GATE_DEBUG_TRACE(msg); \
            GATE_DEBUG_TRACE_VALUE(result); \
            break; \
        } \
    }

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()

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_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_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

◆ 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

Macros

Functions

Detailed Description

Macro Definition Documentation

◆ GATE_BREAK_IF_FAILED_TRACE

Function Documentation

◆ gate_debug_assert()

◆ gate_debug_trace()

◆ gate_debug_trace_messages()

◆ gate_debug_trace_msg_value()

◆ gate_debug_trace_platform_error()

◆ gate_debug_trace_result()

◆ gate_debug_trace_value()