2 * This file is part of the GROMACS molecular simulation package.
4 * Copyright (c) 2011,2012,2013,2014, by the GROMACS development team, led by
5 * Mark Abraham, David van der Spoel, Berk Hess, and Erik Lindahl,
6 * and including many others, as listed in the AUTHORS file in the
7 * top-level source directory and at http://www.gromacs.org.
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.
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.
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.
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.
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.
37 * Declares common exception classes and macros for fatal error handling.
39 * \author Teemu Murtola <teemu.murtola@gmail.com>
41 * \ingroup module_utility
43 #ifndef GMX_UTILITY_EXCEPTIONS_H
44 #define GMX_UTILITY_EXCEPTIONS_H
53 #include <boost/exception_ptr.hpp>
54 #include <boost/exception/errinfo_api_function.hpp>
55 #include <boost/exception/errinfo_errno.hpp>
56 #include <boost/exception/exception.hpp>
57 #include <boost/exception/info.hpp>
58 #include <boost/throw_exception.hpp>
65 //! Internal container type for storing a list of nested exceptions.
66 typedef std::vector<boost::exception_ptr> NestedExceptionList;
67 } // namespace internal
69 //! \addtogroup module_utility
73 * Provides information for Gromacs exception constructors.
75 * This class exists to implement common functionality for initializing all
76 * Gromacs exceptions without having extra code in each exception class.
77 * In simple cases, it can be implicitly constructed by passing a simple string
78 * to an exception constructor.
79 * If more complex initialization is necessary, it is possible to explicitly
80 * construct an object of this type and then call other methods to add
81 * information before actually creating the exception object.
84 * With the exception of the reason string, information added with this class
85 * is not currently accessible through any public API, except for calling
86 * printFatalErrorMessage(), formatExceptionMessageToString() or
87 * formatExceptionMessageToFile(). This is not implemented as there is not yet
88 * need for it, and it is not clear what would be the best alternative for the
89 * access. It should be possible to refactor the internal implementation to
90 * suit the needs of such external access without requiring changes in code
91 * that throws these exceptions.
93 * \ingroup module_utility
95 class ExceptionInitializer
99 * Creates an initialized with the given string as the reason.
101 * \param[in] reason Detailed reason for the exception.
102 * \throw std::bad_alloc if out of memory.
104 * This constructor is not explicit to allow constructing exceptions
105 * with a plain string argument given to the constructor without adding
106 * extra code to each exception class.
108 ExceptionInitializer(const char *reason)
112 //! \copydoc ExceptionInitializer(const char *)
113 ExceptionInitializer(const std::string &reason)
119 * Returns true if addCurrentExceptionAsNested() has been called.
121 * Provided for convenience for cases where exceptions will be added
122 * conditionally, and the caller wants to check whether any excetions
123 * were actually added.
125 bool hasNestedExceptions() const { return !nested_.empty(); }
127 * Adds the currently caught exception as a nested exception.
129 * May be called multiple times; all provided exceptions will be added
130 * in a list of nested exceptions.
132 * Must not be called outside a catch block.
134 void addCurrentExceptionAsNested()
136 nested_.push_back(boost::current_exception());
139 * Adds the specified exception as a nested exception.
141 * May be called multiple times; all provided exceptions will be added
142 * in a list of nested exceptions.
144 * This is equivalent to throwing \p ex and calling
145 * addCurrentExceptionAsNested() in the catch block, but potentially
148 template <class Exception>
149 void addNested(const Exception &ex)
151 nested_.push_back(boost::copy_exception(ex));
156 internal::NestedExceptionList nested_;
158 friend class GromacsException;
162 * Base class for all exception objects in Gromacs.
164 * Although boost recommends using virtual inheritance in exception hiearchies,
165 * it is not used here for two reasons:
166 * -# It is only useful when there is diamond inheritance, and that should
167 * never occur in this exception hierarchy because this class is the only
168 * instance of multiple inheritance (Gromacs programming guidelines prohibit
169 * multiple inheritance from concrete classes, but it is unavoidable here
170 * because of the design of boost::exception).
171 * -# Because the constructor takes an argument, virtual inheritance would
172 * complicate any classes that inherit indirectly from this class.
176 class GromacsException : public std::exception, public boost::exception
180 * Returns the reason string for the exception.
182 * The return value is the string that was passed to the constructor.
184 virtual const char *what() const throw();
186 * Returns the error code corresponding to the exception type.
188 virtual int errorCode() const = 0;
191 * Adds context information to this exception.
193 * \param[in] context Context string to add.
194 * \throws std::bad_alloc if out of memory.
196 * Typical use is to add additional information higher up in the call
197 * stack using this function in a catch block and the rethrow the
201 * The added information is currently not accessible through what(),
202 * nor through any other means except for calling
203 * printFatalErrorMessage(), formatExceptionMessageToString() or
204 * formatExceptionMessageToFile(). See ExceptionInitializer for more
207 void prependContext(const std::string &context);
211 * Creates an exception object with the provided initializer/reason.
213 * \param[in] details Initializer for the exception.
214 * \throws std::bad_alloc if out of memory.
216 explicit GromacsException(const ExceptionInitializer &details);
220 * Exception class for file I/O errors.
224 class FileIOError : public GromacsException
228 * Creates an exception object with the provided initializer/reason.
230 * \param[in] details Initializer for the exception.
231 * \throws std::bad_alloc if out of memory.
233 * It is possible to call this constructor either with an explicit
234 * ExceptionInitializer object (useful for more complex cases), or
235 * a simple string if only a reason string needs to be provided.
237 explicit FileIOError(const ExceptionInitializer &details)
238 : GromacsException(details) {}
240 virtual int errorCode() const;
244 * Exception class for user input errors.
246 * Derived classes should be used to indicate the nature of the error instead
247 * of throwing this class directly.
251 class UserInputError : public GromacsException
254 //! \copydoc FileIOError::FileIOError()
255 explicit UserInputError(const ExceptionInitializer &details)
256 : GromacsException(details) {}
260 * Exception class for situations where user input cannot be parsed/understood.
264 class InvalidInputError : public UserInputError
267 //! \copydoc FileIOError::FileIOError()
268 explicit InvalidInputError(const ExceptionInitializer &details)
269 : UserInputError(details) {}
271 virtual int errorCode() const;
275 * Exception class for situations where user input is inconsistent.
279 class InconsistentInputError : public UserInputError
282 //! \copydoc FileIOError::FileIOError()
283 explicit InconsistentInputError(const ExceptionInitializer &details)
284 : UserInputError(details) {}
286 virtual int errorCode() const;
290 * Exception class for simulation instabilities.
294 class SimulationInstabilityError : public GromacsException
297 //! \copydoc FileIOError::FileIOError()
298 explicit SimulationInstabilityError(const ExceptionInitializer &details)
299 : GromacsException(details) {}
301 virtual int errorCode() const;
305 * Exception class for internal errors.
309 class InternalError : public GromacsException
312 //! \copydoc FileIOError::FileIOError()
313 explicit InternalError(const ExceptionInitializer &details)
314 : GromacsException(details) {}
316 virtual int errorCode() const;
320 * Exception class for incorrect use of an API.
324 class APIError : public GromacsException
327 //! \copydoc FileIOError::FileIOError()
328 explicit APIError(const ExceptionInitializer &details)
329 : GromacsException(details) {}
331 virtual int errorCode() const;
335 * Exception class for use of an unimplemented feature.
339 class NotImplementedError : public APIError
342 //! \copydoc FileIOError::FileIOError()
343 explicit NotImplementedError(const ExceptionInitializer &details)
344 : APIError(details) {}
346 virtual int errorCode() const;
351 * Macro for throwing an exception.
353 * \param[in] e Exception object to throw.
355 * Using this macro instead of \c throw directly makes it possible to uniformly
356 * attach information into the exception objects.
357 * \p e should evaluate to an instance of an object derived from
364 GMX_THROW(InconsistentUserInput("Negative values not allowed for value"));
368 #define GMX_THROW(e) \
369 BOOST_THROW_EXCEPTION((e))
372 * Macro for throwing an exception based on errno.
374 * \param[in] e Exception object to throw.
375 * \param[in] syscall Name of the syscall that returned the error.
376 * \param[in] err errno value returned by the syscall.
378 * This macro provides a convenience interface for throwing an exception to
379 * report an error based on a errno value. In addition to adding the necessary
380 * information to the exception object, the macro also ensures that \p errno is
381 * evaluated before, e.g., the constructor of \p e may call other functions
382 * that could overwrite the errno value.
383 * \p e should evaluate to an instance of an object derived from
386 * Typical usage (note that gmx::File wraps this particular case):
388 FILE *fp = fopen("filename.txt", "r");
391 GMX_THROW(FileIOError("Could not open file"), "fopen", errno);
395 #define GMX_THROW_WITH_ERRNO(e, syscall, err) \
397 int stored_errno_ = (err); \
398 GMX_THROW((e) << boost::errinfo_errno(stored_errno_) \
399 << boost::errinfo_api_function(syscall)); \
403 * Formats a standard fatal error message for reporting an exception.
405 * \param[in] fp %File to format the message to.
406 * \param[in] ex Exception to format.
408 * Does not throw. If memory allocation fails or some other error occurs
409 * while formatting the error, tries to print a reasonable alternative message.
411 * Normal usage in Gromacs command-line programs is like this:
413 int main(int argc, char *argv[])
415 gmx::init(&argc, &argv);
418 // The actual code for the program
421 catch (const std::exception &ex)
423 gmx::printFatalErrorMessage(stderr, ex);
424 return gmx::processExceptionAtExit(ex);
429 void printFatalErrorMessage(FILE *fp, const std::exception &ex);
431 * Formats an error message for reporting an exception.
433 * \param[in] ex Exception to format.
434 * \returns Formatted string containing details of \p ex.
435 * \throws std::bad_alloc if out of memory.
437 std::string formatExceptionMessageToString(const std::exception &ex);
439 * Formats an error message for reporting an exception.
441 * \param fp %File to write the message to.
442 * \param[in] ex Exception to format.
443 * \throws std::bad_alloc if out of memory.
445 void formatExceptionMessageToFile(FILE *fp, const std::exception &ex);
447 * Handles an exception that is causing the program to terminate.
449 * \param[in] ex Exception that is the cause for terminating the program.
450 * \returns Return code to return from main().
452 * This method should be called as the last thing before terminating the
453 * program because of an exception. It exists to terminate the program as
454 * gracefully as possible in the case of MPI processing (but the current
455 * implementation always calls MPI_Abort()).
457 * See printFatalErrorMessage() for example usage.
461 int processExceptionAtExit(const std::exception &ex);
464 * Converts an exception into a return code.
466 int translateException(const std::exception &ex);
469 * Macro for catching exceptions at C++ -> C boundary.
471 * This macro is intended for uniform handling of exceptions when C++ code is
472 * called from C code within Gromacs. Since most existing code is written
473 * using the assumption that fatal errors terminate the program, this macro
474 * implements this behavior for exceptions. It should only be used in cases
475 * where the error cannot be propagated upwards using return values or such.
477 * Having this as a macro instead of having the same code in each place makes
478 * it easy to 1) find all such locations in the code, and 2) change the exact
479 * behavior if needed.
487 GMX_CATCH_ALL_AND_EXIT_WITH_FATAL_ERROR;
490 #define GMX_CATCH_ALL_AND_EXIT_WITH_FATAL_ERROR \
491 catch (const std::exception &ex) { \
492 ::gmx::printFatalErrorMessage(stderr, ex); \
493 ::std::exit(::gmx::processExceptionAtExit(ex)); \