Cantera  3.1.0a1
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
18namespace 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 */
65class CanteraError : public std::exception
66{
67public:
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
110protected:
111 //! Protected default constructor discourages throwing errors containing no
112 //! information.
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
120 mutable string formattedMessage_; //!< Formatted message returned by what()
121
122private:
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 */
135{
136public:
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
155private:
156 size_t sz_, reqd_;
157};
158
159
160//! An array index is out of range.
161/*!
162 * @ingroup errGroup
163 */
165{
166public:
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
187private:
188 string arrayName_;
189 size_t m_, mmax_;
190};
191
192//! An error indicating that an unimplemented function has been called
193//! @ingroup errGroup
195{
196public:
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
Array size error.
ArraySizeError(const string &procedure, size_t sz, size_t reqd)
Constructor.
string getMessage() const override
Method overridden by derived classes to format the error message.
string getClass() const override
Method overridden by derived classes to indicate their type.
Base class for exceptions thrown by Cantera classes.
const char * what() const override
Get a description of the error.
virtual string getMessage() const
Method overridden by derived classes to format the error message.
string formattedMessage_
Formatted message returned by what()
string procedure_
The name of the procedure where the exception occurred.
virtual ~CanteraError()
Destructor for base class does nothing.
CanteraError()
Protected default constructor discourages throwing errors containing no information.
string msg_
Message associated with the exception.
virtual string getMethod() const
Get the name of the method that threw the exception.
CanteraError(const string &procedure, const string &msg, const Args &... args)
Normal Constructor for the CanteraError base class.
virtual string getClass() const
Method overridden by derived classes to indicate their type.
An array index is out of range.
string getMessage() const override
Method overridden by derived classes to format the error message.
IndexError(const string &func, const string &arrayName, size_t m, size_t mmax)
Constructor.
string getClass() const override
Method overridden by derived classes to indicate their type.
An error indicating that an unimplemented function has been called.
NotImplementedError(const string &func, const string &msg, const Args &... args)
Alternative constructor taking same arguments as CanteraError.
NotImplementedError(const string &func)
string getClass() const override
Method overridden by derived classes to indicate their type.
This file contains definitions of constants, types and terms that are used in internal routines and a...
Wrapper for either system-installed or local headers for fmt.
Namespace for the Cantera kernel.
Definition AnyMap.cpp:564