| Cantera 3.0.0

Loading...
Searching...
No Matches
ctexceptions.h
Go to the documentation of this file.
1/**
2 * @file ctexceptions.h
3 * Definitions for the classes that are
4 * thrown when %Cantera experiences an error condition
5 * (also contains errorhandling module text - see @ref errGroup).
6 */
7
8// This file is part of Cantera. See License.txt in the top-level directory or
9// at https://cantera.org/license.txt for license and copyright information.
10
11#ifndef CT_CTEXCEPTIONS_H
12#define CT_CTEXCEPTIONS_H
13
14#include "ct_defs.h"
15#include "cantera/base/fmt.h"
16#include <exception>
17
18 namespace Cantera
19{
20
21/**
22 * @defgroup debugGroup Errors and Diagnostics
23*/
24
25/**
26 * @defgroup errGroup Errors
27 *
28 * @brief Handling of errors and unknown events within %Cantera.
29 *
30 * The general idea is that exceptions are thrown using the common base class
31 * called CanteraError. Derived types of CanteraError characterize what type of
32 * error is thrown. A list of all of the thrown errors is kept in the
33 * Application class.
34 *
35 * Any exceptions which are not caught cause a fatal error exit from the
36 * program.
37 *
38 * A group of defines may be used during debugging to assert conditions which
39 * should be true. These are named AssertTrace(), AssertThrow(), and
40 * AssertThrowMsg(). Examples of their usage is given below.
41 *
42 * @code
43 * AssertTrace(p == OneAtm);
44 * AssertThrow(p == OneAtm, "Kinetics::update");
45 * AssertThrowMsg(p == OneAtm, "Kinetics::update",
46 * "Algorithm limited to atmospheric pressure");
47 * @endcode
48 *
49 * Their first argument is a boolean. If the boolean is not true, a CanteraError
50 * is thrown, with descriptive information indicating where the error occurred.
51 * The Assert* checks are skipped if the NDEBUG preprocessor symbol is defined,
52 * for example with the compiler option -DNDEBUG.
53 * @ingroup debugGroup
54 */
55
56
57//! Base class for exceptions thrown by %Cantera classes.
58/*!
59 * This class is the base class for exceptions thrown by Cantera. It inherits
60 * from std::exception so that normal error handling operations from
61 * applications may automatically handle the errors in their own way.
62 *
63 * @ingroup errGroup
64 */
65 class CanteraError : public std::exception
66{
67 public:
68 //! Normal Constructor for the CanteraError base class
69 /*!
70 * @param procedure Name of the function within which the error was
71 * generated. For member functions, this should be written as
72 * `ClassName::functionName`. For constructors, this should be
73 * `ClassName::ClassName`. Arguments can be specified to
74 * disambiguate overloaded functions, such as
75 * `ClassName::functionName(int, int)`.
76 * @param msg Descriptive string describing the type of error message. This
77 * can be a fmt-style format string (that is, using curly braces to indicate
78 * fields), which will be used with additional arguments to generate a
79 * formatted error message
80 * @param args Arguments which will be used to interpolate the format string
81 */
82 template <typename... Args>
83 CanteraError(const string& procedure, const string& msg, const Args&... args)
84 : procedure_(procedure)
85 {
86 if (sizeof...(args) == 0) {
87 msg_ = msg;
88 } else {
89 msg_ = fmt::format(msg, args...);
90 }
91 }
92
93 //! Destructor for base class does nothing
94 virtual ~CanteraError() throw() {};
95
96 //! Get a description of the error
97 const char* what() const throw() override;
98
99 //! Method overridden by derived classes to format the error message
100 virtual string getMessage() const;
101
102 //! Get the name of the method that threw the exception
103 virtual string getMethod() const;
104
105 //! Method overridden by derived classes to indicate their type
106 virtual string getClass() const {
107 return "CanteraError";
108 }
109
110 protected:
111 //! Protected default constructor discourages throwing errors containing no
112 //! information.
113 CanteraError() {};
114
115 //! Constructor used by derived classes that override getMessage()
116 explicit CanteraError(const string& procedure);
117
118 //! The name of the procedure where the exception occurred
119 string procedure_;
120 mutable string formattedMessage_; //!< Formatted message returned by what()
121
122 private:
123 string msg_; //!< Message associated with the exception
124};
125
126
127//! Array size error.
128/*!
129 * This error is thrown if a supplied length to a vector supplied to %Cantera is
130 * too small.
131 *
132 * @ingroup errGroup
133 */
134 class ArraySizeError : public CanteraError
135{
136 public:
137 //! Constructor
138 /*!
139 * The length needed is supplied by the argument, reqd, and the
140 * length supplied is given by the argument sz.
141 *
142 * @param procedure String name for the function within which the error was
143 * generated.
144 * @param sz This is the length supplied to Cantera.
145 * @param reqd This is the required length needed by Cantera
146 */
147 ArraySizeError(const string& procedure, size_t sz, size_t reqd) :
148 CanteraError(procedure), sz_(sz), reqd_(reqd) {}
149
150 string getMessage() const override;
151 string getClass() const override {
152 return "ArraySizeError";
153 }
154
155 private:
156 size_t sz_, reqd_;
157};
158
159
160//! An array index is out of range.
161/*!
162 * @ingroup errGroup
163 */
164 class IndexError : public CanteraError
165{
166 public:
167 //! Constructor
168 /*!
169 * This class indicates an out-of-bounds array index.
170 *
171 * @param func String name for the function within which the error was
172 * generated.
173 * @param arrayName name of the corresponding array
174 * @param m This is the value of the out-of-bounds index.
175 * @param mmax This is the maximum allowed value of the index. The
176 * minimum allowed value is assumed to be 0.
177 */
178 IndexError(const string& func, const string& arrayName, size_t m, size_t mmax) :
179 CanteraError(func), arrayName_(arrayName), m_(m), mmax_(mmax) {}
180
181 ~IndexError() throw() override {};
182 string getMessage() const override;
183 string getClass() const override {
184 return "IndexError";
185 }
186
187 private:
188 string arrayName_;
189 size_t m_, mmax_;
190};
191
192//! An error indicating that an unimplemented function has been called
193//! @ingroup errGroup
194 class NotImplementedError : public CanteraError
195{
196 public:
197 //! @param func Name of the unimplemented function, such as
198 //! `ClassName::functionName`
199 NotImplementedError(const string& func) :
200 CanteraError(func, "Not implemented.") {}
201
202 //! Alternative constructor taking same arguments as CanteraError
203 template <typename... Args>
204 NotImplementedError(const string& func, const string& msg, const Args&... args) :
205 CanteraError(func, msg, args...) {}
206
207 string getClass() const override {
208 return "NotImplementedError";
209 }
210};
211
212//! Provides a line number
213#define XSTR_TRACE_LINE(s) STR_TRACE_LINE(s)
214
215//! Provides a line number
216#define STR_TRACE_LINE(s) #s
217
218//! Provides a string variable containing the file and line number
219/*!
220 * This is a std:string containing the file name and the line number
221 */
222#define STR_TRACE (string(__FILE__) + ":" + XSTR_TRACE_LINE(__LINE__))
223
224#ifdef NDEBUG
225#ifndef AssertTrace
226# define AssertTrace(expr) ((void) (0))
227#endif
228#ifndef AssertThrow
229# define AssertThrow(expr, procedure) ((void) (0))
230#endif
231#ifndef AssertThrowMsg
232# define AssertThrowMsg(expr,procedure, ...) ((void) (0))
233#endif
234#else
235
236//! Assertion must be true or an error is thrown
237/*!
238 * Assertion must be true or else a CanteraError is thrown. A diagnostic string
239 * containing the file and line number, indicating where the error occurred is
240 * added to the thrown object.
241 *
242 * @param expr Boolean expression that must be true
243 *
244 * @ingroup errGroup
245 */
246#ifndef AssertTrace
247# define AssertTrace(expr) ((expr) ? (void) 0 : throw CanteraError(STR_TRACE, string("failed assert: ") + #expr))
248#endif
249
250//! Assertion must be true or an error is thrown
251/*!
252 * Assertion must be true or else a CanteraError is thrown. A diagnostic string
253 * indicating where the error occurred is added to the thrown object.
254 *
255 * @param expr Boolean expression that must be true
256 * @param procedure Character string or std:string expression indicating the
257 * procedure where the assertion failed
258 * @ingroup errGroup
259 */
260#ifndef AssertThrow
261# define AssertThrow(expr, procedure) ((expr) ? (void) 0 : throw CanteraError(procedure, string("failed assert: ") + #expr))
262#endif
263
264//! Assertion must be true or an error is thrown
265/*!
266 * Assertion must be true or else a CanteraError is thrown. A diagnostic string
267 * indicating where the error occurred is added to the thrown object.
268 *
269 * @param expr Boolean expression that must be true
270 * @param procedure Character string or std:string expression indicating
271 * the procedure where the assertion failed
272 * Additional arguments are passed on to the constructor for CanteraError to
273 * generate a formatted error message.
274 *
275 * @ingroup errGroup
276 */
277#ifndef AssertThrowMsg
278# define AssertThrowMsg(expr, procedure, ...) ((expr) ? (void) 0 : throw CanteraError(procedure + string(":\nfailed assert: \"") + string(#expr) + string("\""), __VA_ARGS__))
279#endif
280
281#endif
282
283//! Throw an exception if the specified exception is not a finite number.
284//! @ingroup errGroup
285#ifndef AssertFinite
286# define AssertFinite(expr, procedure, ...) AssertThrowMsg(expr < BigNumber && expr > -BigNumber, procedure, __VA_ARGS__)
287#endif
288
289}
290
291#endif
Cantera::ArraySizeError
Array size error.
Definition ctexceptions.h:135
Cantera::ArraySizeError::ArraySizeError
ArraySizeError(const string &procedure, size_t sz, size_t reqd)
Constructor.
Definition ctexceptions.h:147
Cantera::ArraySizeError::getMessage
string getMessage() const override
Method overridden by derived classes to format the error message.
Definition ctexceptions.cpp:55
Cantera::ArraySizeError::getClass
string getClass() const override
Method overridden by derived classes to indicate their type.
Definition ctexceptions.h:151
Cantera::CanteraError
Base class for exceptions thrown by Cantera classes.
Definition ctexceptions.h:66
Cantera::CanteraError::what
const char * what() const override
Get a description of the error.
Definition ctexceptions.cpp:25
Cantera::CanteraError::getMessage
virtual string getMessage() const
Method overridden by derived classes to format the error message.
Definition ctexceptions.cpp:45
Cantera::CanteraError::formattedMessage_
string formattedMessage_
Formatted message returned by what()
Definition ctexceptions.h:120
Cantera::CanteraError::procedure_
string procedure_
The name of the procedure where the exception occurred.
Definition ctexceptions.h:119
Cantera::CanteraError::~CanteraError
virtual ~CanteraError()
Destructor for base class does nothing.
Definition ctexceptions.h:94
Cantera::CanteraError::CanteraError
CanteraError()
Protected default constructor discourages throwing errors containing no information.
Definition ctexceptions.h:113
Cantera::CanteraError::msg_
string msg_
Message associated with the exception.
Definition ctexceptions.h:123
Cantera::CanteraError::getMethod
virtual string getMethod() const
Get the name of the method that threw the exception.
Definition ctexceptions.cpp:50
Cantera::CanteraError::CanteraError
CanteraError(const string &procedure, const string &msg, const Args &... args)
Normal Constructor for the CanteraError base class.
Definition ctexceptions.h:83
Cantera::CanteraError::getClass
virtual string getClass() const
Method overridden by derived classes to indicate their type.
Definition ctexceptions.h:106
Cantera::IndexError
An array index is out of range.
Definition ctexceptions.h:165
Cantera::IndexError::getMessage
string getMessage() const override
Method overridden by derived classes to format the error message.
Definition ctexceptions.cpp:61
Cantera::IndexError::IndexError
IndexError(const string &func, const string &arrayName, size_t m, size_t mmax)
Constructor.
Definition ctexceptions.h:178
Cantera::IndexError::getClass
string getClass() const override
Method overridden by derived classes to indicate their type.
Definition ctexceptions.h:183
Cantera::NotImplementedError
An error indicating that an unimplemented function has been called.
Definition ctexceptions.h:195
Cantera::NotImplementedError::NotImplementedError
NotImplementedError(const string &func, const string &msg, const Args &... args)
Alternative constructor taking same arguments as CanteraError.
Definition ctexceptions.h:204
Cantera::NotImplementedError::NotImplementedError
NotImplementedError(const string &func)
Definition ctexceptions.h:199
Cantera::NotImplementedError::getClass
string getClass() const override
Method overridden by derived classes to indicate their type.
Definition ctexceptions.h:207
ct_defs.h
This file contains definitions of constants, types and terms that are used in internal routines and a...
fmt.h
Wrapper for either system-installed or local headers for fmt.
Cantera
Namespace for the Cantera kernel.
Definition AnyMap.cpp:564