3 * This source code is part of
7 * GROningen MAchine for Chemical Simulations
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.
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.
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.
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.
29 * For more info, check our website at http://www.gromacs.org
33 * Declares common exception classes for fatal error handling.
35 * \author Teemu Murtola <teemu.murtola@cbr.su.se>
37 * \ingroup module_utility
39 #ifndef GMX_UTILITY_EXCEPTIONS_H
40 #define GMX_UTILITY_EXCEPTIONS_H
45 #include <boost/exception/exception.hpp>
46 #include <boost/exception/info.hpp>
47 #include <boost/throw_exception.hpp>
53 * Stores a user-friendly explanation for the reason of an exception.
55 * Typically, should not be used directly, but through the GromacsException
56 * class: it is initialized by the constructor, and can be accessed with
57 * GromacsException::what().
61 typedef boost::error_info<struct errinfo_message_, std::string> errinfo_message;
68 * Base class for all exception objects in Gromacs.
70 * Although boost recommends using virtual inheritance in exception hiearchies,
71 * it is not used here for two reasons:
72 * -# It is only useful when there is diamond inheritance, and that should
73 * never occur in this exception hierarchy because this class is the only
74 * instance of multiple inheritance (Gromacs programming guidelines prohibit
75 * multiple inheritance from concrete classes, but it is unavoidable here
76 * because of the design of boost::exception).
77 * -# Because the constructor takes an argument, virtual inheritance would
78 * complicate any classes that inherit indirectly from this class.
80 * \ingroup module_utility
82 class GromacsException : public std::exception, public boost::exception
86 * Returns the reason string for the exception.
88 * The return value is the string that was passed to the constructor.
90 virtual const char *what() const throw();
92 * Returns the error code corresponding to the exception type.
94 virtual int errorCode() const = 0;
98 * Creates an exception object with the provided detailed reason.
100 * \param[in] reason Detailed reason for the exception.
102 explicit GromacsException(const std::string &reason);
106 * Exception class for file I/O errors.
108 * \ingroup module_utility
110 class FileIOError : public GromacsException
114 * Creates an exception object with the provided detailed reason.
116 * \param[in] reason Detailed reason for the exception.
118 explicit FileIOError(const std::string &reason)
119 : GromacsException(reason) {}
121 virtual int errorCode() const;
125 * Exception class for user input errors.
127 * Derived classes should be used to indicate the nature of the error instead
128 * of throwing this class directly.
130 * \ingroup module_utility
132 class UserInputError : public GromacsException
135 //! \copydoc FileIOError::FileIOError()
136 explicit UserInputError(const std::string &reason)
137 : GromacsException(reason) {}
141 * Exception class for situations where user input cannot be parsed/understood.
143 * \ingroup module_utility
145 class InvalidInputError : public UserInputError
148 //! \copydoc FileIOError::FileIOError()
149 explicit InvalidInputError(const std::string &reason)
150 : UserInputError(reason) {}
152 virtual int errorCode() const;
156 * Exception class for situations where user input is inconsistent.
158 * \ingroup module_utility
160 class InconsistentInputError : public UserInputError
163 //! \copydoc FileIOError::FileIOError()
164 explicit InconsistentInputError(const std::string &reason)
165 : UserInputError(reason) {}
167 virtual int errorCode() const;
171 * Exception class for simulation instabilities.
173 * \ingroup module_utility
175 class SimulationInstabilityError : public GromacsException
178 //! \copydoc FileIOError::FileIOError()
179 explicit SimulationInstabilityError(const std::string &reason)
180 : GromacsException(reason) {}
182 virtual int errorCode() const;
186 * Exception class for internal errors.
188 * \ingroup module_utility
190 class InternalError : public GromacsException
193 //! \copydoc FileIOError::FileIOError()
194 explicit InternalError(const std::string &reason)
195 : GromacsException(reason) {}
197 virtual int errorCode() const;
201 * Exception class for incorrect use of an API.
203 * \ingroup module_utility
205 class APIError : public GromacsException
208 //! \copydoc FileIOError::FileIOError()
209 explicit APIError(const std::string &reason)
210 : GromacsException(reason) {}
212 virtual int errorCode() const;
216 * Exception class for use of an unimplemented feature.
218 * \ingroup module_utility
220 class NotImplementedError : public APIError
223 //! \copydoc FileIOError::FileIOError()
224 explicit NotImplementedError(const std::string &reason)
225 : APIError(reason) {}
227 virtual int errorCode() const;
232 * Macro for throwing an exception.
234 * \param[in] e Exception object to throw.
236 * Using this macro instead of \c throw directly makes it possible to uniformly
237 * attach information into the exception objects.
238 * \p e should evaluate to an instance of an object derived from
245 GMX_THROW(InconsistentUserInput("Negative values not allowed for value"));
249 #define GMX_THROW(e) \
250 BOOST_THROW_EXCEPTION((e))
253 * Formats a standard error message for reporting an error.
255 * Normal usage in Gromacs command-line programs is like this:
257 int main(int argc, char *argv[])
261 // The actual code for the program
264 catch (const std::exception &ex)
266 fprintf(stderr, "%s", gmx::formatErrorMessage(ex).c_str());
272 std::string formatErrorMessage(const std::exception &ex);
275 * Converts an exception into a return code.
277 int translateException(const std::exception &ex);