src/gromacs/utility/errorcodes.h

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