Gromacs  2016.4
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
Macros | Typedefs | Enumerations | Functions | Variables
fatalerror.h File Reference
#include <stdarg.h>
#include <stdio.h>
#include "gromacs/utility/basedefinitions.h"
+ Include dependency graph for fatalerror.h:
+ This graph shows which files directly or indirectly include this file:

Description

Declares fatal error handling and debugging routines for C code.

Macros

#define where()   _where(__FILE__, __LINE__)
 Prints filename and line to stdlog. More...
 
#define FARGS   0, __FILE__, __LINE__
 Helper macro to pass first three parameters to gmx_fatal(). More...
 
#define gmx_error(key, msg)   _gmx_error(key, msg, __FILE__, __LINE__)
 Alternative fatal error routine with canned messages. More...
 
#define range_check_mesg(n, n_min, n_max, str)   _range_check(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(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.

#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 char *msg, const char *file, int line)
 Function pointer type for fatal error handler callback. More...
 

Enumerations

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

Functions

void gmx_init_debug (const int dbglevel, const char *dbgfile)
 Initializes debugging variables. More...
 
gmx_bool bDebugMode (void)
 Returns TRUE when the program was started in debug mode.
 
void _where (const char *file, int line)
 Implementation for where(). More...
 
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 char *file, int line, gmx_bool bMaster, gmx_bool bFinalize, const char *fmt, va_list ap)
 Low-level fatal error reporting routine for collective MPI errors. More...
 
void gmx_fatal (int fatal_errno, const char *file, int line, const char *fmt,...)
 Fatal error reporting routine for GROMACS. More...
 
void _gmx_error (const char *key, const char *msg, const char *file, int line)
 Implementation for gmx_error(). More...
 
void _range_check (int n, int n_min, int n_max, const char *warn_str, const char *var, const char *file, int line)
 Implementation for range_check() and range_check_mesg(). More...
 
void gmx_warning (const char *fmt,...)
 Prints a warning message to stderr. More...
 

Variables

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(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.

#define range_check (   n,
  n_min,
  n_max 
)    _range_check(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(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.

#define where ( )    _where(__FILE__, __LINE__)

Prints filename and line to stdlog.

Typedef Documentation

typedef void(* gmx_error_handler_t)(const char *title, const char *msg, const char *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_NonMasterAbort 

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_NonMasterAbort to wait for that one rank to issue the abort.

Function Documentation

void _gmx_error ( const char *  key,
const char *  msg,
const char *  file,
int  line 
)

Implementation for gmx_error().

void _range_check ( int  n,
int  n_min,
int  n_max,
const char *  warn_str,
const char *  var,
const char *  file,
int  line 
)

Implementation for range_check() and range_check_mesg().

warn_str can be NULL.

void _where ( const char *  file,
int  line 
)

Implementation for where().

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 ( int  fatal_errno,
const char *  file,
int  line,
const char *  fmt,
  ... 
)

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.

The first three parameters can be provided through FARGS:

gmx_fatal(FARGS, fmt, ...);
void gmx_fatal_mpi_va ( int  fatal_errno,
const char *  file,
int  line,
gmx_bool  bMaster,
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 bMaster 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).

void gmx_fatal_set_log_file ( FILE *  fp)

Sets the log file for printing error messages.

void gmx_init_debug ( const int  dbglevel,
const char *  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 ( 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.

Variable Documentation

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)
{
fprintf(debug, "%s", "Debug text");
}
gmx_bool gmx_debug_at

Whether extra debugging is enabled.