Detailed Description

Provides standardized error numbers and error handling routines. Error reporting follows the design and conventions used in the GNU Scientific Library (GSL) error handling routines. Much of underling's error handling is a direct copy of GSL's API and source code. Notable exceptions are the MPI error handling macros which are an improved copy of ideas found in PETSc.

Go to the source code of this file.

Macros
#define	UNDERLING_ERROR(reason, underling_errno)
	Invokes underling_error and returns the value `underling_errno`. More...

#define	UNDERLING_ERROR_VAL(reason, underling_errno, value)
	Invokes underling_error using `underling_errno` and returns the value `value`. More...

#define	UNDERLING_ERROR_VOID(reason, underling_errno)
	Invokes underling_error using `underling_errno` and returns from the current function. More...

#define	UNDERLING_ERROR_NULL(reason, underling_errno)
	Invokes underling_error using `underling_errno` and returns NULL from the current function. More...

#define	UNDERLING_ERROR_NULL_FMT(underling_errno, fmt, ...)
	Like `UNDERLING_ERROR_NULL` but accepts `printf` style format arguments. More...

#define	UNDERLING_ERROR_REPORT(reason, underling_errno)
	Invokes underling_error using `underling_errno` but does not return from the current function. More...

#define	UNDERLING_MPICHKQ(stmt)
	Executes `stmt` once handling any resulting MPI error per `UNDERLING_ERROR`. More...

#define	UNDERLING_MPICHKN(stmt)
	Executes `stmt` once handling any resulting MPI error per `UNDERLING_ERROR_NULL`. More...

#define	UNDERLING_MPICHKV(stmt)
	Executes `stmt` once handling any resulting MPI error per `UNDERLING_ERROR_VOID`. More...

#define	UNDERLING_MPICHKR(stmt)
	Executes `stmt` once handling any resulting MPI error per `UNDERLING_ERROR_REPORT`. More...

Typedefs
typedef void	underling_error_handler_t(const char reason, const char file, int line, int underling_errno)
	Defines the function prototype necessary for an error handler. More...

typedef void	underling_stream_handler_t(const char label, const char file, int line, const char *reason)
	Defines the function prototype necessary for a stream handler. More...

Enumerations
enum	underling_status { UNDERLING_SUCCESS, UNDERLING_EFAULT, UNDERLING_EINVAL, UNDERLING_EFAILED, UNDERLING_ESANITY, UNDERLING_ENOMEM }
	Standardized error status codes used throughout underling. More...

Functions
void	underling_error (const char reason, const char file, int line, int underling_errno)
	Calls the error handler last set using underling_set_error_handler when invoked. More...

void	underling_stream_printf (const char label, const char file, int line, const char *reason)
	Print an error message to the current error stream. More...

const char *	underling_strerror (const int underling_errno)
	Look up a human-readable error message for the given error status. More...

underling_error_handler_t *	underling_set_error_handler (underling_error_handler_t *new_handler)
	Sets the current error handler for the process. More...

underling_error_handler_t *	underling_set_error_handler_off (void)
	An error handler implementation that disables all error reporting. More...

underling_stream_handler_t *	underling_set_stream_handler (underling_stream_handler_t *new_handler)
	Sets the current stream handler for the process. More...

FILE *	underling_set_stream (FILE *new_stream)
	Set the default stream for error message display. More...

Macro Definition Documentation

◆ UNDERLING_ERROR

#define UNDERLING_ERROR	(	reason,
		underling_errno
	)

Invokes underling_error and returns the value underling_errno.

Automatically provides file and line information.

Parameters

reason	Message to report.
underling_errno	Error status to report and returned from the current function.

◆ UNDERLING_ERROR_NULL

#define UNDERLING_ERROR_NULL	(	reason,
		underling_errno
	)

Invokes underling_error using underling_errno and returns NULL from the current function.

Useful for out-of-memory conditions. Automatically provides file and line information.

Parameters

reason	Message to report.
underling_errno	Error status to report.

◆ UNDERLING_ERROR_NULL_FMT

#define UNDERLING_ERROR_NULL_FMT	(	underling_errno,
		fmt,
		...
	)

Like UNDERLING_ERROR_NULL but accepts printf style format arguments.

Formats into a fixed-size stack buffer before reporting.

Parameters

underling_errno	Error status to report.
fmt	Format string.
...	Format arguments.

◆ UNDERLING_ERROR_REPORT

#define UNDERLING_ERROR_REPORT	(	reason,
		underling_errno
	)

Invokes underling_error using underling_errno but does not return from the current function.

Automatically provides file and line information.

Parameters

reason	Message to report.
underling_errno	Error status to report.

◆ UNDERLING_ERROR_VAL

#define UNDERLING_ERROR_VAL	(	reason,
		underling_errno,
		value
	)

Invokes underling_error using underling_errno and returns the value value.

Automatically provides file and line information.

Parameters

reason	Message to report.
underling_errno	Error status to report.
value	Value to return from the current function.

◆ UNDERLING_ERROR_VOID

#define UNDERLING_ERROR_VOID	(	reason,
		underling_errno
	)

Invokes underling_error using underling_errno and returns from the current function.

Automatically provides file and line information.

Parameters

reason	Message to report.
underling_errno	Error status to report.

◆ UNDERLING_MPICHKN

#define UNDERLING_MPICHKN ( stmt )

Executes stmt once handling any resulting MPI error per UNDERLING_ERROR_NULL.

Any relevant message is looked up using MPI_Error_string and reported.

Parameters

stmt	Statement, presumably an MPI call, to be executed.

Note: underling/mpi.h must be included for the macro expansion to compile correctly.

Warning: This macro expands to a not insignificant amount of code. It should not be used in performance critical regions.

See also: PETSc's CHKERRQ for the original inspiration for this macro.

◆ UNDERLING_MPICHKQ

#define UNDERLING_MPICHKQ ( stmt )

Executes stmt once handling any resulting MPI error per UNDERLING_ERROR.

Any relevant message is looked up using MPI_Error_string and reported. UNDERLING_EFAILED is the return value provided to UNDERLING_ERROR.

Parameters

stmt	Statement, presumably an MPI call, to be executed.

Note: underling/mpi.h must be included for the macro expansion to compile correctly.

Warning: This macro expands to a not insignificant amount of code. It should not be used in performance critical regions.

See also: PETSc's CHKERRQ for the original inspiration for this macro.

◆ UNDERLING_MPICHKR

#define UNDERLING_MPICHKR ( stmt )

Executes stmt once handling any resulting MPI error per UNDERLING_ERROR_REPORT.

The current function continues executing. Any relevant message is looked up using MPI_Error_string and reported.

Parameters

stmt	Statement, presumably an MPI call, to be executed.

Note: underling/mpi.h must be included for the macro expansion to compile correctly.

Warning: This macro expands to a not insignificant amount of code. It should not be used in performance critical regions.

See also: PETSc's CHKERRV for the original inspiration for this macro.

◆ UNDERLING_MPICHKV

#define UNDERLING_MPICHKV ( stmt )

Executes stmt once handling any resulting MPI error per UNDERLING_ERROR_VOID.

Any relevant message is looked up using MPI_Error_string and reported.

Parameters

stmt	Statement, presumably an MPI call, to be executed.

Note: underling/mpi.h must be included for the macro expansion to compile correctly.

Warning: This macro expands to a not insignificant amount of code. It should not be used in performance critical regions.

See also: PETSc's CHKERRV for the original inspiration for this macro.

Typedef Documentation

◆ underling_error_handler_t

typedef void underling_error_handler_t(const char *reason, const char *file, int line, int underling_errno)

Defines the function prototype necessary for an error handler.

Error handlers should be reentrant safe if possible.

Parameters

reason	Reason for the error.
file	File in which the error was reported.
line	Line at which the error was reported.
underling_errno	Error code to report.

See also: underling_set_error_handler

◆ underling_stream_handler_t

typedef void underling_stream_handler_t(const char *label, const char *file, int line, const char *reason)

Defines the function prototype necessary for a stream handler.

Stream handlers should be reentrant safe if possible.

Parameters

label	Label for the message.
file	File in which the error was reported.
line	Line at which the error was reported.
reason	Reason for the error.

See also: underling_set_stream_handler

Enumeration Type Documentation

◆ underling_status

enum underling_status

Standardized error status codes used throughout underling.

Where possible these codes are numerically equivalent to GSL's error codes.

Note that UNDERLING_SUCCESS is zero to allow code like if (!status) { some_error_handling() }.

Enumerator
UNDERLING_SUCCESS	Success.
UNDERLING_EFAULT	Invalid pointer.
UNDERLING_EINVAL	Invalid argument supplied by user.
UNDERLING_EFAILED	Generic failure.
UNDERLING_ESANITY	Sanity check failed - shouldn't happen.
UNDERLING_ENOMEM	Memory allocation failed.

Function Documentation

◆ underling_error()

void underling_error	(	const char *	reason,
		const char *	file,
		int	line,
		int	underling_errno
	)

Calls the error handler last set using underling_set_error_handler when invoked.

This is the entry point to the error handling system.

The default behavior is to log the error to the stream specified using underling_set_stream. The functions underling_set_stream, underling_set_stream_handler, and underling_set_error_handler can be used to modify this behavior.

Parameters

reason	Reason for the error.
file	File in which the error was reported.
line	Line at which the error was reported.
underling_errno	Error code to report. Should be one of underling_status if at all possible.

See also: Most clients should not use this function directly; instead use one of the convenience macros: UNDERLING_ERROR, UNDERLING_ERROR_VAL, UNDERLING_ERROR_VOID, UNDERLING_ERROR_NULL

◆ underling_set_error_handler()

underling_error_handler_t* underling_set_error_handler ( underling_error_handler_t * new_handler )

Sets the current error handler for the process.

Invoked by underling_error when an error occurs.

Parameters

new_handler New error handler to use.

Returns: the previous error handler in use.

◆ underling_set_error_handler_off()

underling_error_handler_t* underling_set_error_handler_off ( void )

An error handler implementation that disables all error reporting.

Primarily intended for use in test environments.

Returns: the previous error handler in use.

◆ underling_set_stream()

FILE* underling_set_stream ( FILE * new_stream )

Set the default stream for error message display.

Default behavior is to use stderr.

Parameters

new_stream New stream to use.

Returns: the previous stream in use.

◆ underling_set_stream_handler()

underling_stream_handler_t* underling_set_stream_handler ( underling_stream_handler_t * new_handler )

Sets the current stream handler for the process.

Used by the default error handling behavior, and possibly by other custom error handling routines.

Parameters

new_handler New stream handler to use.

Returns: the previous stream handler in use.

◆ underling_stream_printf()

void underling_stream_printf	(	const char *	label,
		const char *	file,
		int	line,
		const char *	reason
	)

Print an error message to the current error stream.

If a underling_stream_handler_t has been specified, it is used. If a stream has been set using underling_set_stream, it is used. Lastly, the routine prints the error message to standard error.

Parameters

label	Label used to identify the error.
file	File in which the error was reported.
line	Line at which the error was reported.
reason	Reason for the error.

◆ underling_strerror()

const char* underling_strerror ( const int underling_errno )

Look up a human-readable error message for the given error status.

Parameters

underling_errno Error code to look up.

Returns: A message suitable for use in logging or error messages.

Detailed Description

Macros

Typedefs

Enumerations

Functions

Macro Definition Documentation

◆ UNDERLING_ERROR

◆ UNDERLING_ERROR_NULL

◆ UNDERLING_ERROR_NULL_FMT

◆ UNDERLING_ERROR_REPORT

◆ UNDERLING_ERROR_VAL

◆ UNDERLING_ERROR_VOID

◆ UNDERLING_MPICHKN

◆ UNDERLING_MPICHKQ

◆ UNDERLING_MPICHKR

◆ UNDERLING_MPICHKV

Typedef Documentation

◆ underling_error_handler_t

◆ underling_stream_handler_t

Enumeration Type Documentation

◆ underling_status

Function Documentation

◆ underling_error()

◆ underling_set_error_handler()

◆ underling_set_error_handler_off()

◆ underling_set_stream()

◆ underling_set_stream_handler()

◆ underling_stream_printf()

◆ underling_strerror()