/*
+ * This file is part of the GROMACS molecular simulation package.
*
- * This source code is part of
+ * 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.
*
- * G R O M A C S
- *
- * GROningen MAchine for Chemical Simulations
+ * GROMACS is free software; you can redistribute it and/or
+ * modify it under the terms of the GNU Lesser General Public License
+ * as published by the Free Software Foundation; either version 2.1
+ * of the License, or (at your option) any later version.
*
- * Written by David van der Spoel, Erik Lindahl, Berk Hess, and others.
- * Copyright (c) 1991-2000, University of Groningen, The Netherlands.
- * Copyright (c) 2001-2009, The GROMACS development team,
- * check out http://www.gromacs.org for more information.
+ * GROMACS is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
+ * Lesser General Public License for more details.
*
- * This program is free software; you can redistribute it and/or
- * modify it under the terms of the GNU General Public License
- * as published by the Free Software Foundation; either version 2
- * of the License, or (at your option) any later version.
+ * You should have received a copy of the GNU Lesser General Public
+ * License along with GROMACS; if not, see
+ * http://www.gnu.org/licenses, or write to the Free Software Foundation,
+ * Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
*
- * If you want to redistribute modifications, please consider that
- * scientific software is very special. Version control is crucial -
- * bugs must be traceable. We will be happy to consider code for
- * inclusion in the official distribution, but derived work must not
- * be called official GROMACS. Details are found in the README & COPYING
- * files - if they are missing, get the official version at www.gromacs.org.
+ * If you want to redistribute modifications to GROMACS, please
+ * consider that scientific software is very special. Version
+ * control is crucial - bugs must be traceable. We will be happy to
+ * consider code for inclusion in the official distribution, but
+ * derived work must not be called official GROMACS. Details are found
+ * in the README & COPYING files - if they are missing, get the
+ * official version at http://www.gromacs.org.
*
* To help us fund GROMACS development, we humbly ask that you cite
- * the papers on the package - you can find them in the top README file.
- *
- * For more info, check our website at http://www.gromacs.org
+ * the research papers on the package. Check out http://www.gromacs.org.
*/
/*! \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@cbr.su.se>
+ * \author Teemu Murtola <teemu.murtola@gmail.com>
* \inpublicapi
* \ingroup module_utility
*/
#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] ex Exception to format.
+ *
* Does not throw. If memory allocation fails or some other error occurs
* while formatting the error, tries to print a reasonable alternative message.
*
* \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
+ * Formats an error message for reporting an exception.
+ *
+ * \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.
+ *
+ * Does not throw.
+ */
+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