Main Page | Modules | Class List | File List | Class Members | File Members

gan_err_trace.h File Reference

#include <gandalf/common/gan_err.h>

Go to the source code of this file.


struct  Gan_ErrorTrace
 Stores details of single error in an error trace. More...


#define GAN_ET_YES   0
 Values for the 'f_spare' and 'f_static_message' in the Gan_ErrorTrace structure.
#define GAN_ET_NO   1


typedef Gan_ErrorTrace Gan_ErrorTrace
 Stores details of single error in an error trace.

Detailed Description

Module: Error trace

Part of: Gandalf Exception Handling

2005/10/18 16:30:47
Copyright: (c) 2000 Industrial Research Limited

Short Desc: Data structure and management functions for error trace Description: This module implements the error trace used in gan_err.[ch].

An error trace is a last-in first-out (LIFO) stack for temporarily holding details of multiple error events until an application is ready to read the stack.

The stack is usually flushed by the function in a sequence of nested calls that initially detects an error. As the call stack unwinds the successive functions also register errors, but they should not flush the error trace.

The stack is implemented as a linked list of error records. If in the process of allocating heap memory for a new error record a memory error occurs, then this is refered to as a deep error.

The stack always maintains two preallocated and unused error records for storing the details of the deep error and the error that was in the process of being registered when the deep error occured.

Even if the top of the stack holds a deep error record and the two preallocated records are used, new errors can still be registered into the trace. These attempts may lead to repeated deep errors, in which case the top deep error serves as an indicator of the deep continuing error state. However, if the registration process is successful (because in the intervening time, some external agent has free'd heap memory) the old deep error record is left on the stack and the new errors are registered on top of it.

To ensure that the stack has at least two preallocated records at process startup time, the bottom and second to bottom records of the stack use statically allocated memory. These can never be dynamically free'd.

To do this, an external module must define two static error records. In gandalf/common/gan_err.c, this is implemented as:

Gan_ErrorTrace record_last = {NULL, GAN_ET_YES, GAN_ET_NO, GAN_ET_YES, NULL, GAN_EC_DFT_SPARE, NULL, 0,NULL}; Gan_ErrorTrace record_2nd_last = {&record_last, GAN_ET_YES, GAN_ET_NO, GAN_ET_YES, NULL,GAN_EC_DFT_SPARE, NULL,0,NULL};

Gan_ErrorTrace * gan_et_trace_top =

The symbol gan_et_trace_top refers to the current top of stack and is passed into the functions defined in this module as argument 1.

NB. A statically allocated string containing the deep error text message must also exist, but this is defined in gandalf/common/gan_err_trace.c.

Generated on Fri Mar 17 12:44:51 2006 by  doxygen