Detailed Description
Allow the bubbling up or errors in C.
Introduction
An exception structure is used to allow the bubbling up of errors, as C does not support exceptions in that way. This means that instead of an error causing a segmentation fault elsewhere, the exception is set and passed all the way up to be checked.
Creating
Exceptions are created by the caller using the FIFTYONE_DEGREES_EXCEPTION_CREATE macro which creates an exception pointer named "exception". This is then passed into any method which can potentially throw an exception.
Checking
An exception can be checked using the FIFTYONE_DEGREES_EXCEPTION_OKAY macro which will return true if there is no exception, or false if an exception has occurred.
Throwing
In the event that an exception has occurred in a method, it can be checked and thrown using the FIFTYONE_DEGREES_EXCEPTION_THROW macro. If the exception is okay, then nothing will be thrown by this macro, so it is safe to call as a "catch and throw" method. This will behave differently depending on whether it is used in the context of C or C++.
C : C does not support exceptions, so if there is an exception, the exception message will be printed to standard output, then the process will exit.
C++ : As C++ supports exceptions, a fatal exception with the message will be thrown. This can then be caught or handled in whichever way the caller sees fit.
Messages
The error message returned by an exception consists of the error message itself, the name of the source file which caused the error, the name of the function which caused the error and the line in the source file at which the error occurred.
Usage Example
Disabling
To improve performance, exception handling can be disabled completely by compiling with FIFTYONE_DEGREES_EXCEPTIONS_DISABLED. This changes all the macro calls to do nothing, meaning that no checks occur, and no exceptions are thrown.
Collaboration diagram for Exceptions:
Structs | |
| struct | fiftyoneDegreesException |
| Structure used to represent a 51Degrees exception and passed into methods that might generate exceptions. More... | |
Macros | |
| #define | FIFTYONE_DEGREES_EXCEPTION_SET(s) |
| Macro used to set an exception to a status code. | |
| #define | FIFTYONE_DEGREES_EXCEPTION_CLEAR |
| Macro used to clear an exception type. | |
| #define | FIFTYONE_DEGREES_EXCEPTION_CHECK(t) |
| Macro used to check if an exception status equals the value of t. | |
| #define | FIFTYONE_DEGREES_EXCEPTION_OKAY FIFTYONE_DEGREES_EXCEPTION_CHECK(FIFTYONE_DEGREES_STATUS_NOT_SET) |
| Macro used to check if there is no exception currently. | |
| #define | FIFTYONE_DEGREES_EXCEPTION_THROW fiftyoneDegreesExceptionCheckAndExit(exception); |
| Macro to print to standard error a message if an exception is set. | |
| #define | FIFTYONE_DEGREES_EXCEPTION_CREATE |
| Macro used to create an exception. | |
| #define | FIFTYONE_DEGREES_EXCEPTION_FAILED (FIFTYONE_DEGREES_EXCEPTION_OKAY == false) |
| Macro to test if the exception has been set and is failed. | |
Functions | |
| const char * | fiftyoneDegreesExceptionGetMessage (fiftyoneDegreesException *exception) |
| Returns an English error message for the exception. | |
| void | fiftyoneDegreesExceptionCheckAndExit (fiftyoneDegreesException *exception) |
| If the exception is set then will print a message to stderr and exit the process. | |
Macro Definition Documentation
◆ FIFTYONE_DEGREES_EXCEPTION_CHECK
| #define FIFTYONE_DEGREES_EXCEPTION_CHECK | ( | t | ) |
Macro used to check if an exception status equals the value of t.
Warning: this macro should be avoided in anything other than test code as when exceptions are disabled there will be unpredictable results. Using a local status variable for checks is a better pattern.
◆ FIFTYONE_DEGREES_EXCEPTION_CLEAR
| #define FIFTYONE_DEGREES_EXCEPTION_CLEAR |
Macro used to clear an exception type.
◆ FIFTYONE_DEGREES_EXCEPTION_CREATE
| #define FIFTYONE_DEGREES_EXCEPTION_CREATE |
Macro used to create an exception.
◆ FIFTYONE_DEGREES_EXCEPTION_SET
| #define FIFTYONE_DEGREES_EXCEPTION_SET | ( | s | ) |
Macro used to set an exception to a status code.
- Parameters
-
s status code to set
Function Documentation
◆ fiftyoneDegreesExceptionCheckAndExit()
| void fiftyoneDegreesExceptionCheckAndExit | ( | fiftyoneDegreesException * | exception | ) |
If the exception is set then will print a message to stderr and exit the process.
- Parameters
-
exception to check and exit if set
◆ fiftyoneDegreesExceptionGetMessage()
| const char * fiftyoneDegreesExceptionGetMessage | ( | fiftyoneDegreesException * | exception | ) |
Returns an English error message for the exception.
The caller must free the memory when they have finished consuming the error message. An exception holds no file name, so a message about a file says 'null'. A caller that has the status and the file name gets a message naming the file from fiftyoneDegreesStatusGetMessage.
- Parameters
-
exception to get a string message from
- Returns
- pointer to the newly allocated message string