Line data Source code
1 : /* +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
2 : Copyright (c) 2012-2023 The plumed team
3 : (see the PEOPLE file at the root of the distribution for a list of names)
4 :
5 : See http://www.plumed.org for more information.
6 :
7 : This file is part of plumed, version 2.
8 :
9 : plumed is free software: you can redistribute it and/or modify
10 : it under the terms of the GNU Lesser General Public License as published by
11 : the Free Software Foundation, either version 3 of the License, or
12 : (at your option) any later version.
13 :
14 : plumed 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
17 : GNU Lesser General Public License for more details.
18 :
19 : You should have received a copy of the GNU Lesser General Public License
20 : along with plumed. If not, see <http://www.gnu.org/licenses/>.
21 : +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ */
22 : #ifndef __PLUMED_tools_Exception_h
23 : #define __PLUMED_tools_Exception_h
24 :
25 : #include <exception>
26 : #include <string>
27 : #include <stdexcept>
28 : #include <sstream>
29 : #include <array>
30 :
31 : namespace PLMD {
32 :
33 : /**
34 : \ingroup TOOLBOX
35 : Class to deal with Plumed runtime errors.
36 :
37 : This class and the related macros can be used to detect programming
38 : errors. Typical cases are internal inconsistencies or errors in the plumed<->MD
39 : interface. Mistakes made by final users (i.e. in the `plumed.dat` file)
40 : should probably be documented in some better way (e.g. printing parts of the manual in the output).
41 : However, also this class allows for significant information to be attached.
42 : Let's try to make error messages as informative as possible!
43 :
44 : \note This class has been rewritten in PLUMED 2.5. It works in a backward compatible manner,
45 : but is much more flexible. The main novelty is that we can use insertion operators to
46 : add arbitrary messages, as in `plumed_error()<<"check this vector "<<v;`
47 : See below for more details.
48 :
49 : To throw an error, just throw a c++ exception
50 : \verbatim
51 : if(something_bad) throw Exception();
52 : \endverbatim
53 : or better add an error message to that
54 : \verbatim
55 : if(something_bad) throw Exception("describe the error here");
56 : \endverbatim
57 :
58 : As of PLUMED 2.5 you can add multiple messages, they will just be concatenated,
59 : but to do se you should use the insertion operator. Notice that anything that
60 : can be formatted with an insertion operator can go to the exception, even a \ref Vector
61 : \verbatim
62 : Vector v;
63 : if(something_bad) throw Exception()<<"problem with this "<<v;
64 : \endverbatim
65 : In principle you can mix the two syntax (add a message as an argument and insert others with `<<`),
66 : however it is not very clear and should be avoided.
67 : We only allow using arguments in parenthesis in order to keep backward compatibility.
68 :
69 : \par Using macros
70 :
71 : In order to provide more context, especially for debugging, it might be useful to know where the exception
72 : originated from. The macros below add information about the exact location of the error in the file (filename, line
73 : and, when available, function name). Macros ending in "error" unconditionally throw
74 : the exception, whereas macros ending in "assert" first perform a conditional check
75 : (similarly to standard assert()).
76 : An extra `m` in the name (e.g. `plumed_merror`) indicates a macro that provides a message as its argument.
77 : However, as of PLUMED 2.5 we should prefer adding messages using insertion operators.
78 : \verbatim
79 : // this is correct but not recommended. add a message please!
80 : plumed_assert(a>0);
81 :
82 : // this is the old syntax (with argument).
83 : // this syntax is basically available for backward compatibility.
84 : plumed_massert(a>0,"a should be larger than zero);
85 :
86 : // this is the recommended syntax, with insertion operators.
87 : // it allows to easily insert multiple objects
88 : plumed_assert(a>0)<<"a should be larger than zero. a="<<a;
89 :
90 : // same as above, but the test is made explicitly:
91 : if(a<=0) plumed_error();
92 : if(a<=0) plumed_error("a should be larger than zero);
93 : if(a<=0) plumed_error()<<"a should be larger than zero. a="<<a;
94 : \endverbatim
95 :
96 : The additional macros
97 : plumed_dbg_assert() and plumed_dbg_massert() are similar
98 : to plumed_assert() and plumed_massert() respectively, but the corresponding
99 : check is only performed when NDEBUG macro is not defined. They should
100 : be used when the check is expensive and should be skipped in production
101 : code. So, for instance, in the following case:
102 : \verbatim
103 : plumed_dbg_assert(expensive_function(i)>0)<<"message";
104 : \endverbatim
105 : `expensive_function()` is not called in the production code.
106 : Notice that the compiler should be able to completely optimize away the
107 : whole statement including functions used to produce the message as in this example:
108 : \verbatim
109 : plumed_dbg_assert(expensive_function(i)>0)<<"I did this check "<<other_expensive_function(i);
110 : \endverbatim
111 :
112 : Finally, notice that there is another macro available, \ref plumed_here.
113 : In can be used in order to create an exception with information about the
114 : line/file coordinates without trowing it. That is, the two following syntaxes
115 : are equivalent
116 : \verbatim
117 : // First way, all at once
118 : plumed_error()<<"some message";
119 : /////////////////////////////////
120 : // Second way, one step at a time
121 : // Create exception
122 : Exception e;
123 : // Append information about line and file
124 : e<<plumed_here;
125 : // Append some other message
126 : e<<"some message";
127 : // Throw the resulting exception
128 : throw e;
129 : \endverbatim
130 :
131 : Exceptions can be caught within plumed or outside of it.
132 : E.g., in an external c++ code using PLUMED as a library, one can type
133 : \verbatim
134 : try{
135 : plumed.cmd("setPrecision",n);
136 : } catch (const std::exception & e) {
137 : std::printf("ee %s",e.what());
138 : exit(1);
139 : }
140 : \endverbatim
141 : This can be useful if an external code wants to exit in a controlled manner
142 : (e.g. flushing files, printing the error message in a specific file, etc.)
143 : but is anyway limited to c++ codes. Moreover,
144 : since these errors are expected to be unrecoverable, the MD code will
145 : usually not be able to do something more clever than exiting.
146 :
147 : \note
148 : We store message and stack trace in growing strings. This is in
149 : principle not recommended, since copying the exception might fail if
150 : copying the string throw another exception. However, this has been like
151 : this in all previous PLUMED versions. In case it is necessary, we can replace
152 : it later with a fixed size array placed on the stack.
153 :
154 : */
155 : class Exception : public std::exception {
156 : /// Reported message. Can be updated.
157 : std::string msg;
158 : /// Flag to remember if we have to write the `+++ message follows +++` string.
159 : /// Needed so that the string appears only at the beginning of the message.
160 : bool note=true;
161 : /// Stream used to insert objects.
162 : /// It is not copied when the Exception is copied.
163 : std::stringstream stream;
164 : /// Stack trace, computed at construction
165 : std::array<void*,128> callstack;
166 : /// Number of frames in stack, computed at construction
167 : int callstack_n=0;
168 : /// Parsed stack trace. Built at first use, thus mutable.
169 : mutable std::string stackTrace;
170 :
171 : public:
172 :
173 : /// Auxiliary containing the location of the exception in the file.
174 : /// Typically used from the macros below.
175 : class Location {
176 : public:
177 : const char*file;
178 : const unsigned line;
179 : const char* pretty;
180 54 : explicit Location(const char*file,unsigned line,const char* pretty=nullptr):
181 54 : file(file),
182 54 : line(line),
183 54 : pretty(pretty)
184 : {}
185 : };
186 :
187 : /// Auxiliary containing the failed assertion.
188 : /// Typically used from the macros below.
189 : class Assertion {
190 : public:
191 : const char*assertion;
192 10 : explicit Assertion(const char*assertion=nullptr):
193 10 : assertion(assertion)
194 : {}
195 : };
196 :
197 : /// Auxiliary class used to throw exceptions.
198 : /// It just defines <<= operator so that:
199 : /// - exceptions can be thrown calling std::throw_with_nested
200 : /// with a "throw like" syntax
201 : /// - precedence is the same as the throw operator
202 : /// (see https://en.cppreference.com/w/cpp/language/operator_precedence)
203 : class Throw {
204 : public:
205 : template <typename E>
206 2 : [[noreturn]] void operator <<=(E&&e) {
207 4 : if(std::current_exception()) {
208 2 : std::throw_with_nested(e);
209 : } else {
210 : // if not nested, avoid modifying the exception type
211 0 : throw e;
212 : }
213 : }
214 : };
215 :
216 : /// Default constructor with no message.
217 : /// Only records the stack trace.
218 : Exception();
219 :
220 : /// Constructor compatible with PLUMED <=2.4.
221 31 : explicit Exception(const std::string & msg):
222 31 : Exception() {
223 31 : *this << msg;
224 31 : }
225 :
226 : /// Copy constructor.
227 : /// Needed to make sure stream is not copied
228 70 : Exception(const Exception & e):
229 70 : msg(e.msg),
230 70 : note(e.note),
231 70 : callstack(e.callstack),
232 70 : callstack_n(e.callstack_n),
233 70 : stackTrace(e.stackTrace) {
234 70 : }
235 :
236 : /// Assignment.
237 : /// Needed to make sure stream is not copied
238 : Exception & operator=(const Exception & e) {
239 : msg=e.msg;
240 : note=e.note;
241 : callstack=e.callstack;
242 : callstack_n=e.callstack_n;
243 : stackTrace=e.stackTrace;
244 : stream.str("");
245 : return *this;
246 : }
247 :
248 : /// Returns the error message.
249 : /// In case the environment variable PLUMED_STACK_TRACE was defined
250 : /// and equal to `yes` when the exception was raised,
251 : /// the error message will contain the stack trace as well.
252 121 : const char* what() const noexcept override {
253 121 : return msg.c_str();
254 : }
255 :
256 : /// Returns the stack trace as a string.
257 : /// This function is slow as it requires building a parsed string.
258 : /// If storing the stack for later usage, you might prefer to use trace().
259 : const char* stack() const;
260 :
261 : /// Returns the callstack.
262 : const std::array<void*,128> & trace() const noexcept {
263 : return callstack;
264 : }
265 :
266 : /// Returns the number of elements in the trace array
267 : int trace_n() const noexcept {
268 : return callstack_n;
269 : }
270 :
271 : /// Destructor should be defined and should not throw other exceptions
272 144 : ~Exception() noexcept override {}
273 :
274 : /// Insert location.
275 : /// Format the location properly.
276 : Exception& operator<<(const Location&);
277 :
278 : /// Insert assertion.
279 : /// Format the assertion properly
280 : Exception& operator<<(const Assertion&);
281 :
282 : /// Insert string.
283 : /// Append this string to the message.
284 : Exception& operator<<(const std::string&);
285 :
286 : /// Insert anything else.
287 : /// This allows to dump also other types (e.g. double, or even Vector).
288 : /// Anything that can be written on a stream can go here.
289 : template<typename T>
290 267 : Exception& operator<<(const T & x) {
291 267 : stream<<x;
292 267 : (*this)<<stream.str();
293 267 : stream.str("");
294 267 : return *this;
295 : }
296 : };
297 :
298 : /// Class representing a generic error
299 143 : class ExceptionError :
300 : public Exception {
301 : public:
302 1 : using Exception::Exception;
303 : template<typename T>
304 : ExceptionError& operator<<(const T & x) {
305 89 : *static_cast<Exception*>(this) <<x;
306 : return *this;
307 : }
308 : };
309 :
310 : /// Class representing a debug error (can only be thrown when using debug options)
311 0 : class ExceptionDebug :
312 : public Exception {
313 : public:
314 1 : using Exception::Exception;
315 : template<typename T>
316 : ExceptionDebug& operator<<(const T & x) {
317 : *static_cast<Exception*>(this) <<x;
318 : return *this;
319 : }
320 : };
321 :
322 : /// Class representing a type error in the PLMD::Plumed interface
323 111 : class ExceptionTypeError :
324 : public Exception {
325 : public:
326 0 : using Exception::Exception;
327 : template<typename T>
328 : ExceptionTypeError& operator<<(const T & x) {
329 107 : *static_cast<Exception*>(this) <<x;
330 : return *this;
331 : }
332 : };
333 :
334 : #ifdef __GNUG__
335 : // With GNU compiler, we can use __PRETTY_FUNCTION__ to get the function name
336 : #define __PLUMED_FUNCNAME __PRETTY_FUNCTION__
337 : #else
338 : // Otherwise, we use the standard C++11 variable
339 : #define __PLUMED_FUNCNAME __func__
340 : #endif
341 :
342 : #ifndef PLUMED_MODULE_DIR
343 : #define PLUMED_MODULE_DIR ""
344 : #endif
345 :
346 : /// \relates PLMD::Exception
347 : /// Auxiliary macro that generates a PLMD::Exception::Location object.
348 : /// Might be useful if we want to use derived exceptions that could
349 : /// be thrown using `throw DerivedException()<<plumed_here<<" "<<other stuff"`.
350 : /// It is used in the macros below to throw PLMD::Exception.
351 : #define plumed_here PLMD::Exception::Location(PLUMED_MODULE_DIR __FILE__,__LINE__,__PLUMED_FUNCNAME)
352 :
353 : /// \relates PLMD::Exception
354 : /// Throw an exception with information about the position in the file.
355 : /// Messages can be inserted with `plumed_error()<<"message"`.
356 : #define plumed_error() throw PLMD::ExceptionError() << plumed_here
357 :
358 : /// \relates PLMD::Exception
359 : /// Throw a nested exception with information about the position in the file.
360 : /// It preliminary checks if we are in a catch block. If so, the caught exception
361 : /// is rethrown as nested. If not, it throws a normal ExceptionError.
362 : /// NB in theory we could have just redefined plumed_error to this, but
363 : /// for some reason cppcheck does not understand that the <<= operator used here is
364 : /// [[noreturn]] and thus gives many false warnings
365 : #define plumed_error_nested() PLMD::Exception::Throw() <<= PLMD::ExceptionError() << plumed_here
366 :
367 : /// \relates PLMD::Exception
368 : /// Throw an exception with information about the position in the file
369 : /// and a message. Mostly available for backward compatibility
370 : #define plumed_merror(msg) plumed_error() << msg
371 :
372 : /// \relates PLMD::Exception
373 : /// Launches plumed_merror only if test evaluates to false.
374 : /// The string describing the test is also reported.
375 : /// Further messages can be inserted with `<<`.
376 : #define plumed_assert(test) if(!(test)) plumed_error() << PLMD::Exception::Assertion(#test)
377 :
378 : /// \relates PLMD::Exception
379 : /// Launches plumed_merror only if test evaluates to false.
380 : /// The string describing the test is also reported, in addition to
381 : /// messages reported in the extra argument. Mostly available for backward compatibility.
382 : #define plumed_massert(test,msg) plumed_assert(test) << msg
383 :
384 : #ifdef NDEBUG
385 :
386 : // These are the versions used when compiling with NDEBUG flag.
387 : // The if constexpr(false) gurarantees that the compiler will optimize away the assertion
388 : // We are not using an empty macro becasue the user may want to use the << operator
389 :
390 : #define plumed_dbg_assert(test) if constexpr(false) plumed_assert(true)
391 : #define plumed_dbg_massert(test,msg) if constexpr(false) plumed_massert(true,msg)
392 :
393 : #else
394 :
395 : /// \relates PLMD::Exception
396 : /// Same as \ref plumed_assert, but only evaluates the condition if NDEBUG is not defined.
397 : #define plumed_dbg_assert(test) if(!(test)) PLMD::Exception::Throw() <<= PLMD::ExceptionDebug() << plumed_here << PLMD::Exception::Assertion(#test) << "(this check is enabled only in debug builds)\n"
398 :
399 : /// \relates PLMD::Exception
400 : /// Same as \ref plumed_massert, but only evaluates the condition if NDEBUG is not defined.
401 : #define plumed_dbg_massert(test,msg) plumed_dbg_assert(test) << msg
402 :
403 : #endif
404 :
405 : }
406 : #endif
|
