api/include/gmxapi/exceptions.h

   1 /*
   2  * This file is part of the GROMACS molecular simulation package.
   3  *
   4  * Copyright (c) 2018,2019,2020, 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.
   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 #ifndef GMXAPI_EXCEPTIONS_H
  36 #define GMXAPI_EXCEPTIONS_H
  37 /*! \defgroup gmxapi_exceptions Exceptions
  38  *
  39  * \brief Exceptions thrown by gmxapi components.
  40  *
  41  * \ingroup gmxapi
  42  */
  43 /*! \file
  44  * \brief Declare exception classes for operations in gmxapi.
  45  *
  46  * \author M. Eric Irrgang <ericirrgang@gmail.com>
  47  *
  48  * \ingroup gmxapi_exceptions
  49  */
  50
  51 #include <exception>
  52 #include <string>
  53
  54 namespace gmxapi
  55 {
  56
  57 /*! \brief Base exception for gmxapi library.
  58  *
  59  * Exceptions thrown in the gmxapi namespace are descended from gmxapi::Exception
  60  * or there is a bug.
  61  *
  62  * \ingroup gmxapi_exceptions
  63  */
  64 class Exception : public std::exception
  65 {
  66 public:
  67     //! \cond
  68     Exception();
  69     ~Exception() override;
  70     Exception(const Exception& /*unused*/);
  71     Exception& operator=(const Exception& /*unused*/);
  72
  73     Exception(Exception&& /*unused*/) noexcept;
  74     Exception& operator=(Exception&& /*unused*/) noexcept;
  75
  76     const char* what() const noexcept override;
  77     //! \endcond
  78 };
  79
  80 /*!
  81  * \brief Basic implementation mix-in for exceptions.
  82  *
  83  * Allow exceptions to be defined with minimal syntax when their primary function is
  84  * to exist as distinct named types.
  85  *
  86  * \tparam E the class using this template as a base class.
  87  *
  88  * Use in the "curiously recurring template pattern".
  89  *
  90  * Example:
  91  *
  92  *     class DerivedException : public BasicException<DerivedException>
  93  *     {
  94  *          public:
  95  *              using BasicException::BasicException;
  96  *     };
  97  *
  98  * \note Current implementation only provides constructors and no specialized or dispatched behavior.
  99  *
 100  * \ingroup gmxapi_exceptions
 101  */
 102 template<class E>
 103 class BasicException : public Exception
 104 {
 105 private:
 106     //! Store the usual exception message as a std::string instead of C string.
 107     std::string what_;
 108
 109 public:
 110     //! Initialize with empty message.
 111     BasicException() : BasicException{ std::string() } {}
 112
 113     /*!
 114      * \brief Copy a string to use for the exception message.
 115      *
 116      * \param message
 117      * \{
 118      */
 119     explicit BasicException(std::string message) noexcept : what_{ std::move(message) } {}
 120
 121     explicit BasicException(const char* message) { what_ = message; }
 122     //! \}
 123
 124     /*!
 125      * \brief Get message.
 126      *
 127      * \return pointer to C string.
 128      *
 129      * It is the responsibility of the caller to keep the Exception object alive while the char
 130      * pointer is in use.
 131      */
 132     const char* what() const noexcept override { return what_.c_str(); }
 133 };
 134
 135 /*! \brief Behavioral protocol violated.
 136  *
 137  * Indicates that a behavioral protocol specified in the API is not being followed. The class
 138  * throwing this exception expects certain methods to be called in a certain order.
 139  *
 140  * If this exception is encountered in client code, the API is being misused or there is a bug.
 141  * (Generally, required behaviors should be implemented in templates or base classes rather than
 142  * exposing and requiring complete implementation of the protocol in client code.)
 143  *
 144  * \ingroup gmxapi_exceptions
 145  */
 146 class ProtocolError : public BasicException<ProtocolError>
 147 {
 148 public:
 149     using BasicException<ProtocolError>::BasicException;
 150 };
 151
 152 /*!
 153  * \brief Intended feature is not implemented.
 154  *
 155  * Indicates a bug in the API implementation. Either a version mismatch between the client
 156  * and library has gone undetected, or the API has purported to offer functionality that does
 157  * not exist.
 158  *
 159  * \ingroup gmxapi_exceptions
 160  */
 161 class NotImplementedError : public BasicException<NotImplementedError>
 162 {
 163 public:
 164     using BasicException<NotImplementedError>::BasicException;
 165 };
 166
 167 /*!
 168  * \brief Unacceptable API usage.
 169  *
 170  * Usage error. Examples include calling a function with invalid arguments.
 171  *
 172  * \ingroup gmxapi_exceptions
 173  */
 174 class UsageError : public BasicException<UsageError>
 175 {
 176 public:
 177     using BasicException<UsageError>::BasicException;
 178 };
 179
 180 } // end namespace gmxapi
 181
 182 #endif // header guard