Main Page   Modules   Compound List   File List   Compound Members   File Members  

gan_err.h File Reference

#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.

Gan_ErrorReporterFunc gan_err_set_reporter (Gan_ErrorReporterFunc app_error_reporter)
 Installs an error reporter.

Gan_ErrorReporterFunc gan_err_get_reporter (void)
 Returns current error reporter.

void gan_err_report (void)
 Invokes current error reporter.

int gan_err_register_fileline (const char *func_name, int err_code, const char *file_name, int line_number, const char *message)
 Registers occurence of an error.

void gan_err_set_trace (Gan_TraceMode trace_mode)
 Enable or disable use of trace to store error details.

void gan_err_flush_trace (void)
 Flush all errors in trace.

int gan_err_get_error_count (void)
 Gets the number of errors in error trace.

int gan_err_get_error (int n, const char **func_name, int *err_code, const char **file_name, int *line_number, const char **message)
 Gets details of n-th error stored in the error trace.

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.


Detailed Description

Module: Exception Handling

Part of: Gandalf Library

Revision: Last edited: Author:

Copyright: (c) 2000 Industrial Research Limited

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 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.


Function Documentation

void gan_err_flush_trace void   
 

Flush all errors in trace.

Returns:
No value.
Flush all errors in error trace
Note:
Traverse error trace from start to finish deleting all error records (except two reserved ones which are transparent to this module).

int gan_err_get_error int    n,
const char **    func_name,
int *    err_code,
const char **    file_name,
int *    line_number,
const char **    message
 

Gets details of n-th error stored in the error trace.

Parameters:
n Index of requested error [1..N]
func_name Name of function in which error occurs
err_code Numeric code of error
file_name Name of file in which error occurs
line_number Line in file at which error occurs
message Message string describing error
Returns:
Status of n-th error.
If any of above pointers are NULL, then those details are not returned.

Gets details of n-th error. n=1 refers to the most recent error registered in error trace. Usually gan_err_get_error_count() is called to obtain the number of error records in the trace. Return values:

  • #(GAN_EC_DFT + Index 'n' out of bounds,
  • #(GAN_EC_DFT + Error trace is empty (regardless of requested n)
  • #0 Otherwise.

Warning:
The returned strings (func_name, file_name, message) are not guaranteed to exist at a later time, nor should they be modified in place. Therefore the calling function must either use the returned strings immediately or make copies.
Because the stack is numbered from the top (1=most recent) an arbitrary index i may refer to different error records at different times. However, index 1 always refers to the most recent error.

See also:
gan_err_get_error_count().

int gan_err_get_error_count void   
 

Gets the number of errors in error trace.

Returns:
Number of errors in error trace.
Gets the number of errors in error trace.

See also:
gan_err_get_error().

Gan_ErrorReporterFunc gan_err_get_reporter void   
 

Returns current error reporter.

Returns:
Pointer to current error reporter, or #((Gan_ErrorReporterFunc) 0) or #((Gan_ErrorReporterFunc) 1).
Returns current error reporter.

See also:
gan_err_set_reporter().

int gan_err_register_fileline const char *    func_name,
int    err_code,
const char *    file_name,
int    line_number,
const char *    message
 

Registers occurence of an error.

Parameters:
func_name Name of function in which error occurs
err_code Numeric code of error
file_name Name of file in which error occurs
line_number Line in file at which error occurs
message Message string describing error
Returns:
The error number of error registered. #(GAN_EC_DFT + if a deep error occurs, err_code otherwise.
Registers occurence of an error. Intended to be called at the lowest function level immediately after the occurence of an error, and called at every level of the function call stack during unwinding, until the error is handled, or it unwinds into a function level where a different error handling mechanism is used.

If the trace mode is #GAN_ERR_TRACE_OFF, this function causes the current error reporter to called immediately. If the trace mode is #GAN_ERR_TRACE_ON, this function causes the details of the error to be placed onto an error trace. The error details are reported in "batch" at a later time upon invokation of gan_err_report().

Warning:
#(GAN_EC_DFT + is registered in the top record of the error trace if a deep error occurs. The error requested to be registered is placed in the second top record of the error trace. This error may be missing the message string, because it may have been the process of allocating memory for this string that caused the deep error to occur.
This function is typically called using the macro gan_err_register().

See also:
gan_err_register() (macro), gan_err_set_trace().
Note:
If trace mode is off then call error reporter immediately, otherwise push error details onto error trace.

void gan_err_report void   
 

Invokes current error reporter.

Returns:
No value.
Invokes current error reporter. That's all. It is the responsibility of the error reporter to traverse the error trace, read the details of each error, and to report those details in whatever application specific manner it chooses.

This function is automatically called from gan_err_register_fileline() when trace mode is OFF.

Warning:
The error reporter will not be called if gan_err_set_reporter(#((Gan_ErrorReporterFunc) 1)) has been called. The default error reporter is called when gan_err_set_reporter(#((Gan_ErrorReporterFunc) 0));
See also:
gan_err_set_trace(), gan_err_set_reporter().

Gan_ErrorReporterFunc gan_err_set_reporter Gan_ErrorReporterFunc    app_error_reporter
 

Installs an error reporter.

Parameters:
app_error_reporter Pointer to an application defined function
Returns:
Pointer to previously installed error reporter, if successful. NULL otherwise.
This exception module allows an application defined function to be called when an error is reported using gan_err_report(). gan_err_set_reporter() installs this error reporter. app_error_reporter should be a pointer to an application defined function to access error details, or the macros:
  • ((Gan_ErrorReporterFunc) 0) To set default error reporter
  • ((Gan_ErrorReporterFunc) 1) To ignore error reporting

If ((Gan_ErrorReporterFunc) 0) is provided, then the default error reporter (see below) is installed.

Warning:
The default error reporter simply writes a message to stderr. The exception module is initialised to use the default error reporter.
See also:
gan_err_get_reporter().
Note:
Other functions that invoke the current error handler must check first if it is set to #((Gan_ErrorReporterFunc) 1). If so, ignore the invocation. gan_err_current_reporter() is module scope variable.

void gan_err_set_trace Gan_TraceMode    trace_mode
 

Enable or disable use of trace to store error details.

Parameters:
trace_mode Whether to switch trace mode on or off
Returns:
No value.
A trace is a data structure that stacks error details for subsequent reporting (activated by gan_err_report()). If trace is disabled by passing trace_mode as #GAN_ERR_TRACE_OFF, then errors are reported immediately upon being registered i.e. when gan_err_register() is called. Otherwise trace mode is switched on by passing #GAN_ERR_TRACE_ON.

Warning:
Trace mode is initialised to #GAN_ERR_TRACE_OFF. Any non-zero trace_mode is assumed equivalent to #GAN_ERR_TRACE_OFF. When trace is turned off, the trace is flushed immediately.
See also:
gan_err_report(), gan_err_register().


Generated on Mon Oct 13 16:14:41 2003 by doxygen1.3-rc1