Version 7.0
Copyright © 2021 Lowell D. Thomas
APG
… an ABNF Parser Generator
Data Structures | Macros | Functions
exception.h File Reference

Structures and macros for exception handling. More...

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Data Structures

struct  exception
 A structure to describe the type and location of a caught exception. More...
 

Macros

#define BAD_CONTEXT   99
 Application exit code when no exception context is available. More...
 
#define XTHROW(ctx, msg)   vExThrow((ctx), (msg), __LINE__, __FILE__, __func__)
 Exception throw macro. More...
 
#define XCTOR(e)
 This macro will initialize an exception structure and prepare entry to the "try" block. More...
 

Functions

void vExCtor (exception *spException)
 Initialize an exception structure. More...
 
abool bExValidate (exception *spException)
 Test an exception structure for validity. More...
 
void vExThrow (exception *spException, const char *cpMsg, unsigned int iLine, const char *cpFile, const char *cpFunc)
 Throws an exception. More...
 
void vExRethrow (exception *spMemFrom, exception *spMemTo)
 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

Structures and macros for exception handling.

Definition in file exception.h.

Macro Definition Documentation

◆ BAD_CONTEXT

#define BAD_CONTEXT   99

Application exit code when no exception context is available.

Applications will exit with this error code if the user presents an object member function with a bad context pointer.

Definition at line 42 of file exception.h.

◆ XCTOR

#define XCTOR (   e)
Value:
vExCtor(&e);\
if(setjmp(e.aJmpBuf) == 0){ \
e.try = APG_TRUE; \
}else{ \
e.try = APG_FALSE; \
}

This macro will initialize an exception structure and prepare entry to the "try" block.

For an example of usage with an explanation of its operation, see the example in Appendix A.

Parameters
eMust be an exception structure, not a pointer.

Definition at line 77 of file exception.h.

◆ XTHROW

#define XTHROW (   ctx,
  msg 
)    vExThrow((ctx), (msg), __LINE__, __FILE__, __func__)

Exception throw macro.

With this single-line macro, the user can specify an error-specific message and the macro will fill in the file, function and line information and call the function to excecute the throw.

Parameters
ctxPointer to a valid memory context previously returned from vpMemCtor().
msgPointer to an error message.

Definition at line 67 of file exception.h.

Function Documentation

◆ bExValidate()

abool bExValidate ( exception spException)

Test an exception structure for validity.

Parameters
spExceptionpointer 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
spExceptionpointer 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
spExFromPointer to the exception to copy from. Silently exits with BAD_CONTEXT exit code if not initialized.
spExToPointer 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
spExA pointer to an exception structure previously initialized with vExCtor(). Silently exits with BAD_CONTEXT exit code if not initialized.
cpMsgThe user's description of the error.
uiLineThe line number where the error occurred.
cpFileThe file name where the error occurred.
cpFuncThe function name where the error occurred.

Definition at line 87 of file exception.c.

APG_TRUE
#define APG_TRUE
Definition: apg.h:291
vExCtor
void vExCtor(exception *spException)
Initialize an exception structure.
Definition: exception.c:57
APG_FALSE
#define APG_FALSE
Definition: apg.h:292
APG Version 7.0 is licensed under the 2-Clause BSD License,
an Open Source Initiative Approved License.