exception.c File Reference

Exception handling functions. More...

#include "./lib.h"

Include dependency graph for exception.c:

Go to the source code of this file.

Functions
void	vExCtor (exception *spException)
	Initialize an exception structure. More...
abool	bExValidate (exception *spException)
	Test an exception structure for validity. More...
void	vExThrow (exception *spEx, const char *cpMsg, unsigned int uiLine, const char *cpFile, const char *cpFunc)
	Throws an exception. More...
void	vExRethrow (exception *spExFrom, exception *spExTo)
	Re-throw an exception from the "from" try/catch-block scope to the "to" try/catch-block scope. More...
void	vExContext ()
	Handles bad context pointers. More...

Detailed Description

Exception handling functions.

Almost all of APG's objects and other facilities throw exceptions back to the parent scope to report fatal errors. The structure and macros in exception.h and the functions here facilitate all of APG's exception handling features. For a quick usage demonstration see the example in Appendix A.

Definition in file exception.c.

Function Documentation

bExValidate()

abool bExValidate

(

exception *

spException

)

Test an exception structure for validity.

Parameters

spException

pointer to an uninitialized exception structure.

Returns

True if the structure is valid (the result of vExCtor()). False otherwise.

Definition at line 70 of file exception.c.

vExContext()

void vExContext

(

)

Handles bad context pointers.

When a bad context is passed to a member function, the function obviously has no knowledge of what exception object to use for reporting. Therefore, the application silently exits with a BAD_CONTEXT exit code.

Debugging hint: If an application mysteriously exits, check the exit code. If it is BAD_CONTEXT. place a break point on this function and use the debugger's call stack to work backwards to the offending call with the bad context pointer.

Definition at line 126 of file exception.c.

vExCtor()

void vExCtor

(

exception *

spException

)

Initialize an exception structure.

Any attempt to use an exception structure that has not been initialized will cause the application to silently exit with a BAD_CONTEXT exit code. Note that, despite the name, this function does not create the exception it just initializes it. There is no corresponding destructor.

For complete preparation for the try and catch blocks, see XCTOR().

Parameters

spException

pointer to an uninitialized exception structure.

Returns

The structure is cleared and initialized.

Definition at line 57 of file exception.c.

vExRethrow()

void vExRethrow	(	exception *	spExFrom,
		exception *	spExTo
	)

Re-throw an exception from the "from" try/catch-block scope to the "to" try/catch-block scope.

Parameters

spExFrom	Pointer to the exception to copy from. Silently exits with BAD_CONTEXT exit code if not initialized.
spExTo	Pointer to the exception to copy and throw to. Silently exits with BAD_CONTEXT exit code if not initialized.

Definition at line 105 of file exception.c.

vExThrow()

void vExThrow	(	exception *	spEx,
		const char *	cpMsg,
		unsigned int	uiLine,
		const char *	cpFile,
		const char *	cpFunc
	)

Throws an exception.

Uses longjmp() to transfer control from the try block to the application's catch block.

Parameters

spEx	A pointer to an exception structure previously initialized with vExCtor(). Silently exits with BAD_CONTEXT exit code if not initialized.
cpMsg	The user's description of the error.
uiLine	The line number where the error occurred.
cpFile	The file name where the error occurred.
cpFunc	The function name where the error occurred.

Definition at line 87 of file exception.c.