/*
* This file is part of the GROMACS molecular simulation package.
*
- * Copyright (c) 2011,2012,2013, by the GROMACS development team, led by
- * David van der Spoel, Berk Hess, Erik Lindahl, and including many
- * others, as listed in the AUTHORS file in the top-level source
- * directory and at http://www.gromacs.org.
+ * Copyright (c) 2011,2012,2013,2014, by the GROMACS development team, led by
+ * Mark Abraham, David van der Spoel, Berk Hess, and Erik Lindahl,
+ * and including many others, as listed in the AUTHORS file in the
+ * top-level source directory and at http://www.gromacs.org.
*
* GROMACS is free software; you can redistribute it and/or
* modify it under the terms of the GNU Lesser General Public License
*/
/*! \file
* \brief
- * Declares common exception classes for fatal error handling.
+ * Declares common exception classes and macros for fatal error handling.
*
* \author Teemu Murtola <teemu.murtola@gmail.com>
* \inpublicapi
#include <vector>
#include <boost/exception_ptr.hpp>
+#include <boost/throw_exception.hpp>
#include <boost/exception/errinfo_api_function.hpp>
#include <boost/exception/errinfo_errno.hpp>
#include <boost/exception/exception.hpp>
#include <boost/exception/info.hpp>
-#include <boost/throw_exception.hpp>
namespace gmx
{
typedef std::vector<boost::exception_ptr> NestedExceptionList;
} // namespace internal
-/*! \addtopublicapi
- * \{
- */
+//! \addtogroup module_utility
+//! \{
/*! \brief
* Provides information for Gromacs exception constructors.
* \todo
* With the exception of the reason string, information added with this class
* is not currently accessible through any public API, except for calling
- * printFatalErrorMessage(). This is not implemented as there is no current
+ * printFatalErrorMessage(), formatExceptionMessageToString() or
+ * formatExceptionMessageToFile(). This is not implemented as there is not yet
* need for it, and it is not clear what would be the best alternative for the
* access. It should be possible to refactor the internal implementation to
* suit the needs of such external access without requiring changes in code
{
nested_.push_back(boost::current_exception());
}
+ /*! \brief
+ * Adds the specified exception as a nested exception.
+ *
+ * May be called multiple times; all provided exceptions will be added
+ * in a list of nested exceptions.
+ *
+ * This is equivalent to throwing \p ex and calling
+ * addCurrentExceptionAsNested() in the catch block, but potentially
+ * more efficient.
+ */
+ template <class Exception>
+ void addNested(const Exception &ex)
+ {
+ nested_.push_back(boost::copy_exception(ex));
+ }
private:
std::string reason_;
* -# Because the constructor takes an argument, virtual inheritance would
* complicate any classes that inherit indirectly from this class.
*
- * \ingroup module_utility
+ * \inpublicapi
*/
class GromacsException : public std::exception, public boost::exception
{
* \todo
* The added information is currently not accessible through what(),
* nor through any other means except for calling
- * printFatalErrorMessage(). See ExceptionInitializer for more
+ * printFatalErrorMessage(), formatExceptionMessageToString() or
+ * formatExceptionMessageToFile(). See ExceptionInitializer for more
* discussion.
*/
void prependContext(const std::string &context);
/*! \brief
* Exception class for file I/O errors.
*
- * \ingroup module_utility
+ * \inpublicapi
*/
class FileIOError : public GromacsException
{
* Derived classes should be used to indicate the nature of the error instead
* of throwing this class directly.
*
- * \ingroup module_utility
+ * \inpublicapi
*/
class UserInputError : public GromacsException
{
/*! \brief
* Exception class for situations where user input cannot be parsed/understood.
*
- * \ingroup module_utility
+ * \inpublicapi
*/
class InvalidInputError : public UserInputError
{
/*! \brief
* Exception class for situations where user input is inconsistent.
*
- * \ingroup module_utility
+ * \inpublicapi
*/
class InconsistentInputError : public UserInputError
{
/*! \brief
* Exception class for simulation instabilities.
*
- * \ingroup module_utility
+ * \inpublicapi
*/
class SimulationInstabilityError : public GromacsException
{
/*! \brief
* Exception class for internal errors.
*
- * \ingroup module_utility
+ * \inpublicapi
*/
class InternalError : public GromacsException
{
/*! \brief
* Exception class for incorrect use of an API.
*
- * \ingroup module_utility
+ * \inpublicapi
*/
class APIError : public GromacsException
{
/*! \brief
* Exception class for use of an unimplemented feature.
*
- * \ingroup module_utility
+ * \inpublicapi
*/
class NotImplementedError : public APIError
{
{
GMX_THROW(InconsistentUserInput("Negative values not allowed for value"));
}
- * \endcode
+ \endcode
*/
#define GMX_THROW(e) \
BOOST_THROW_EXCEPTION((e))
{
GMX_THROW(FileIOError("Could not open file"), "fopen", errno);
}
- * \endcode
+ \endcode
*/
#define GMX_THROW_WITH_ERRNO(e, syscall, err) \
do { \
/*! \brief
* Formats a standard fatal error message for reporting an exception.
*
- * \param[in] fp File to format the message to.
+ * \param[in] fp %File to format the message to.
* \param[in] ex Exception to format.
*
* Does not throw. If memory allocation fails or some other error occurs
* \code
int main(int argc, char *argv[])
{
- gmx::ProgramInfo::init(argc, argv);
+ gmx::init(&argc, &argv);
try
{
// The actual code for the program
catch (const std::exception &ex)
{
gmx::printFatalErrorMessage(stderr, ex);
- return 1;
+ return gmx::processExceptionAtExit(ex);
}
}
- * \endcode
+ \endcode
*/
void printFatalErrorMessage(FILE *fp, const std::exception &ex);
/*! \brief
* \param[in] ex Exception to format.
* \returns Formatted string containing details of \p ex.
* \throws std::bad_alloc if out of memory.
+ */
+std::string formatExceptionMessageToString(const std::exception &ex);
+/*! \brief
+ * Formats an error message for reporting an exception.
+ *
+ * \param fp %File to write the message to.
+ * \param[in] ex Exception to format.
+ * \throws std::bad_alloc if out of memory.
+ */
+void formatExceptionMessageToFile(FILE *fp, const std::exception &ex);
+/*! \brief
+ * Handles an exception that is causing the program to terminate.
+ *
+ * \param[in] ex Exception that is the cause for terminating the program.
+ * \returns Return code to return from main().
+ *
+ * This method should be called as the last thing before terminating the
+ * program because of an exception. It exists to terminate the program as
+ * gracefully as possible in the case of MPI processing (but the current
+ * implementation always calls MPI_Abort()).
+ *
+ * See printFatalErrorMessage() for example usage.
*
- * Currently, the output format is useful mainly for tests and debugging
- * purposes; additional flags for controlling the format can be added if other
- * uses for the function arise.
+ * Does not throw.
*/
-std::string formatException(const std::exception &ex);
+int processExceptionAtExit(const std::exception &ex);
/*! \brief
* Converts an exception into a return code.
*/
int translateException(const std::exception &ex);
-/*!\}*/
-
-/*! \cond libapi */
-/*! \libinternal \brief
+/*! \brief
* Macro for catching exceptions at C++ -> C boundary.
*
* This macro is intended for uniform handling of exceptions when C++ code is
* behavior if needed.
*
* Usage:
- * \code
+ \code
try
{
// C++ code
}
GMX_CATCH_ALL_AND_EXIT_WITH_FATAL_ERROR;
- * \endcode
- *
- * \inlibraryapi
+ \endcode
*/
#define GMX_CATCH_ALL_AND_EXIT_WITH_FATAL_ERROR \
catch (const std::exception &ex) { \
::gmx::printFatalErrorMessage(stderr, ex); \
- std::exit(1); \
+ ::std::exit(::gmx::processExceptionAtExit(ex)); \
}
-//! \endcond
+
+//! \}
} // namespace gmx