kzs_error.h File Reference

Error handling functions. More...

#include <system/kzs_types.h>
#include <system/kzs_header.h>

Macros
#define	KZS_EXCEPTION_MESSAGE_MAXIMUM_LENGTH
	Maximum length of exception. More...
#define	KZS_SUCCESS
	Success code. More...
#define	KZS_ERROR_ASSERTION_FAILED
	Assertion failed. More...
#define	KZS_ERROR_NOT_IMPLEMENTED_YET
	Functionality is not yet implemented. More...
#define	KZS_ERROR_ENUM_OUT_OF_RANGE
	Invalid value for enum. More...
#define	KZS_ERROR_ILLEGAL_OPERATION
	Trying to perform illegal operation. More...
#define	KZS_ERROR_ILLEGAL_ARGUMENT
	An argument was invalid for the given context. More...
#define	KZS_ERROR_MALFORMED_DATA
	Data is malformed. More...
#define	KZS_ERROR_ARRAY_OUT_OF_BOUNDS
	Trying to access array with invalid index. More...
#define	KZS_ERROR_INVALID_STATE
	Program is in invalid state. More...
#define	kzsSuccess()
	Return from the function without any error code. More...
#define	kzsAssertText(test, text)
	Asserts the given test parameter. More...
#define	kzsAssert(test)
	Asserts the given test parameter. More...
#define	kzsErrorBreak()
	Terminates the application and traps the debugger if possible. More...
#define	kzsDebugBreak()
	Traps the debugger if possible. More...
#define	kzsErrorThrow(new_error, logMessage)
	Return from the function with the given error code. More...
#define	kzsErrorThrowFormat(new_error, formatArgs)
#define	kzsExceptionThrow(new_exception, logMessage)
	Return from the function with the given exception code. More...
#define	kzsExceptionThrowFormat(new_exception, formatArgs)
#define	kzsExceptionRethrow(param_exception)
	Return from the function with the given exception code. More...
#define	kzsErrorTest(test, new_error, logMessage)
	Return from the function with the given error code, if the test is false. More...
#define	kzsErrorTestFormat(test, new_error, formatArgs)
#define	kzsExceptionTest(test, new_exception, logMessage)
	Return from the function with the given exception code, if the test is false. More...
#define	kzsExceptionTestFormat(test, new_exception, formatArgs)
#define	kzsErrorForward(error)
	Return from the function with the given error code, if it is one. More...
#define	kzsExceptionForward(exception)
	Return from the function with the given exception or error code, if it is one. More...
#define	kzsExceptionForwardAsError(exception, new_error, logMessage)
	If the given exception code is an error, pass it forward. More...
#define	kzsExceptionForwardAsErrorFormat(test, new_error, formatArgs)
#define	kzsErrorSubstitute(error, new_error, logMessage)
	Return from the function with the given new error code, if the given old code is also an error. More...
#define	kzsExceptionSubstitute(error, new_exception, logMessage)
	Return from the function with the given new exception code, if the given old code is also an exception. More...
#define	kzsErrorIf(error)
	Test if the given error is an error. More...
#define	kzsExceptionCatch(exception, exception_code)
	Test if the given exception matches the specified exception code. More...
#define	kzsExceptionCatchAll(exception)
	Test if the given exception is an actual exception and not success or error. More...
#define	KZS_NOT_IMPLEMENTED_YET
	Macro to use to indicate that some code is not yet implemented. More...
#define	KZS_NOT_IMPLEMENTED_YET_ERROR
	Macro to use to indicate and throw error that some code is not yet implemented. More...
#define	KZS_NOT_IMPLEMENTED_YET_ERROR_TEXT(message)
	Macro to use to indicate and throw error with an explanation, that some code is not yet implemented. More...
#define	kzsErrorLog(errorCode, message)
	Logs the given error code with given message. More...

Typedefs
typedef int	kzsException
	Exception code type definition, extends error. More...
typedef void(*	KzsErrorCallback )(kzsError errorCode, kzString message)
	Callback that is triggered in error situations. More...
typedef void(*	KzsExceptionCallback )(kzsError errorCode, kzString message)
	Callback that is triggered in exception situations. More...

Functions
KZ_INLINE kzBool	kzsAssertTest_private (void)
	Helper function for assert macro to suppress compiler warnings. More...
void	kzsErrorThrowFunctionWithMessage_private (kzsError error, kzString message)
	kzsErrorThrow macro wrapper to share code. More...
void	kzsErrorThrowFunction_private (kzsError error)
	Wrapper for kzsErrorThrow() to share more code. More...
void	kzsErrorLog_private (kzsError errorCode, kzString message, kzString file, kzUint line)
void	kzsAssert_private (void)
void	kzsErrorBreak_private (void)
void	kzsDebugBreak_private (void)
void	kzsExceptionLog_private (kzString message)
	Exception log. More...
void	kzsExceptionLogFormat_private (kzString format,...)
	Exception log format. More...
void	kzsErrorOccurred_private (kzsError errorCode, kzString message)
	Error callback. More...
void	kzsExceptionOccurred_private (kzsError errorCode, kzString message)
	Exception callback. More...
kzsError	kzsErrorInitializeThread (kzMutableString *storage)
	Initializes error handling for thread. More...
kzsError	kzsErrorDeinitializeThread (void)
	De-initializes error handling for thread. More...
kzsError	kzsErrorInitialize (void)
	Initialize a global variable for error message storage. More...
kzsError	kzsErrorUninitialize (void)
	De-initialize a global variable for error message storage. More...
void	kzsErrorSetErrorCallback (KzsErrorCallback callback)
	Sets error callback. More...
void	kzsErrorSetExceptionCallback (KzsExceptionCallback callback)
	Sets exception callback. More...
kzString	kzsErrorGetLastErrorMessage (void)
	Gets last error message or empty string if there is no error. More...
kzString	kzsErrorGetLastExceptionMessage (void)
	Gets the last exception message for the thread. More...
void	kzsErrorFormatMessage_private (kzString format,...)
	Formats error message. More...
kzString	kzsErrorGetLastFormattedErrorMessage_private (void)
	Gets last formatted error message. More...

Variables
KZ_HEADER_BEGIN typedef int	kzsError
	Error code type definition. More...

Detailed Description

Error handling functions.

Copyright 2008-2019 by Rightware. All rights reserved.

Macro Definition Documentation

#define KZS_EXCEPTION_MESSAGE_MAXIMUM_LENGTH

Maximum length of exception.

#define KZS_SUCCESS

Success code.

No error.

#define KZS_ERROR_ASSERTION_FAILED

Assertion failed.

#define KZS_ERROR_NOT_IMPLEMENTED_YET

Functionality is not yet implemented.

#define KZS_ERROR_ENUM_OUT_OF_RANGE

Invalid value for enum.

#define KZS_ERROR_ILLEGAL_OPERATION

Trying to perform illegal operation.

#define KZS_ERROR_ILLEGAL_ARGUMENT

An argument was invalid for the given context.

#define KZS_ERROR_MALFORMED_DATA

Data is malformed.

#define KZS_ERROR_ARRAY_OUT_OF_BOUNDS

Trying to access array with invalid index.

#define KZS_ERROR_INVALID_STATE

Program is in invalid state.

#define kzsSuccess

(

)

Return from the function without any error code.

#define kzsAssertText	(		test,
			text
	)

Asserts the given test parameter.

If test evaluates to true, nothing happens. Only effective in debug build.

#define kzsAssert

(

test)

Asserts the given test parameter.

If test evaluates to true, nothing happens. Only effective in debug build.

#define kzsErrorBreak

(

)

Terminates the application and traps the debugger if possible.

Only effective in debug build.

#define kzsDebugBreak

(

)

Traps the debugger if possible.

Only effective in debug build.

#define kzsErrorThrow	(		new_error,
			logMessage
	)

Return from the function with the given error code.

#define kzsErrorThrowFormat	(		new_error,
			formatArgs
	)

See Also

kzsErrorThrow formatArgs is the collection of format string and format arguments in parentheses, i.e. kzsErrorThrowFormat(KZS_ERROR_ARRAY_OUT_OF_BOUNDS, ("Shadow map array out of bounds for texture %s", textureName));

#define kzsExceptionThrow	(		new_exception,
			logMessage
	)

Return from the function with the given exception code.

#define kzsExceptionThrowFormat	(		new_exception,
			formatArgs
	)

See Also

kzsExceptionThrow formatArgs is the collection of format string and format arguments in parentheses, i.e. kzsExceptionThrowFormat(KZU_EXCEPTION_INCOMPLETE_BINARY_FILE, ("Binary file %s is truncated and does not contain requested data", binaryFileName));

#define kzsExceptionRethrow

(

param_exception)

Return from the function with the given exception code.

#define kzsErrorTest	(		test,
			new_error,
			logMessage
	)

Return from the function with the given error code, if the test is false.

Otherwise continue.

#define kzsErrorTestFormat	(		test,
			new_error,
			formatArgs
	)

See Also

kzsErrorTest formatArgs is the collection of format string and format arguments in parentheses, i.e. kzsErrorTestFormat(indexFound, KZC_ERROR_ELEMENT_NOT_FOUND, ("Child to be removed %s not found in parent clip %s", childClipName, parentClipName));

#define kzsExceptionTest	(		test,
			new_exception,
			logMessage
	)

Return from the function with the given exception code, if the test is false.

Otherwise continue.

#define kzsExceptionTestFormat	(		test,
			new_exception,
			formatArgs
	)

See Also

kzsExceptionTest formatArgs is the collection of format string and format arguments in parentheses, i.e. kzsExceptionTestFormat(file != KZ_NULL, KZS_EXCEPTION_FILE_OPEN_FAILED, ("Failed to open resource file %s", resourceFileName));

#define kzsErrorForward

(

error)

Return from the function with the given error code, if it is one.

If the error code is an exception, the code may or may not return (use kzsExceptionForward instead).

#define kzsExceptionForward

(

exception)

Return from the function with the given exception or error code, if it is one.

Otherwise continue.

#define kzsExceptionForwardAsError	(		exception,
			new_error,
			logMessage
	)

If the given exception code is an error, pass it forward.

If it is an exception, substitute it with the given error. Otherwise continue.

#define kzsExceptionForwardAsErrorFormat	(		test,
			new_error,
			formatArgs
	)

See Also

kzsExceptionForwardAsError formatArgs is the collection of format string and format arguments in parentheses, i.e. kzsExceptionForwardAsErrorFormat(result, KZC_ERROR_SHADER_RESTORE_TO_GPU_FAILED, ("Failed to restore shader %s on GPU", shaderName));

#define kzsErrorSubstitute	(		error,
			new_error,
			logMessage
	)

Return from the function with the given new error code, if the given old code is also an error.

Otherwise continue.

#define kzsExceptionSubstitute	(		error,
			new_exception,
			logMessage
	)

Return from the function with the given new exception code, if the given old code is also an exception.

Otherwise continue.

#define kzsErrorIf

(

error)

Test if the given error is an error.

#define kzsExceptionCatch	(		exception,
			exception_code
	)

Test if the given exception matches the specified exception code.

#define kzsExceptionCatchAll

(

exception)

Test if the given exception is an actual exception and not success or error.

#define KZS_NOT_IMPLEMENTED_YET

Macro to use to indicate that some code is not yet implemented.

#define KZS_NOT_IMPLEMENTED_YET_ERROR

Macro to use to indicate and throw error that some code is not yet implemented.

#define KZS_NOT_IMPLEMENTED_YET_ERROR_TEXT

(

message)

Macro to use to indicate and throw error with an explanation, that some code is not yet implemented.

#define kzsErrorLog	(		errorCode,
			message
	)

Logs the given error code with given message.

Typedef Documentation

typedef int kzsException

Exception code type definition, extends error.

typedef void(* KzsErrorCallback)(kzsError errorCode, kzString message)

Callback that is triggered in error situations.

typedef void(* KzsExceptionCallback)(kzsError errorCode, kzString message)

Callback that is triggered in exception situations.

Function Documentation

KZ_INLINE kzBool kzsAssertTest_private

(

void

)

Helper function for assert macro to suppress compiler warnings.

void kzsErrorThrowFunctionWithMessage_private	(	kzsError	error,
		kzString	message
	)

kzsErrorThrow macro wrapper to share code.

void kzsErrorThrowFunction_private

(

kzsError

error)

Wrapper for kzsErrorThrow() to share more code.

void kzsErrorLog_private	(	kzsError	errorCode,
		kzString	message,
		kzString	file,
		kzUint	line
	)

See Also

kzsErrorLog

void kzsAssert_private

(

void

)

See Also

kzsAssert

void kzsErrorBreak_private

(

void

)

See Also

kzsErrorBreak

void kzsDebugBreak_private

(

void

)

See Also

kzsDebugBreak

void kzsExceptionLog_private

(

kzString

message)

Exception log.

void kzsExceptionLogFormat_private	(	kzString	format,
			...
	)

Exception log format.

void kzsErrorOccurred_private	(	kzsError	errorCode,
		kzString	message
	)

Error callback.

void kzsExceptionOccurred_private	(	kzsError	errorCode,
		kzString	message
	)

Exception callback.

kzsError kzsErrorInitializeThread

(

kzMutableString *

storage)

Initializes error handling for thread.

kzsError kzsErrorDeinitializeThread

(

void

)

De-initializes error handling for thread.

kzsError kzsErrorInitialize

(

void

)

Initialize a global variable for error message storage.

kzsError kzsErrorUninitialize

(

void

)

De-initialize a global variable for error message storage.

void kzsErrorSetErrorCallback

(

KzsErrorCallback

callback)

Sets error callback.

void kzsErrorSetExceptionCallback

(

KzsExceptionCallback

callback)

Sets exception callback.

kzString kzsErrorGetLastErrorMessage

(

void

)

Gets last error message or empty string if there is no error.

kzString kzsErrorGetLastExceptionMessage

(

void

)

Gets the last exception message for the thread.

void kzsErrorFormatMessage_private	(	kzString	format,
			...
	)

Formats error message.

kzString kzsErrorGetLastFormattedErrorMessage_private

(

void

)

Gets last formatted error message.

Variable Documentation

KZ_HEADER_BEGIN typedef int kzsError

Error code type definition.