1.5. Error Checking
Added in version 7.0.0.
Until version 7.0.0, error reporting and handling was inconsistent throughout SUNDIALS. Starting with version 7.0.0 all of SUNDIALS (the core, implementations of core modules, and
packages) reports error mesages through the SUNLogger
API. Furthermore, functions in the
SUNDIALS core API (i.e., SUN
or N_V
functions only) either return a SUNErrCode
, or
(if they don’t return a SUNErrCode
) they internally record an error code (if an error
occurs) within the SUNContext
for the execution stream. This “last error” is accessible
via the SUNContext_GetLastError()
or SUNContext_PeekLastError()
functions.
-
typedef int SUNErrCode
Thus, in user code, SUNDIALS core API functions can be checked for errors in one of two ways:
SUNContext sunctx;
SUNErrCode sunerr;
N_Vector v;
int length;
sunrealtype dotprod;
// Every code that uses SUNDIALS must create a SUNContext.
sunctx = SUNContext_Create(...);
// Create a SUNDIALS serial vector.
// Some functions do not return an error code.
// We have to check for errors in these functions using SUNContext_GetLastError.
length = 2;
v = N_VNew_Serial(length, sunctx);
sunerr = SUNContext_GetLastError(sunctx);
if (sunerr) { /* an error occured, do something */ }
// If the function returns a SUNErrCode, we can check it directly
sunerr = N_VLinearCombination(...);
if (sunerr) { /* an error occured, do something */ }
// Another function that does not return a SUNErrCode.
dotprod = N_VDotProd(...);
SUNContext_GetLastError(sunctx);
if (sunerr) {
/* an error occured, do something */
} else {
print("dotprod = %.2f\n", dotprod);
}
The function SUNGetErrMsg()
can be used to get a message describing the error code.
-
const char *SUNGetErrMsg(SUNErrCode code)
Returns a message describing the error code.
- Parameters:
code – the error code
- Returns:
a message describing the error code.
Note
It is recommended in most cases that users check for an error after calling SUNDIALS functions. However, users concerned with getting the most performance might choose to exclude or limit these checks.
Warning
If a function returns a SUNErrCode
then the return value is the only place the error is available
i.e., these functions do not store their error code as the “last error” so it is invalid to use
SUNContext_GetLastError()
to check these functions for errors.
1.5.1. Error Handler Functions
When an error occurs in SUNDIALS, it calls error handler functions that have
been pushed onto the error handler stack in last-in first-out order.
Specific error handlers can be enabled by pushing them onto the error handler stack
with the function SUNContext_PushErrHandler()
. They may disabled by calling SUNContext_PopErrHandler()
or SUNContext_ClearErrHandlers()
.
A SUNDIALS error handler function has the type
-
typedef int (*SUNErrHandlerFn)(int line, const char *func, const char *file, const char *msg, SUNErrCode err_code, void *err_user_data, SUNContext sunctx)
SUNDIALS provides a few different error handlers that can be used, or a custom one defined by the
user can be provided (useful for linking SUNDIALS errors to your application’s error handling).
The default error handler is SUNLogErrHandlerFn()
which logs an error to a specified
file or stderr
if no file is specified.
The error handlers provided in SUNDIALS are:
-
void SUNLogErrHandlerFn(int line, const char *func, const char *file, const char *msg, SUNErrCode err_code, void *err_user_data, SUNContext sunctx)
Logs the error that occurred using the
SUNLogger
fromsunctx
. This is the default error handler.- Parameters:
line – the line number at which the error occured
func – the function in which the error occured
file – the file in which the error occured
msg – the message to log, if this is
NULL
then the default error message for the error code will be usederr_code – the error code for the error that occured
err_user_data – the user pointer provided to
SUNContext_PushErrHandler()
sunctx – pointer to a valid
SUNContext
object
- Returns:
void
-
void SUNAbortErrHandlerFn(int line, const char *func, const char *file, const char *msg, SUNErrCode err_code, void *err_user_data, SUNContext sunctx)
Logs the error and aborts the program if an error occured.
- Parameters:
line – the line number at which the error occured
func – the function in which the error occured
file – the file in which the error occured
msg – this parameter is ignored
err_code – the error code for the error that occured
err_user_data – the user pointer provided to
SUNContext_PushErrHandler()
sunctx – pointer to a valid
SUNContext
object
- Returns:
void
-
void SUNMPIAbortErrHandlerFn(int line, const char *func, const char *file, const char *msg, SUNErrCode err_code, void *err_user_data, SUNContext sunctx)
Logs the error and calls
MPI_Abort
if an error occured.- Parameters:
line – the line number at which the error occured
func – the function in which the error occured
file – the file in which the error occured
msg – this parameter is ignored
err_code – the error code for the error that occured
err_user_data – the user pointer provided to
SUNContext_PushErrHandler()
sunctx – pointer to a valid
SUNContext
object
- Returns:
void