File name: error.hpp, error.cpp
contents: error report macros, global error functions
use: provide a common interface for all error outputs of the
simulation
Note: this description does not include error.h,
which belongs to the network driver and has nothing to do with SimUTC error
handling.
global items used by the functions:
const int
MessageLen: the maximum length of the complete error message.
#define ABORTFUNC:
the name of the function that is called to stop the program if an assert
fails. The function depends on the operating system: if PSOS_SIM
is defined, then the macro is set to k_fatal. Otherwise, it is
set to abort.
#define ABORTPARAMS:
the parameters of the abort function. Again, the value of the macro depends
on the operating system: if PSOS_SIM
is defined, then the macro is set to 0x10000, K_LOCAL. The first
parameter is the error code that is set by k_fatal(), the second
parameter specifies that only the local node should be shut down. If PSOS_SIM
is not defined, the macro is void.
macros:
All macros operate on the same principle: if NDEBUG is defined, the macro expands to void (i.e., it behaves as if it were not there). Else, it calls the global function ReportError (EReportType, char *, int, char *) (see below) and then does something specific to the macro used. Since the macro is expanded, if you use it in a class that has a function with the same prototype as the above-mentioned global ReportError(), the function of the class is called instead. You can use this trick to add additional information like the identifier(s) and type of the module that is reporting the error. Even if you are overloading the global function and adding own information, always call one of the additional global functions declared in error.hpp and return their return values. In the following description of the macros, it is assumed that NDEBUG has not been defined.
Assert (expr):
If expr evaluates to zero, the macro calls ReportError()
with type Asserting, which causes ReportError() to stop
the program. If expr evaluates to non-zero, nothing happens. The
macro has no value.
Check(expr):
If expr evaluates to zero, the macro calls ReportError()
with type Checking and has the value of ReportError(),
which should be 0. If expr evaluates to non-zero, nothing happens,
and the macro has the value 1.
Report(expr):
expr is *not* evaluated. The macro calls ReportError()
with type Reporting and has no value.
global error report functions:
enum EReportType:
Asserting, Checking, Reporting
int ReportError
(EReportType type, char *file, int line, char *expression): Report
the error of type type in expression expression, which
has occurred in file file at line line. If type==Asserting,
then abort() is called and the function does not return. The other
types do not stop program execution and should always return 0. The error
message itself is assembled into a string and give to an error handler
object, which must be installed to see any error outputs.
int ReportError
(EReportType type, char *file, int line, char *expression, EModule module):
Adds the module type to the basic error output.
int ReportError
(EReportType type, char *file, int line, char *expression, EModule module,
SINT32 moduleID);
Adds the module type and a module identifier to the basic error output.
int ReportError
(EReportType type, char *file, int line, char *expression, EModule module,
SINT32 nodeID, int area);
Adds the module type and two module identifiers to the basic error
output.
void ReportMessage
(const char *msg): Just passes on the message to the error handler
(if installed). The function does not append any additional information.
(de-)installing an error handler:
void InstallErrorHandler
(CErrorHandler *handler): Installs an error handler (cf. errbase.hpp);
error.cpp keeps a pointer to that handler and passes all error
messages to it. As long as no handler is installed, the pointer is NULL
and error messages are discarded, so you must install a handler if you
want to see the error messages of your code.
void DeinstallErrorHandler
(): Sets the internal pointer to the error handler to NULL.
local variables defined in the implementation file:
CErrorHandler
*errorHandler: the currently used error handler. If the variable is
NULL, the error messages are discarded.
default: NULL
local functions defined in the implementation file:
int GetReturnValue
(EReportType type): returns the value that the calling ReportError()
function should return, which is 0. If type is Asserting,
then if an error handler exists it is deleted (causing all messages that
are still kept to be flushed), and at last the function calls ABORTFUNC
(ABORTPARAMS) to stop program execution. Thus, the function does not
return.
char *ModuleToString
(EModule module): converts the module enumeration into a string constant,
which is returned.
void PrintFileSpecs
(EReportType type, char *expression, char *file, int line, char *msg):
Assembles the basic error report message that is printed as the first line
by all ReportError() functions.