#include <gandalf/common/misc_defs.h>Go to the source code of this file.
Defines | |
| #define | GAN_ERR_DFL ((Gan_ErrorReporterFunc) 0) |
| #define | GAN_ERR_IGN ((Gan_ErrorReporterFunc) 1) |
| #define | GAN_EC_OK 0 |
| #define | GAN_EC_FAIL -1 |
| #define | GAN_EC_BASE 0 |
| #define | GAN_EC_DFT (GAN_EC_BASE+1000) |
| #define | GAN_EC_DFT_DEEP_ERROR (GAN_EC_DFT + 1) |
| #define | GAN_EC_DFT_SPARE (GAN_EC_DFT + 2) |
| #define | GAN_EC_DFT_BAD_N (GAN_EC_DFT + 3) |
| #define | GAN_EC_DFT_EMPTY (GAN_EC_DFT + 4) |
Typedefs | |
| typedef void(* | Gan_ErrorReporterFunc )(void) |
| A type definition for an application supplied error handling function. | |
Enumerations | |
| enum | Gan_TraceMode { GAN_ERR_TRACE_OFF, GAN_ERR_TRACE_ON } |
| Error trace on/off. More... | |
Functions | |
| void | gan_err_register (const char *func_name, int err_code, const char *message) |
| Macro: Registers an error. | |
| void | gan_err_register_with_number (const char *func_name, int err_code, const char *message, int number) |
| Macro: Registers an error.with a number attached. | |
| Gan_Bool | gan_err_test_bool (Gan_Bool test, char *funcname, int code, char *message) |
| Macro: Tests expression, fails and invokes error handler if false. | |
| int | gan_err_test_int (Gan_Bool test, char *funcname, int code, char *message) |
| Tests expression, fails and invokes error handler if false. | |
| int | gan_err_test_uint (Gan_Bool test, char *funcname, int code, char *message) |
| Macro: Tests expression, fails and invokes error handler if false. | |
| void * | gan_err_test_ptr (Gan_Bool test, char *funcname, int code, char *message) |
| Macro: Tests expression, fails and invokes error handler if false. | |
| double | gan_err_test_double (Gan_Bool test, char *funcname, int code, char *message) |
| Macro: Tests expression, fails and invokes error handler if false. | |
| float | gan_err_test_float (Gan_Bool test, char *funcname, int code, char *message) |
| Macro: Tests expression, fails and invokes error handler if false. | |
Part of: Gandalf Library
Short Desc: Module to handle errors, warning and information messages.
Description:
Definitions: library: a collection of code that can be used by disparate applications application: the code or program that utilises the library error module:a collection of code for centralised error handling private: a function that is intended to be called from the library public: a function that is intended to be called from the application error record: a struct holding error code, file name, line number, and text message for one error. error trace: a LIFO stack of error records, which allows temporary storage of error information until defered retrieval by application top record: the most recent error stored in trace detection: code that detects occurance of an error handling: action undertaken as a result of detecting an error. In library this typically involves registering the error and returning from current function with an error status. In application this typically involves invoking the reporter function. register: the process of placing an error into the trace flushing: the clearing of the error trace reporter: a function provided by the application to access error stored in trace and then communicating that information to the user or to a log. The reporter function must then flush the error trace.
Summary: The 'application' calls 'library' function A which calls 'library' function B, which has an error that is 'detected'. Function B 'flushes' the 'error trace' (because it is the last function called that uses the facilities of the 'error module', and then 'registers' the error details into the 'error trace' and unwinds to function A with a return value that indicates an error has occured. Function A tests the return value and 'detects' the error and so 'registers' an error into the 'trace' and unwinds to the 'application' with a return value that indicates an error has occured. The 'application' tests the return value and 'detects' that an error has occured so calls a facility in the 'error module' to report the error. The error report function in turn calls an 'application' supplied 'error reporter' function with a pointer to the 'error trace' as an argument. The address of the error trace is stored as a module scoped variable in the 'error module'. The 'error reporter' accesses the information contained in the 'error trace' using accessor functions and communicates the error details to the user or to a log in some application specific way.
Intent: The purpose of this the error module is to provide a mechanism by which generic reusable code (typically a library) can report errors to a variety of applications without the need to modify the library code for each new application context. That is, the error reporting mechanism of the library is highly decoupled from that of the application. Communication of error information from library to application is performed using a small and well defined interface.
Approach: The role of the library is to communicate full and unprocessed error information to the application. The role of the application is to access the error information and report it to the user. This demarcation of roles allows the application to use its own error reporting mechanism, without any need to embed application specific code in the library. The library achieves generality because it plays no role in reporting the error information, which usually requires system and application specific facilities.
Specifically, the library writes (registers) error information into a LIFO stack (error trace) which is built up as the error unwinds through the nested calls. When the library function called by the application finally returns -- with an error code -- the application uses an error reporter to access the errors details and processes that information in any way it chooses (e.g. displays an error dialogue box, logs the error in a database).
The library function at which a new error occurs must first flush the error trace before registering the error.
Consequences and liabilities: (1) The application is able to:
Usage notes for application writer: (see gan_err_example_app.c) No code is needed to initialise the error trace. But a error reporting function is optionally installed in the error module using gan_err_set_reporter(). The reporter is an application function of type Gan_ErrorReporterFunc, which is defined in gandalf/common/gan_err.h. The reporter must get the error count using gan_err_get_error_count() and then sequentially access the errors stored in the trace using gan_err_get_error(n), where n is the n-th error, and n=1 is the most recent error. If no error reporter is installed, then the error module provides a default reporter gan_err_default_reporter(), whose action is to print the error details into stderr. The function gan_err_set_reporter(GAN_ERR_DFL) causes the default error reporter to be used, and the call gan_err_set_reporter(GAN_ERR_IGN) inhibits the error reporter from being called. gan_err_set_reporter() returns the address of the error reporter that was replaced so that it can be reinstalled later.
When the application tests the return value of a library function and detects that an error has occured, it should call gan_err_report() which invokes the error reporter.
The application writer can choose not to buffer the error details in a trace, but instead have the library function report errors immediately, by automatically calling gan_err_report() inside gan_err_register(). No error trace is built up. If the application calls gan_err_report(), no errors are reported because the trace will be empty. Usage of the trace is controlled by gan_err_set_trace() with arguments GAN_ERR_TRACE_ON or GAN_ERR_TRACE_OFF.
Usage notes for library writer: (see gan_err_example_lib.h) When a error is detected at the deepest function call that uses the facilities of the error module, then gan_err_flush_trace() should be called, followed by gan_err_register(). As the subsequent library function unwinds, they should call gan_err_register() (but not gan_err_flush_trace()), and return with an error code. This continues until the call stack unwinds into the applicaton.
Multi-thread safe: A programmer attempting to use this module in a multithreaded system must heed all precautions attendent with using fully share memory address spaces. To make this module multithread safe, global locks must used to prevent concurrent access to the error trace.
PMN 2000-11-28 Created.
1.3.9.1