Gromacs  2024.3
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
Macros | Typedefs | Enumerations | Functions | Variables
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]exitTypeIdentifies the state of the program at the time of the call, determining how the program can be terminated.
[in]returnValueExit 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  ,
,
 
)

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.