charm_err

Error handling module:

• defines, initializes, frees and resets the charm_err structure,

• tests whether an charm_err structure is empty, and

• handles errors.

Note

When CHarm detects an error (e.g., an internal memory allocation failure), it properly frees all the internally allocated memory before returning back to the caller. No memory leaks should therefore occur, not even after a premature exit.

Defines

CHARM_ERR_MAX_FILE 4096

Maximum number of characters that can be stored in charm_err.file[i], i = 0, 1, ..., CHARM_ERR_MAX_LEVEL - 1, including the terminating null character.

CHARM_ERR_MAX_FUNC 256

Maximum number of characters that can be stored in charm_err.func[i], i = 0, 1, ..., CHARM_ERR_MAX_LEVEL - 1, including the terminating null character.

CHARM_ERR_MAX_MSG 4096

Maximum number of characters in charm_err.msg, including the terminating null character.

CHARM_ERR_MAX_LEVEL 10

Maximum number of error propagations from the function, in which the error occurred to the caller.

CHARM_ERR_MALLOC_FAILURE "Memory allocation failure."

Message to be printed when malloc or calloc fails.

Enums

enum [anonymous]

Errors enumeration.

Values:

enumerator CHARM_FAILURE = -1

Exit status returned when CHarm is explicitly asked to terminate the program in case it encounters an error.

enumerator CHARM_SUCCESS

Successful execution of a CHarm function.

enumerator CHARM_EMEM

Memory allocation failure (malloc, calloc).

enumerator CHARM_EFUNCARG

Error in function input/output argument(s).

enumerator CHARM_EFILEIO

Error in file reading/writing.

enumerator CHARM_EFFTWINIT

Error in threads initialization by FFTW.

Functions

charm_err *charm_err_init(void)

Allocates and initializes the charm_err structure using default empty values.

Returns:

On success, returned is a pointer to the charm_err structure. On error, NULL is returned.

void charm_err_free(charm_err *err)

Frees the memory associated with err. No operation is performed if err is NULL.

void charm_err_reset(charm_err *err)

Resets err to the default empty values.

void charm_err_handler(charm_err *err, _Bool terminate)

Error handler.

• If err is not empty, prints detailed information on the error. If terminate is set to Boolean 1, the program subsequently terminates.

• If err is empty, neither an error is printed nor the program is terminated (regardless of the terminate value).

Before leaving the function, err is reset to the default empty values.

Note

It is highly recommended to call the error handling function after every call of CHarm routines that take the charm_err structure as an input.

_Bool charm_err_isempty(const charm_err *err)

Returns boolean 1 if err is empty or 0 otherwise.

struct charm_err

Error structure.

In most cases, it is created by functions from this module that return a pointer to charm_err. Experienced users may create the structure on their own, provided that they assign correct values to its members, so that CHarm can properly understood the data in it (see the rules summarized below).

Public Members

unsigned int level

Total number of error propagations from the function in which the error was encountered back to the caller.

char **file

charm_err.file[0] is a pointer to a string with the name of the file in which the error was encountered; charm_err.file[i], i = 1, 2, ..., CHARM_ERR_MAX_LEVEL - 1, are file names through which the error was propagated to the caller.

unsigned int *line

Pointer to an array with line numbers of charm_err.file[i], i = 0, 1, ..., CHARM_ERR_MAX_LEVEL - 1, at which the charm_err structure was modified.

char **func

Same as charm_err.file, but with function names.

int code

Error code (see the errors enumerations CHARM_FAILURE, CHARM_SUCCESS, etc.).

char *msg

Pointer to an error message.

_Bool issaturated

Signalizes whether or not the levels of the error structure are saturated due to the error propagations. If true, the structure can no longer store most recent error propagations. This should never happen, though, since CHARM_ERR_MAX_LEVEL is chosen large enough.