Error Handling
[Common]

Classes
struct	Gan_ErrorTrace
	Stores details of single error in an error trace. More...
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)
#define	GAN_ET_YES   0
	Values for the 'f_spare' and 'f_static_message' in the Gan_ErrorTrace structure.
#define	GAN_ET_NO   1
#define	GAN_ERROR_FAILURE   1
#define	GAN_ERROR_NOT_IMPLEMENTED   2
#define	GAN_ERROR_REF_OUTSIDE_MATRIX   3
#define	GAN_ERROR_CANT_REALLOC   4
#define	GAN_ERROR_MALLOC_FAILED   5
#define	GAN_ERROR_DIFFERENT_DIMS   6
#define	GAN_ERROR_INCOMPATIBLE   7
#define	GAN_ERROR_MATRIX_NOT_SQUARE   8
#define	GAN_ERROR_INPLACE_TRANSPOSE   9
#define	GAN_ERROR_INPLACE_MULTIPLY   10
#define	GAN_ERROR_ARRAY_TOO_SMALL   11
#define	GAN_ERROR_ILLEGAL_TYPE   12
#define	GAN_ERROR_NO_IMPLICIT_INV   13
#define	GAN_ERROR_CLAPACK_ILLEGAL_ARG   14
#define	GAN_ERROR_CBLAS_ILLEGAL_ARG   15
#define	GAN_ERROR_CBLAS_FAILED   16
#define	GAN_ERROR_NOT_POSITIVE_DEFINITE   17
#define	GAN_ERROR_DIVISION_BY_ZERO   18
#define	GAN_ERROR_SQRT_OF_NEG_NUMBER   19
#define	GAN_ERROR_NO_CONVERGENCE   20
#define	GAN_ERROR_SINGULAR_MATRIX   21
#define	GAN_ERROR_IMAGE_TOO_SMALL   22
#define	GAN_ERROR_NO_DATA   23
#define	GAN_ERROR_NOT_ENOUGH_DATA   24
#define	GAN_ERROR_OPENING_FILE   25
#define	GAN_ERROR_CORRUPTED_FILE   26
#define	GAN_ERROR_OUTSIDE_RANGE   27
#define	GAN_ERROR_TOO_LARGE   28
#define	GAN_ERROR_TOO_SMALL   29
#define	GAN_ERROR_TRUNCATED_FILE   30
#define	GAN_ERROR_NOT_INITIALISED   31
#define	GAN_ERROR_ILLEGAL_ARGUMENT   32
#define	GAN_ERROR_CCMATH_FAILED   33
#define	GAN_ERROR_NO_SOLUTION   34
#define	GAN_ERROR_READING_FROM_FILE   35
#define	GAN_ERROR_WRITING_TO_FILE   36
#define	GAN_ERROR_EXTERNAL_LIBRARY_CALL   37
#define	GAN_ERROR_ILLEGAL_IMAGE_TYPE   38
#define	GAN_ERROR_ILLEGAL_IMAGE_FORMAT   39
#define	GAN_ERROR_ILLEGAL_IMAGE_FILE_FORMAT   40
#define	GAN_ERROR_ILLEGAL_IMAGE_CHANNEL   41
Typedefs
typedef void(*	Gan_ErrorReporterFunc )(void)
	A type definition for an application supplied error handling function.
typedef Gan_ErrorTrace	Gan_ErrorTrace
	Stores details of single error in an error trace.
Enumerations
enum	Gan_TraceMode { GAN_ERR_TRACE_OFF, GAN_ERR_TRACE_ON }
	Error trace on/off. More...
Functions
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.
int	gan_err_register_fileline (const char *func_name, int err_code, const char *file_name, int line_number, const char *message, int number)
	Registers occurence of an error.
void	gan_err_report (void)
	Invokes current error reporter.
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, int *number)
	Gets details of n-th error stored in the error trace.
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.
Gan_ErrorTrace *	gan_et_push (Gan_ErrorTrace *et_top, const char *func_name, int err_code, const char *file_name, int line_number, const char *message, int number)
	Pushes a new error recorded onto error trace.
int	gan_et_get_record_count (Gan_ErrorTrace *et_record)
	Counts number of records in trace from specified starting point.
Gan_ErrorTrace *	gan_et_get_record_next (Gan_ErrorTrace *et_record)
	Returns pointer to next non-spare error record after et_record.
Gan_ErrorTrace *	gan_et_get_record_first (Gan_ErrorTrace *et_record)
	Returns pointer to first non-spare error record from et_record.
Gan_ErrorTrace *	gan_et_flush_trace (Gan_ErrorTrace *a_record)
	Flush all errors in error trace.
const char *	gan_err_string (int error_code)
	Returns error message corresponding to given error code.
const char *	gan_err_string_at_lowest_level (void)

---

Define Documentation

#define GAN_EC_OK   0

Default error codes used within the error module.

#define GAN_ERR_DFL   ((Gan_ErrorReporterFunc) 0)

Defines to specify error reporting behaviour. Used by gan_err_set_reporter().

---

Typedef Documentation

typedef void(* Gan_ErrorReporterFunc)(void)

A type definition for an application supplied error handling function. Modelled after __kernel_signhandler_t in /usr/include/linux/posix/signal.h

typedef struct Gan_ErrorTrace Gan_ErrorTrace

Stores details of single error in an error trace. Error trace is a last in, first out stack of structures containing details of recorded errors. The stack is implemented as a linked list that is traversed by following 'prev' links. The bottom (oldest) and 2nd to bottom record of the error trace are statically allocated, while all others are dynamically allocated (malloc'd). Important that gan_et_flush doesn't try to free() the statically allocated records. Parameters: prev  Address of previous (next oldest) record in error trace Prev for last record is NULL. f_static_record  Is this record statically or dynamically allocated If it's static, don't try and free() it. f_static_message  Is the text message in this record is contained in a statically or dynamically allocated char array. If it's static, don't try and free() it. f_spare  Whether is record contains details for an error, or is spare. func_name  Name of function in which error occurs err_code  Numeric code of error. Default set is defined in gan_exception_codes*.h file_name  Name of file in which error occurs line_number  Line in file at which error occurs message  Message string describing error number  Number attached to error A record has the status "spare" and "not spare". A spare record is always kept in advance so that a deep error can be registered in a memory shortage situation. A record is designated spare when it carries and error code of EC_DFT_SPARE. The text message pointed to by "message" normally resides in a dynamically allocated char array, except for the deep error message which resides in a static char array. Therefore if the error code is EC_DFT_DEEP_ERROR, then the message char array should never be subjected to free().

---

Enumeration Type Documentation

enum Gan_TraceMode

Error trace on/off. A Trace is a data structure containing complete history of error information collected from the time the initiating error occurs, to the time it unwinds to the application. GAN_ERR_TRACE_ON Indicates that a trace structure is built and that the error details are transfered to the application using gan_err_report(). The function gan_err_register() adds an error to the trace. GAN_ERR_TRACE_OFF Indicates that no trace structure be constructed. Instead error details are reported immediately during gan_err_register().

---

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, int *  number )

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 number  Number attached to 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().

void gan_err_register (  const char *  func_name, int  err_code, const char *  message )

Macro: Registers an error. Parameters: func_name  Name of function in which error occurs err_code  Numeric code of error message  Message string describing error Returns: No value. This macro abbreviates gan_err_register_fileline() by hiding the file and line argument. Refer to gan_err_register_fileline() for details on using this macro. See also: gan_err_register_with_number().

int gan_err_register_fileline (  const char *  func_name, int  err_code, const char *  file_name, int  line_number, const char *  message, int  number )

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 number Number to attach to error, default 0 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_register_with_number (  const char *  func_name, int  err_code, const char *  message, int  number )

Macro: Registers an error.with a number attached. Parameters: func_name  Name of function in which error occurs err_code  Numeric code of error message  Message string describing error number  Number to attach to error Returns: No value. This macro abbreviates gan_err_register_fileline() by hiding the file and line argument. Refer to gan_err_register_fileline() for details on using this macro. See also: gan_err_register().

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

const char * gan_err_string (  int  error_code  )

Returns error message corresponding to given error code. Returns: Error string

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. Parameters: test  An expresion to test for true/false value funcname  The function name in which this test occurs code  An error code to set if the test fails message  An error message for if the test fails Returns: No value. If the test fails, the error handler module is invoked with the given funcname, code and message, and GAN_FALSE is returned by the calling function. If NDEBUG is defined, the test is ignored. See also: gan_err_assert_ptr().

double gan_err_test_double (  Gan_Bool  test, char *  funcname, int  code, char *  message )

Macro: Tests expression, fails and invokes error handler if false. Parameters: test  An expresion to test for true/false value funcname  The function name in which this test occurs code  An error code to set if the test fails message  An error message for if the test fails Returns: No value. If the test fails, the error handler module is invoked with the given funcname, code and message, and DBL_MAX is returned by the calling function. If NDEBUG is defined, the test is ignored. See also: gan_err_assert_ptr().

float gan_err_test_float (  Gan_Bool  test, char *  funcname, int  code, char *  message )

Macro: Tests expression, fails and invokes error handler if false. Parameters: test  An expresion to test for true/false value funcname  The function name in which this test occurs code  An error code to set if the test fails message  An error message for if the test fails Returns: No value. If the test fails, the error handler module is invoked with the given funcname, code and message, and FLT_MAX is returned by the calling function. If NDEBUG is defined, the test is ignored. See also: gan_err_assert_ptr().

int gan_err_test_int (  Gan_Bool  test, char *  funcname, int  code, char *  message )

Tests expression, fails and invokes error handler if false. Parameters: test  An expresion to test for true/false value funcname  The function name in which this test occurs code  An error code to set if the test fails message  An error message for if the test fails Returns: No value. If the test fails, the error handler module is invoked with the given funcname, code and message, and -1 is returned by the calling function. If NDEBUG is defined, the test is ignored. See also: gan_err_assert_ptr().

void* gan_err_test_ptr (  Gan_Bool  test, char *  funcname, int  code, char *  message )

Macro: Tests expression, fails and invokes error handler if false. Parameters: test  An expresion to test for true/false value funcname  The function name in which this test occurs code  An error code to set if the test fails message  An error message for if the test fails Returns: No value. If the test fails, the error handler module is invoked with the given funcname, code and message, and NULL is returned by the calling function. If NDEBUG is defined, the test is ignored. See also: gan_err_assert_bool().

int gan_err_test_uint (  Gan_Bool  test, char *  funcname, int  code, char *  message )

Macro: Tests expression, fails and invokes error handler if false. Parameters: test  An expresion to test for true/false value funcname  The function name in which this test occurs code  An error code to set if the test fails message  An error message for if the test fails Returns: No value. If the test fails, the error handler module is invoked with the given funcname, code and message, and UINT_MAX is returned by the calling function. If NDEBUG is defined, the test is ignored. See also: gan_err_assert_ptr().

Gan_ErrorTrace * gan_et_flush_trace (  Gan_ErrorTrace *  et_record  )

Flush all errors in error trace. Parameters: a_record  The top record in error trace Returns: Pointer to new top of error trace. Flush all errors in error trace. Warning: et_record must be top record in trace, or else residual trace will malformed (i.e. not NULL terminated). Note: Traverse error trace from start to finish deleting all records, except leaving the final two which are reserved to store deep error information. Don't free free_me, but mark it spare, and continue

int gan_et_get_record_count (  Gan_ErrorTrace *  et_record  )

Counts number of records in trace from specified starting point. Parameters: et_record  Pointer to top record of error trace Returns: The number of records in trace from and including et_record to bottom of trace. Counts number of non-spare records in trace from and including et_record to the last (oldest) record in stack. Total number of non-spare records in error trace is returned when the top of error trace is specified by et_record.

Gan_ErrorTrace * gan_et_get_record_first (  Gan_ErrorTrace *  et_record  )

Returns pointer to first non-spare error record from et_record. Parameters: et_record  Pointer to error record in error trace for which error code is to be read. Returns: Error code of specified error record, or NULL if et_record is NULL, or no non-spare records found. Returns pointer to first non-spare error record from and including et_record.

Gan_ErrorTrace * gan_et_get_record_next (  Gan_ErrorTrace *  et_record  )

Returns pointer to next non-spare error record after et_record. Parameters: et_record  Pointer to the Error record preceding the one that will be returned Returns: Returns pointer to next non-spare error record after et_record. Warning: If et_record is NULL, this function returns NULL.

Gan_ErrorTrace * gan_et_push (  Gan_ErrorTrace *  et_top, const char *  func_name, int  err_code, const char *  file_name, int  line_number, const char *  message, int  number )

Pushes a new error recorded onto error trace. Parameters: et_top  Pointer to top record of error trace 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 number  Number attached to error Returns: Pointer to new top of list. Note: A memory error may occur inside gan_et_push() because this function calls malloc(): this is called a deep error. Two records are reserved at the top of the trace to register the occurrence of a deep error (top) and to register the error (second to top) that identified by the error code (GAN_EC_DFT +. A deep error is treated no differently from any other error, except that the reserved records are used. Therefore, even if the trace registers a deep error, gan_et_push() will attempt to register subsequent errors if memory allows. Each time a deep error occurs, gan_et_push() will attempt to register a deep error. Deep error that follow a normal error will always succeed in being registered. A deep error that follows a deep error may not succeed in being registered because of memory constraints -- however, the top of the trace will nevertheless show that the most recent error was a deep error. Errors requested to be registered while no system memory exists will be lost permanently. The oldest two records of the LIFO stack are statically allocated. This ensures that at any time a deep error can be registered. gan_et_push() or any other function in the exception handling module makes no attempt to free memory for the purpose of avoid a deep error. Memory management firmly rest with an external component (i.e. library or application). Such behaviour is consistent with the policy that the application (or library) is the master and the exception handling module is the slave. The role of the exception module is to provide full error information to the application, so that the application has the opportunity to handle the error in a contextually meaningful way. The psuedo code for handling deep errors is as follows: ----------------------------------------------------------------------- gan_et_push() Have 2 records spare? yes: register_error no: try to allocate records so that we have 2 spare on error: deep_error register_error ----------------------------------------------------------------------- register_error() (into second spare) do the best to furnish info into 2nd spare record on error: leave the error message part blank deep_error() mark 2nd record as 'not spare' allocate a new record and put at top of stack on error: deep_error() ----------------------------------------------------------------------- deep_error() Have 1 spare record (in which to write deep error) yes: write deep error into spare record no : do nothing, return

---