fatalerror.h File Reference

#include <cstdarg>
#include <cstdio>
#include <filesystem>
#include "gromacs/libgromacs_export.h"
#include "gromacs/utility/basedefinitions.h"
#include "gromacs/utility/stringutil.h"

Include dependency graph for fatalerror.h:

Description

Declares fatal error handling and debugging routines for C code.

Macros
#define	FARGS   0, __FILE__, __LINE__
	Helper macro to pass first three parameters to gmx_fatal(). More...
#define	gmx_error(key, msg)   gmx_error_function(key, msg, __FILE__, __LINE__)
	Alternative fatal error routine with canned messages. More...
#define	range_check_mesg(n, n_min, n_max, str)   range_check_function(n, n_min, n_max, str, #n, __FILE__, __LINE__)
	Checks that a variable is within a range. More...
#define	range_check(n, n_min, n_max)   range_check_function(n, n_min, n_max, NULL, #n, __FILE__, __LINE__)
	Checks that a variable is within a range. More...
Fatal error routines for certain types of errors
These wrap gmx_error() and provide the key parameter as one of the recognized strings. These macros are deprecated and no new calls should be made to them.
#define	gmx_call(msg)   gmx_error("call", msg)
#define	gmx_comm(msg)   gmx_error("comm", msg)
#define	gmx_file(msg)   gmx_error("file", msg)
#define	gmx_impl(msg)   gmx_error("impl", msg)
#define	gmx_incons(msg)   gmx_error("incons", msg)
#define	gmx_input(msg)   gmx_error("input", msg)
#define	gmx_mem(msg)   gmx_error("mem", msg)
#define	gmx_open(fn)   gmx_error("open", fn)

Typedefs
typedef void(*	gmx_error_handler_t )(const char *title, const std::string &msg, const std::filesystem::path &file, int line)
	Function pointer type for fatal error handler callback. More...

Enumerations
enum	ExitType { ExitType_CleanExit, ExitType_Abort, ExitType_NonMainAbort }
	Identifies the state of the program on a fatal error. More...

Functions
void	gmx_init_debug (int dbglevel, const std::filesystem::path &dbgfile)
	Initializes debugging variables. More...
gmx_bool	bDebugMode ()
	Returns TRUE when the program was started in debug mode.
void	gmx_fatal_set_log_file (FILE *fp)
	Sets the log file for printing error messages. More...
void	gmx_set_error_handler (gmx_error_handler_t func)
	Sets an error handler for gmx_fatal() and other fatal error routines. More...
void	gmx_exit_on_fatal_error (enum ExitType exitType, int returnValue)
	Helper function to terminate the program on a fatal error. More...
void	gmx_fatal_mpi_va (int fatal_errno, const std::filesystem::path &file, int line, gmx_bool bMain, gmx_bool bFinalize, const char *fmt, va_list ap)
	Low-level fatal error reporting routine for collective MPI errors. More...
void	gmx_format (printf, 4, 5)
	Fatal error reporting routine for GROMACS. More...
void	gmx_error_function (const char *key, const std::string &msg, const std::filesystem::path &file, int line)
	Implementation for gmx_error(). More...
void	range_check_function (int n, int n_min, int n_max, const char *warn_str, const char *var, const std::filesystem::path &file, int line)
	Implementation for range_check() and range_check_mesg(). More...
void	gmx_warning (gmx_fmtstr const char *fmt,...) gmx_format(printf
	Prints a warning message to stderr. More...

Variables
LIBGROMACS_EXPORT FILE *	debug
	Debug log file. More...
gmx_bool	gmx_debug_at
	Whether extra debugging is enabled. More...

Macro Definition Documentation

#define FARGS   0, __FILE__, __LINE__

Helper macro to pass first three parameters to gmx_fatal().

#define gmx_error	(		key,
			msg
	)		gmx_error_function(key, msg, __FILE__, __LINE__)

Alternative fatal error routine with canned messages.

This works as gmx_fatal(), except that a generic error message is added based on a string key, and printf-style formatting is not supported. Should not typically be called directly, but through gmx_call() etc.

This macro is deprecated and no new calls should be made to it.

#define range_check	(		n,
			n_min,
			n_max
	)		range_check_function(n, n_min, n_max, NULL, #n, __FILE__, __LINE__)

Checks that a variable is within a range.

This works as range_check_mesg(), but with a default error message.

#define range_check_mesg	(		n,
			n_min,
			n_max,
			str
	)		range_check_function(n, n_min, n_max, str, #n, __FILE__, __LINE__)

Checks that a variable is within a range.

If n is not in range [n_min, n_max), a fatal error is raised. n_min is inclusive, but n_max is not.

Typedef Documentation

typedef void(* gmx_error_handler_t)(const char *title, const std::string &msg, const std::filesystem::path &file, int line)

Function pointer type for fatal error handler callback.

Enumeration Type Documentation

enum ExitType

Identifies the state of the program on a fatal error.

Enumerator
ExitType_CleanExit	Clean exit is possible. There should be no concurrently executing code that might be accessing global objects, and all MPI ranks should reach the same fatal error.
ExitType_Abort	Program needs to be aborted. There are no preconditions for this state.
ExitType_NonMainAbort	Program needs to be aborted, but some other rank is responsible of it. There should be some other MPI rank that reaches the same fatal error, but uses ExitType_Abort. The other ranks can then use ExitType_NonMainAbort to wait for that one rank to issue the abort.

Function Documentation

void gmx_error_function	(	const char *	key,
		const std::string &	msg,
		const std::filesystem::path &	file,
		int	line
	)

Implementation for gmx_error().

This function is deprecated and no new calls should be made to it.

void gmx_exit_on_fatal_error	(	enum ExitType	exitType,
		int	returnValue
	)

Helper function to terminate the program on a fatal error.

Parameters

[in]	exitType	Identifies the state of the program at the time of the call, determining how the program can be terminated.
[in]	returnValue	Exit code for the program, for cases where it can be used.

void gmx_fatal_mpi_va	(	int	fatal_errno,
		const std::filesystem::path &	file,
		int	line,
		gmx_bool	bMain,
		gmx_bool	bFinalize,
		const char *	fmt,
		va_list	ap
	)

Low-level fatal error reporting routine for collective MPI errors.

This function works as gmx_fatal(), but provides additional control for cases where it is known that the same error occurs on multiple MPI ranks. The error handler is called only if bMain is TRUE, and MPI_Finalize() is called instead of MPI_Abort() in MPI-enabled GROMACS if bFinalize is TRUE.

This is used to implement gmx_fatal_collective() (which cannot be declared here, since it would bring with it mdrun-specific dependencies).

This function is deprecated and no new calls should be made to it.

void gmx_fatal_set_log_file

(

FILE *

fp

)

Sets the log file for printing error messages.

void gmx_format	(	printf	,
		4	,
		5
	)

Fatal error reporting routine for GROMACS.

This function prints a fatal error message with a header that contains the source file and line number of the call, followed by the string specified by fmt and supplied parameters. If fatal_errno is 0, only the message and arguments are printed. If fatal_errno is a legal system errno or -1, a perror()-like message is printed after the first message; if fatal_errno is -1, the last system errno will be used. The format of fmt uses printf()-like formatting.

In case all MPI processes want to stop with the same fatal error, use gmx_fatal_collective(), declared in network.h, to avoid having as many error messages as processes.

This function is deprecated and no new calls should be made to it.

The first three parameters can be provided through FARGS:

gmx_fatal(FARGS, fmt, ...);

void gmx_init_debug	(	int	dbglevel,
		const std::filesystem::path &	dbgfile
	)

Initializes debugging variables.

This function is not threadsafe. It should be called as part of initializing GROMACS, before any other thread accesses the library. For command line programs, gmx::CommandLineModuleManager takes care of this if the user requests debugging.

void gmx_set_error_handler

(

gmx_error_handler_t

func

)

Sets an error handler for gmx_fatal() and other fatal error routines.

The default handler prints the message. GROMACS will terminate the program after the error handler returns. To make gmx_fatal_collective() work, the error handler should not terminate the program, as it cannot know what is the desired way of termination. The message passed to the handler may be a multi-line string.

See Also

gmx_fatal()

void gmx_warning	(	gmx_fmtstr const char *	fmt,
			...
	)

Prints a warning message to stderr.

The format of fmt uses printf()-like formatting. The message string should NOT start with "WARNING" and should NOT end with a newline.

void range_check_function	(	int	n,
		int	n_min,
		int	n_max,
		const char *	warn_str,
		const char *	var,
		const std::filesystem::path &	file,
		int	line
	)

Implementation for range_check() and range_check_mesg().

warn_str can be NULL.

Variable Documentation

LIBGROMACS_EXPORT FILE* debug

Debug log file.

Functions can write to this file for debug info. Before writing to it, it should be checked whether the file is not NULL:

if (debug)
{
     std::fprintf(debug, "%s", "Debug text");
}

gmx_bool gmx_debug_at

Whether extra debugging is enabled.