"Custom" Assert and Trace functions (called from HqAssert and HqTrace). Each platform should define its own version of these functions. More...

#include <stdarg.h>
#include "hqncall.h"

Data Structures
struct	HqAssertHandlers_t
	Structure to manipulate the assert and trace handler function pointers. More...

Typedefs
typedef void()	HqCustomAssert_fn(const char pszFilename, int nLine, const char pszFormat, va_list vlist, int assertflag)
	Function type for assert handler. More...

typedef void()	HqCustomTrace_fn(const char pszFilename, int nLine, const char pszFormat, va_list vlist)
	Function type for trace handler. More...

typedef void()	GetHqAssertHandlers_fn(HqAssertHandlers_t *functions)
	Function type that gets assertion functions from a module. More...

Enumerations
enum	{ AssertNotRecursive , AssertRecursive }

Functions
void	SetHqAssertHandlers (HqAssertHandlers_t *functions)
	Set custom functions to handle assertions and tracing. More...

void	GetHqAssertHandlers (HqAssertHandlers_t *functions)
	Get the custom assertion functions provided by a module. More...

void	HqCustomAssert (const char pszFilename, int nLine, const char pszFormat, va_list vlist, int assertflag)

void	HqCustomTrace (const char pszFilename, int nLine, const char pszFormat, va_list vlist)

Detailed Description

"Custom" Assert and Trace functions (called from HqAssert and HqTrace). Each platform should define its own version of these functions.

Typically HqCustomAssert should display the message to the user (unless it is NULL) and interrupt the program (or drop into a debugger).

HqCustomTrace will usually do nothing.

Copyright (C) 2023 Global Graphics Software Ltd. All rights reserved. This source code contains the confidential and trade secret information of Global Graphics Software Ltd. It may not be used, copied or distributed for any reason except as set forth in the applicable Global Graphics license agreement.

Typedef Documentation

◆ GetHqAssertHandlers_fn

typedef void() GetHqAssertHandlers_fn(HqAssertHandlers_t *functions)

Function type that gets assertion functions from a module.

Parameters

[out] functions A pointer to a custom assert handler structure.

The main use for functions of this type is to get the custom assert handlers from one linkage unit for use in another linkage unit.

◆ HqCustomAssert_fn

typedef void() HqCustomAssert_fn(const char *pszFilename, int nLine, const char *pszFormat, va_list vlist, int assertflag)

Function type for assert handler.

Parameters

[in]	pszFilename	The filename in which the assert happened.
	nLine	The line in pszFilename at which the assert happened.
[in]	pszFormat	A `printf()` style format used to interpret the vlist variable argument list.
[in]	vlist	A variable argument list to construct the assert message from.
	assertflag	Either AssertNotRecursive or AssertRecursive.

All of the assert macros are converted to calls on the custom assert handler function to issue the debug message and perform the debug break.

◆ HqCustomTrace_fn

typedef void() HqCustomTrace_fn(const char *pszFilename, int nLine, const char *pszFormat, va_list vlist)

Function type for trace handler.

Parameters

[in]	pszFilename	The filename in which the trace happened.
	nLine	The line in pszFilename at which the trace happened.
[in]	pszFormat	A `printf()` style format used to interpret the vlist variable argument list.
[in]	vlist	A variable argument list to construct the assert message from.

All of the trace macros are converted to calls on the custom trace handler function to issue the debug message and perform the debug break.

Enumeration Type Documentation

◆ anonymous enum

anonymous enum

Values for the assertflag parameter to HqCustomAssert_fn.

Enumerator
AssertNotRecursive	This is a top-level assert.
AssertRecursive	This assert or trace may be happening inside another.

Function Documentation

◆ GetHqAssertHandlers()

void GetHqAssertHandlers ( HqAssertHandlers_t * functions )

Get the custom assertion functions provided by a module.

Parameters

[out] functions A pointer to a custom assert handler structure.

This function is used by some dynamic libraries to hook into assertion functions provided by the host program. The linker options should be set to export this function for dynamic libraries that provide assert handlers.

◆ HqCustomAssert()

void HqCustomAssert	(	const char *	pszFilename,
		int	nLine,
		const char *	pszFormat,
		va_list	vlist,
		int	assertflag
	)

It is customary to name the assert handler function HqCustomAssert. This prototypes exist to help make it easy to use.

Parameters

[in]	pszFilename	The filename in which the assert happened.
	nLine	The line in pszFilename at which the assert happened.
[in]	pszFormat	A `printf()` style format used to interpret the vlist variable argument list.
[in]	vlist	A variable argument list to construct the assert message from.
	assertflag	Either AssertNotRecursive or AssertRecursive.

◆ HqCustomTrace()

void HqCustomTrace	(	const char *	pszFilename,
		int	nLine,
		const char *	pszFormat,
		va_list	vlist
	)

It is customary to name the trace handler function HqCustomTrace. This prototype exists to help make it easy to use.

Parameters

[in]	pszFilename	The filename in which the trace happened.
	nLine	The line in pszFilename at which the trace happened.
[in]	pszFormat	A `printf()` style format used to interpret the vlist variable argument list.
[in]	vlist	A variable argument list to construct the assert message from.

◆ SetHqAssertHandlers()

void SetHqAssertHandlers ( HqAssertHandlers_t * functions )

Set custom functions to handle assertions and tracing.

Parameters

[in] functions A pointer to the custom assert handlers. If this pointer is NULL, this function resets the custom handlers to their default values. If the structure pointer is non-NULL, but the assert function or trace function pointer identified in the function is NULL, the value will not be overridden.

HQNc-standard provides default implementations of HqCustomAssert() and HqCustomTrace() that write to stderr and stdout. These are not appropriate for all use cases, so we allow them to be overridden by calling this function.

Data Structures

Typedefs

Enumerations

Functions

Detailed Description

Typedef Documentation

◆ GetHqAssertHandlers_fn

◆ HqCustomAssert_fn

◆ HqCustomTrace_fn

Enumeration Type Documentation

◆ anonymous enum

Function Documentation

◆ GetHqAssertHandlers()

◆ HqCustomAssert()

◆ HqCustomTrace()

◆ SetHqAssertHandlers()