NAME-
vzError - Error logging and reporting facilities
HEADER FILE-
#include <Volumizer2/Error.h>
PUBLIC METHOD SUMMARY
Logging Errors
| static void error ( |
vzErrorType error, const char* format=NULL, ...); |
| static void warn ( |
vzErrorType error, const char* format=NULL, ...); |
| static void log ( |
vzErrorSeverity severity, vzErrorType error, const char* format=NULL, ...); |
Printing Debug Messages
| static void message ( |
int debugLevel, const char* format, ...); |
Querying Last Error
Changing Error Handler
| static void setHandler ( |
ErrorHandler* handler, void* data=NULL); |
| static void getHandler ( |
ErrorHandler*& handler, void*& data); |
CLASS DESCRIPTION-
This class implements a mechanism for logging errors.
It consists of a collection of static methods that allow a
user-defined error routine to be setup to handle all logged
errors. The default error handler simply prints out the error message and
then calls abort() if the error severity is VZ_ERROR. The
error handler installed applies to all threads.
-
Regardless of the error handler in effect, the first error
encountered will be recorded and can be queried later using
getError().
The clear() can be used to reset the saved error to VZ_NO_ERROR.
Errors are recorded and cleared on a per-thread basis.
-
Each problem is classified as either an error or
a warning using the enum values VZ_ERROR or
VZ_WARNING, respectively.
-
The vzError::message()
method produces debug messages that are neither errors nor warnings.
Each debug message is given a particular debug level, passed as an integer
parameter to the message() method. The message will be
output to stderr only if the debug level of the message is less than or
equal to the current debug level (see setDebugLevel()).
Therefore, the higher you set this debug level, the more debug
information will be printed.
METHOD DESCRIPTIONS
clear()
-
This method clears the saved error returned by getError()
back to the initial state of VZ_NO_ERROR.
error()
| static void error ( |
vzErrorType error, const char* format=NULL, ...); |
-
This convenience method is used by the library to log errors.
If is equivalent to calling log() with the
severity passed in as VZ_ERROR. The default behavior is to
print the error message and then call abort(). The following
demonstrates the use of this method -
// Check for NULL pointers
void checkForNull(void *pointer) {
if(pointer == NULL)
vzError::error(VZ_INVALID_VALUE,"NULL pointer");
}
-
getDebugLevel()
| static int getDebugLevel ( |
); |
-
Retrieve the current debug level.
getError()
| static vzErrorType getError ( |
); |
-
This method returns the first error logged since the calling
thread started or last called clear(). Error
codes are stored independently for each thread.
If there have been no errors then VZ_NO_ERROR will be
returned.
getHandler()
| static void getHandler ( |
ErrorHandler*& handler, void*& data); |
-
This method returns the values last passed to
setHandler() in handler and data.
getSeverity()
| static vzErrorSeverity getSeverity ( |
); |
-
This method returns the severity associated with the error
returned by getError().
log()
| static void log ( |
vzErrorSeverity severity, vzErrorType error, const char* format=NULL, ...); |
-
This method is used by the library to log errors (and warnings).
The actual handling of the error can be controlled
using setHandler().
The severity level and type of error is indicated by the
severity and error parameters.
In addition a message may be encoded using the format
parameter and any printf(3) style optional arguments
that follow it.
-
Errors are classified as either an error or a warning
using the enum values VZ_ERROR or VZ_WARNING respectively.
These severity levels are intended as guidelines to
an error handler on whether execution should continue
after the error is reported.
message()
| static void message ( |
int debugLevel, const char* format, ...); |
-
This method prints the specified message to stderr, assuming
that debugLevel is less than or equal to the current
debug level (set by setDebugLevel()). The debug level
can also be set by setting the environment variable
VOLUMIZER_DEBUG_LEVEL to the appropriate value.
setDebugLevel()
| static void setDebugLevel ( |
int debugLevel); |
-
Set the current debug level. All calls to message()
with a debug level above the current level will be ignored.
setHandler()
| static void setHandler ( |
ErrorHandler* handler, void* data=NULL); |
-
This method is used to define an error handler routine
that will be called whenever an error is logged.
The function pointed to be handler must have
the prototype:
void handler(vzErrorSeverity severity, vzErrorType error,
const char *format, va_list args, void* data);
-
-
The handler is passed the severity level in severity,
the actual error code in error, and an optional message
to be formatted using a routine like vsprintf(3) in
format and args.
The final parameter data is the same value that was
passed to this routine in the parameter of the same name.
-
The following example adds user defined error handler to be
used for the vzError class.
// Set the error handler for vzError::log()
vzError::setHandler (myHandler, NULL);
-
The error handler might look like the following -
// User defined error handler
static void myHandler(vzErrorSeverity severity, vzErrorType type,
const char *format, va_list args, void* data)
{
if(severity == VZ_ERROR)
cerr<<"myHandler::Error!!!";
else if(severity == VZ_WARNING)
cerr<<"myHandler::Warning!!!";
// Print the error message
vfprintf(stderr, format, args);
// Use the vzErrorType to do whatever else is needed!!!
.........
}
-
warn()
| static void warn ( |
vzErrorType error, const char* format=NULL, ...); |
-
This convenience method is used by the library to log warnings.
If is equivalent to calling log() with the
severity passed in as VZ_WARNING. The default handler just
prints an error message and returns.
// Check for equal values
void areSame(int value1, int value2 ) {
if(value1 == value2)
vzError::warn(VZ_UNSPECIFIED_ERROR,"Both indices are same");
}
-
SEE ALSO-
printf(3), vsprintf(3)