qmckl/org/qmckl_error.org

Error handling

• -
• Decoding errors
• Data structure in context
• Updating errors in the context
• Get the error
• Failing
• Last error
  • Fortran inteface
• Helper functions for debugging
  • Fortran inteface

-

The library should never make the calling programs abort, nor perform any input/output operations. This decision has to be taken by the developer of the code calling the library.

All the functions return with an exit code, defined as

typedef int32_t qmckl_exit_code;

The exit code returns the completion status of the function to the calling program. When a function call completed successfully, QMCKL_SUCCESS is returned. If one of the functions of the library fails to complete the requested task, an appropriate error code is returned to the program.

Here is the complete list of exit codes.

Macro	Code	Description
QMCKL_SUCCESS	0	'Success'
QMCKL_INVALID_ARG_1	1	'Invalid argument 1'
QMCKL_INVALID_ARG_2	2	'Invalid argument 2'
QMCKL_INVALID_ARG_3	3	'Invalid argument 3'
QMCKL_INVALID_ARG_4	4	'Invalid argument 4'
QMCKL_INVALID_ARG_5	5	'Invalid argument 5'
QMCKL_INVALID_ARG_6	6	'Invalid argument 6'
QMCKL_INVALID_ARG_7	7	'Invalid argument 7'
QMCKL_INVALID_ARG_8	8	'Invalid argument 8'
QMCKL_INVALID_ARG_9	9	'Invalid argument 9'
QMCKL_INVALID_ARG_10	10	'Invalid argument 10'
QMCKL_INVALID_ARG_11	11	'Invalid argument 11'
QMCKL_INVALID_ARG_12	12	'Invalid argument 12'
QMCKL_INVALID_ARG_13	13	'Invalid argument 13'
QMCKL_INVALID_ARG_14	14	'Invalid argument 14'
QMCKL_INVALID_ARG_15	15	'Invalid argument 15'
QMCKL_INVALID_ARG_16	16	'Invalid argument 16'
QMCKL_INVALID_ARG_17	17	'Invalid argument 17'
QMCKL_INVALID_ARG_18	18	'Invalid argument 18'
QMCKL_INVALID_ARG_19	19	'Invalid argument 19'
QMCKL_INVALID_ARG_20	20	'Invalid argument 20'
QMCKL_FAILURE	101	'Failure'
QMCKL_ERRNO	102	strerror(errno)
QMCKL_INVALID_CONTEXT	103	'Invalid context'
QMCKL_ALLOCATION_FAILED	104	'Allocation failed'
QMCKL_DEALLOCATION_FAILED	105	'De-allocation failed'
QMCKL_NOT_PROVIDED	106	'Not provided'
QMCKL_OUT_OF_BOUNDS	107	'Index out of bounds'
QMCKL_ALREADY_SET	108	'Already set'
QMCKL_INVALID_EXIT_CODE	109	'Invalid exit code'

The qmckl_string_of_error converts an exit code into a string. The string is assumed to be large enough to contain the error message (typically 128 characters).

Decoding errors

To decode the error messages, qmckl_string_of_error converts an error code into a string.

const char*
qmckl_string_of_error (const qmckl_exit_code error);

The text strings are extracted from the previous table.

#+NAME:cases

Data structure in context

The strings are declared internally with a maximum fixed size to avoid dynamic memory allocation.

#define  QMCKL_MAX_FUN_LEN   256
#define  QMCKL_MAX_MSG_LEN  1024

typedef struct qmckl_error_struct {

qmckl_exit_code exit_code;
char function[QMCKL_MAX_FUN_LEN];
char message [QMCKL_MAX_MSG_LEN];

} qmckl_error_struct;

Updating errors in the context

The error is updated in the context using qmckl_set_error. When the error is set in the context, it is mandatory to specify from which function the error is triggered, and a message explaining the error. The exit code can't be QMCKL_SUCCESS.

qmckl_exit_code
qmckl_set_error(qmckl_context context,
             const qmckl_exit_code exit_code,
             const char* function_name,
             const char* message);

Get the error

Upon error, the error type and message can be obtained from the context using qmckl_get_error. The message and function name is returned in the variables provided. Therefore, passing a function name and message is mandatory.

qmckl_exit_code
qmckl_get_error(qmckl_context context,
             qmckl_exit_code *exit_code,
             char* function_name,
             char* message);

Failing

To make a function fail, the qmckl_failwith function should be called, such that information about the failure is stored in the context. The desired exit code is given as an argument, as well as the name of the function and an error message. If the message is NULL, then the default message obtained by qmckl_string_of_error is used. The return code of the function is the desired return code. Upon failure, a QMCKL_NULL_CONTEXT is returned.

qmckl_exit_code
qmckl_failwith(qmckl_context context,
            const qmckl_exit_code exit_code,
            const char* function,
            const char* message) ;

For example, this function can be used as

if (x < 0) {
return qmckl_failwith(context,
                     QMCKL_INVALID_ARG_2,
                     "qmckl_function",
                     "Expected x >= 0");
}

Last error

Returns a string describing the last error, using qmckl_get_error.

qmckl_exit_code
qmckl_last_error(qmckl_context context, char* buffer);

Fortran inteface

Helper functions for debugging

The following function prints to stderr an error message is the return code is not QMCKL_SUCCESS.

qmckl_exit_code
qmckl_check(qmckl_context context, qmckl_exit_code rc);

It should be used as:

rc = qmckl_check(context,
             qmckl_...(context, ...)
             );
assert (rc == QMCKL_SUCCESS);

Fortran inteface