src/gromacs/utility/errorcodes.h

   1 /*
   2  *
   3  *                This source code is part of
   4  *
   5  *                 G   R   O   M   A   C   S
   6  *
   7  *          GROningen MAchine for Chemical Simulations
   8  *
   9  * Written by David van der Spoel, Erik Lindahl, Berk Hess, and others.
  10  * Copyright (c) 1991-2000, University of Groningen, The Netherlands.
  11  * Copyright (c) 2001-2009, The GROMACS development team,
  12  * check out http://www.gromacs.org for more information.
  13  *
  14  * This program is free software; you can redistribute it and/or
  15  * modify it under the terms of the GNU General Public License
  16  * as published by the Free Software Foundation; either version 2
  17  * of the License, or (at your option) any later version.
  18  *
  19  * If you want to redistribute modifications, please consider that
  20  * scientific software is very special. Version control is crucial -
  21  * bugs must be traceable. We will be happy to consider code for
  22  * inclusion in the official distribution, but derived work must not
  23  * be called official GROMACS. Details are found in the README & COPYING
  24  * files - if they are missing, get the official version at www.gromacs.org.
  25  *
  26  * To help us fund GROMACS development, we humbly ask that you cite
  27  * the papers on the package - you can find them in the top README file.
  28  *
  29  * For more info, check our website at http://www.gromacs.org
  30  */
  31 /*! \file
  32  * \brief
  33  * Declares error codes and related functions for fatal error handling.
  34  *
  35  * \author Teemu Murtola <teemu.murtola@cbr.su.se>
  36  * \inpublicapi
  37  * \ingroup module_utility
  38  */
  39 #ifndef GMX_UTILITY_ERRORCODES_H
  40 #define GMX_UTILITY_ERRORCODES_H
  41
  42 namespace gmx
  43 {
  44
  45 /*! \addtopublicapi
  46  * \{
  47  */
  48
  49 /*! \brief
  50  * Possible error return codes from Gromacs functions.
  51  */
  52 enum ErrorCode
  53 {
  54     //! Zero for successful return.
  55     eeOK,
  56     //! Not enough memory to complete operation.
  57     eeOutOfMemory,
  58     //! Provided file could not be opened.
  59     eeFileNotFound,
  60     //! System I/O error.
  61     eeFileIO,
  62     //! Invalid user input (could not be understood).
  63     eeInvalidInput,
  64     //! Invalid user input (conflicting or unsupported settings).
  65     eeInconsistentInput,
  66     //! Simulation instability detected.
  67     eeInstability,
  68
  69     // Error codes below are for internal error checking; if triggered, they
  70     // should indicate a bug in the code.
  71     //! Requested feature not yet implemented.
  72     eeNotImplemented,
  73     //! Input value violates API specification.
  74     eeInvalidValue,
  75     //! Invalid routine called or wrong calling sequence detected.
  76     eeInvalidCall,
  77     //! Internal consistency check failed.
  78     eeInternalError,
  79     //! API specification was violated.
  80     eeAPIError,
  81     //! Range consistency check failed.
  82     eeRange,
  83     //! Communication consistency check failed.
  84     eeCommunication,
  85
  86     //! Unknown error detected.
  87     eeUnknownError,
  88 };
  89
  90 /*! \brief
  91  * Returns a short string description of an error code.
  92  *
  93  * \param[in] errorcode Error code to retrieve the string for.
  94  * \returns   A constant string corresponding to \p errorcode.
  95  *
  96  * If \p errorcode is not one of those defined for ::gmx::ErrorCode,
  97  * the string corresponding to ::eeUnknownError is returned.
  98  *
  99  * This function does not throw.
 100  */
 101 const char *getErrorCodeString(int errorcode);
 102
 103 /*! \brief
 104  * Callback function pointer type for error handlers.
 105  *
 106  * \param[in] retcode Code of the error that has occurred.
 107  * \param[in] msg     More detailed description of the error.
 108  * \param[in] file    Name of the file where the error occurred.
 109  * \param[in] line    Line in \p file on which the error occurred.
 110  */
 111 typedef void (*ErrorHandlerFunc)(int retcode, const char *msg,
 112                                  const char *file, int line);
 113
 114 /*! \brief
 115  * Sets callback function for handling errors.
 116  *
 117  * \param[in] handler New error handler function.
 118  * \returns   Old error handler function.
 119  *
 120  * The default error handler prints out the location and reason of the error to
 121  * stderr, and then calls abort().
 122  */
 123 ErrorHandlerFunc setFatalErrorHandler(ErrorHandlerFunc handler);
 124
 125 /*! \brief
 126  * Macro for raising an error and returning from a function.
 127  *
 128  * The function should return \c int ; if it doesn't, use GMX_ERROR_NORET.
 129  */
 130 #define GMX_ERROR(retcode, msg) \
 131     do { \
 132         int _rc_internal = (retcode); \
 133         ::gmx::internal::fatalError(_rc_internal, msg, __FILE__, __LINE__); \
 134         return _rc_internal; \
 135     } while (0)
 136
 137 /*! \brief
 138  * Macro for raising an error in a function that does not return \c int.
 139  *
 140  * \see GMX_ERROR
 141  */
 142 #define GMX_ERROR_NORET(retcode, msg) \
 143         ::gmx::internal::fatalError(retcode, msg, __FILE__, __LINE__)
 144
 145 /*!\}*/
 146
 147 /*! \cond internal */
 148 namespace internal
 149 {
 150
 151 /*! \brief
 152  * Raises a fatal error.
 153  *
 154  * \param[in] retcode Error code to raise.
 155  * \param[in] msg     More detailed description of the error.
 156  * \param[in] file    Name of the source file where the error occurred.
 157  * \param[in] line    Line in \p file on which the error occurred.
 158  *
 159  * Should not be called directly, but instead through ::GMX_ERROR or
 160  * ::GMX_ERROR_NORET.
 161  *
 162  * \ingroup module_utility
 163  */
 164 void fatalError(int retcode, const char *msg, const char *file, int line);
 165
 166 }   // namespace internal
 167 //! \endcond
 168
 169 } // namespace gmx
 170
 171 #endif