casacore
Error.h
Go to the documentation of this file.
1//# Error.h: Base class for all Casacore errors
2//# Copyright (C) 1993,1994,1995,1999,2000,2001,2016
3//# Associated Universities, Inc. Washington DC, USA.
4//#
5//# This library is free software; you can redistribute it and/or modify it
6//# under the terms of the GNU Library General Public License as published by
7//# the Free Software Foundation; either version 2 of the License, or (at your
8//# option) any later version.
9//#
10//# This library is distributed in the hope that it will be useful, but WITHOUT
11//# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
12//# FITNESS FOR A PARTICULAR PURPOSE. See the GNU Library General Public
13//# License for more details.
14//#
15//# You should have received a copy of the GNU Library General Public License
16//# along with this library; if not, write to the Free Software Foundation,
17//# Inc., 675 Massachusetts Ave, Cambridge, MA 02139, USA.
18//#
19//# Correspondence concerning AIPS++ should be addressed as follows:
20//# Internet email: aips2-request@nrao.edu.
21//# Postal address: AIPS++ Project Office
22//# National Radio Astronomy Observatory
23//# 520 Edgemont Road
24//# Charlottesville, VA 22903-2475 USA
25//#
26//# $Id$
27
28#ifndef CASA_ERROR_H
29#define CASA_ERROR_H
30
31
32#include <casacore/casa/aips.h>
33#include <casacore/casa/BasicSL/String.h>
34#include <exception>
35#include <sys/types.h>
36
37
38namespace casacore { //# NAMESPACE CASACORE - BEGIN
39
40// Throw the given exception with a string composed of various arguments.
41// E.g.
42// <srcblock>
43// CASATHROW (AipsError, "integer=" << myint << ", float=" << myfloat);
44// </srcblock>
45#define CASATHROW(exc, arg) do { \
46 std::ostringstream casa_log_oss; \
47 casa_log_oss << arg; \
48 throw exc(casa_log_oss.str()); \
49 } while (0)
50
51// The Assert macro is an alias to the standard assert macro when NDEBUG is defined. When
52// NDEBUG is not defined (release build) then a throw is used to report the error.
53
54#ifdef NDEBUG
55#define AssertCc(c) ((void)0)
56#else
57#define AssertCc(c) { if (AIPS_UNLIKELY(! (c))) {casacore::AipsError::throwIf (casacore::True, "Assertion failed: " #c, __FILE__, __LINE__, __PRETTY_FUNCTION__); }}
58#endif
59
60#define AssertAlways(c) { if (AIPS_UNLIKELY(! (c))) {casacore::AipsError::throwIf (casacore::True, "Assertion failed: " #c, __FILE__, __LINE__, __PRETTY_FUNCTION__); }}
61
62#define WarnCc(m)\
63{\
64 LogIO os(LogOrigin("", __func__, __LINE__, WHERE));\
65 os << LogIO::WARN << m << LogIO::POST;\
66}
67
68
69// Asserts when in debug build and issues a warning message to the log in release.
70#if defined (NDEBUG)
71#define AssertOrWarn(c,m) ((void)0)
72#else
73#define AssertOrWarn(c,m)\
74{ if (AIPS_UNLIKELY(! (c))) {\
75 WarnCc (m);\
76 }\
77}
78#endif
79
80#if defined (NDEBUG)
81# define ThrowCc(m) \
82 { casacore::AipsError anAipsError ((m), __FILE__, __LINE__); \
83 throw anAipsError; }
84#else
85# define ThrowCc(m) throw casacore::AipsError ((m), __FILE__, __LINE__)
86#endif
87
88// Throw an AipsError exception if the condition is true.
89#define ThrowIf(c,m) {if (AIPS_UNLIKELY(c)) {casacore::AipsError::throwIf (casacore::True, (m), __FILE__, __LINE__, __PRETTY_FUNCTION__);}}
90
91// Throw an AipsError exception if the system error code is not 0.
92// It adds the message for that error code to the exception text.
93#define ThrowIfError(c,m) {if (AIPS_UNLIKELY(c)) {casacore::AipsError::throwIfError (casacore::True, (m), __FILE__, __LINE__, __PRETTY_FUNCTION__);}}
94
95// Repackage and rethrow an AipsError exception.
96#define Rethrow(e,m) {throw casacore::AipsError::repackageAipsError ((e),(m),__FILE__,__LINE__, __PRETTY_FUNCTION__);}
97
98
99// <summary>Base class for all Casacore library errors</summary>
100// <use visibility=export>
101//
102// <reviewed reviewer="UNKNOWN" date="before2004/08/25" tests="" demos="">
103// </reviewed>
104//
105// <prerequisite>
106// <li> ExcpError
107// </prerequisite>
108//
109// <synopsis>
110// This is the base class for all of the Casacore error classes. Because
111// all of the errors have a common base class, any error can be caught
112// with a single catch statement.
113//
114// This class has a string which allows error messages to be propagated.
115//
116// <note role=tip> The string member must be handled very carefully because
117// string is also derived from cleanup, thus the
118// <src>message.makePermanent()</src> call in the implementation of
119// the constructors. This prevents the String from being cleaned up
120// in the middle of an exception.
121// </note>
122//
123// </synopsis>
124//
125// <example>
126// <srcblock>
127// throw(AipsError("SOME STRING"));
128// </srcblock>
129// </example>
130//
131// <todo asof="">
132// </todo>
133
134class AipsError: public std::exception
135{
136public:
137
138 enum Category {
141 };
142
143 //
144 // Simply returns the stored error message.
145 //
146 virtual const char* what() const noexcept
147 { return(message.c_str()); }
148 const String &getMesg() const
149 { return(message); }
152 { return(category); }
153
154 // Append a message. This is used by LogIO when an exception is logged.
155 // The message is const to be able to use it for a temporary exception.
156 void setMessage (const String& msg) const
157 { const_cast<AipsError*>(this)->message = msg; }
158
159 // Creates an AipsError and initializes the error message from
160 // the parameter.
161 // <group>
162 AipsError (const Char *str, Category c = GENERAL);
164 AipsError (const String &msg, const String &filename, uInt lineNumber,
165 Category c = GENERAL);
167 // </group>
168
169 //
170 // Destructor which does nothing.
171 //
172 ~AipsError() noexcept;
173
174 // Get or clear the stacktrace info.
175 // <group>
179 static void clearLastInfo ();
180 // </group>
181
182 // Repackage an exception.
184 const String& message,
185 const char* file,
186 Int line,
187 const char* func);
188
189 // Throw if the condition is true.
190 static void throwIf (Bool condition, const String& message,
191 const char* file, Int line,
192 const char* func = "");
193
194 // Throw if the system error code is not 0.
195 static void throwIfError (Int errorCode, const String& prefix,
196 const char* file, Int line,
197 const char* func = "");
198
199protected:
200 // Add the stack trace to the message (if USE_STACKTRACE is set).
202
206};
207
208
209// <summary>Allocation errors</summary>
210// <use visibility=export>
211//
212// <reviewed reviewer="UNKNOWN" date="before2004/08/25" tests="" demos="">
213// </reviewed>
214//
215// <synopsis>
216//
217// This class is used for allocation errors. It adds an extra
218// data item, the failed allocation size. Otherwise much the
219// same as <src>AipsError</src>.
220//
221// </synopsis>
222//
223// <example>
224// <srcblock>
225// throw(AllocError("ANY STRING",1024));
226// </srcblock>
227// </example>
228//
229// <todo asof="">
230// </todo>
231
232class AllocError : public AipsError {
233protected:
234 size_t Size;
235public:
236 //
237 // This constructor takes the error message and the failed
238 // allocation size.
239 //
240 // <group>
241 AllocError(const Char *str, uInt sze) : AipsError(str,SYSTEM), Size(sze) {}
242 AllocError(const String &str, uInt sze) : AipsError(str,SYSTEM), Size(sze) {}
243 // </group>
244
245 //
246 // This function returns the failed allocation size.
247 //
248 size_t size() const {return(Size);}
249
250 //
251 // Destructor which does nothing.
252 //
253 ~AllocError() noexcept;
254
255};
256
257
258// <summary>Base class for all indexing errors</summary>
259// <use visibility=export>
260//
261// <reviewed reviewer="UNKNOWN" date="before2004/08/25" tests="" demos="">
262// </reviewed>
263//
264// <synopsis>
265// This class is the base class of all <src>IndexError</src>s. It is
266// defined to allow the user to catch any of the many kinds of IndexErrors
267// which may be thrown. It can also be thrown itself if returning
268// the illegal index value is unimportant.
269// </synopsis>
270//
271// <example>
272// <srcblock>
273// throw(IndexError("ANY STRING"));
274// </srcblock>
275// </example>
276//
277// <todo asof="">
278// </todo>
279
280class IndexError : public AipsError {
281public:
282 //
283 // Creates an GeneralIndexError and initializes the error message from
284 // the parameter
285 // <group>
289 // </group>
290
291 //
292 // Destructor which does nothing.
293 //
294 ~IndexError() noexcept;
295};
296
297
298// <summary>Index errors returning the bad index</summary>
299// <use visibility=export>
300//
301// <reviewed reviewer="UNKNOWN" date="before2004/08/25" tests="" demos="">
302// </reviewed>
303//
304// <synopsis>
305// This class is templated to allow generalalized indexes to be returned
306// with the error message i.e. the class is templated on the index type.
307//
308// </synopsis>
309//
310// <example>
311// <srcblock>
312// throw(indexError<int>(3,"ANY STRING"));/
313// </srcblock>
314// </example>
315//
316// <todo asof="">
317// </todo>
318
319template<class t> class indexError : public IndexError {
320protected:
321 t oIndex; // Offending Index
322public:
323 //
324 // This constructor takes the error message and the index
325 // which cause the error to occur.
326 //
327 // <group>
328 indexError(t oI, const Char *str, Category c=BOUNDARY);
329 indexError(t oI, const String &str, Category c=BOUNDARY);
330 indexError(t oI, Category c=BOUNDARY) : IndexError(c), oIndex(oI) {};
331 // </group>
332
333 //
334 // Destructor which does nothing.
335 //
336 ~indexError() noexcept;
337};
338
339
340// <summary>Duplicate key errors</summary>
341// <use visibility=export>
342//
343// <reviewed reviewer="UNKNOWN" date="before2004/08/25" tests="" demos="">
344// </reviewed>
345//
346// <synopsis>
347// This class is the base class of all duplicate key errors. It is
348// defined to allow the user to catch any of the many kinds of DuplErrors
349// which may be thrown. It can also be thrown itself if returning
350// the illegal key is unimportant.
351// </synopsis>
352//
353// <example>
354// <srcblock>
355// throw(DuplError("ANY STRING"));
356// </srcblock>
357// </example>
358//
359// <todo asof="">
360// </todo>
361
362class DuplError : public AipsError {
363public:
364 //
365 // Creates an DuplError and initializes the error message from
366 // the parameter
367 // <group>
371 // </group>
372
373 //
374 // Destructor which does nothing.
375 //
376 ~DuplError() noexcept;
377};
378
379
380// <summary>Duplicate key errors where the bad key is returned</summary>
381// <use visibility=export>
382//
383// <reviewed reviewer="UNKNOWN" date="before2004/08/25" tests="" demos="">
384// </reviewed>
385//
386// <synopsis>
387// This template is for generalized duplicate key errors where the template
388// type parameter is the type of the key which caused the error. Because this
389// class is derived from <linkto class=DuplError><src>DuplError</src>
390// </linkto>, the user to catch all duplicate key errors with one catch
391// statement.
392//
393// </synopsis>
394//
395// <example>
396// throw(duplError<int>(4,"ANY STRING"));
397// </example>
398//
399// <todo asof="">
400// </todo>
401
402template<class t> class duplError : public DuplError {
403protected:
404 t oKey; // Offending Key
405public:
406 //
407 // This constructs a "duplError" for the offending key, and an
408 // optional character string.
409 //
410 // <group>
411 duplError(t oI, const Char *str,Category c=BOUNDARY);
412 duplError(t oI, const String &str,Category c=BOUNDARY);
413 duplError(t oI,Category c=BOUNDARY) : DuplError(c), oKey(oI) {};
414 // </group>
415
416 //
417 // Destructor which does nothing.
418 //
419 ~duplError() noexcept;
420};
421
422
423// <summary>Exception for an error in a system call</summary>
424// <use visibility=export>
425//
426// <reviewed reviewer="UNKNOWN" date="before2004/08/25" tests="" demos="">
427// </reviewed>
428//
429// <synopsis>
430// This error is to be used for if a system call returns an error.
431// It uses strerror to get the system error message.
432// </synopsis>
433
435{
436public:
437 // This constructs a "SystemCallError" from the system call function name
438 // and the errno.
439 SystemCallError(const String &funcName, int error, Category c=GENERAL);
440
441 SystemCallError (int error, const String &msg, const String &filename,
442 uInt lineNumber, Category c=GENERAL);
443
444 // Destructor which does nothing.
446
447 // Get the errno.
448 int error() const
449 { return itsError; }
450
451 // Get the message belonging to an error.
452 static String errorMessage(int error);
453
454private:
456};
457
458
459// <summary>Exception which halts execution</summary>
460// <use visibility=export>
461//
462// <reviewed reviewer="UNKNOWN" date="before2004/08/25" tests="" demos="">
463// </reviewed>
464//
465// <synopsis>
466// This error causes an execution to halt regardless. It
467// causes execution to halt before the exception can be caught.
468// </synopsis>
469//
470// <example>
471// <srcblock>
472// throw(AbortError("ANY STRING"));
473// </srcblock>
474// </example>
475//
476// <todo asof="">
477// </todo>
478
479class AbortError : public AipsError {
480public:
481 //
482 // This constructs a "AbortError" from the error message.
483 //
484 // <group>
487 // </group>
488
489 //
490 // Destructor which does nothing.
491 //
492 ~AbortError() noexcept;
493};
494
495
496// <summary>Initialization error, typically of static data shared between objects</summary>
497// <use visibility=export>
498//
499// <reviewed reviewer="UNKNOWN" date="before2004/08/25" tests="" demos="">
500// </reviewed>
501//
502// <synopsis>
503// This error indicates that some initialization has failed. It is preferable
504// to throw this in an initX() function called by std::call_once() or similar
505// over returning a bool or other result variable.
506// </synopsis>
507//
508// <todo asof="">
509// </todo>
510
511class InitError : public AipsError {
512};
513
514} //# NAMESPACE CASACORE - END
515
516#ifdef AIPS_NEEDS_RETHROW
517#ifndef CASACORE_NEEDS_RETHROW
518#define CASACORE_NEEDS_RETHROW
519#endif
520#endif
521
522#ifdef CASACORE_NEEDS_RETHROW
523#define RETHROW(X) throw(X);
524#else
525#define RETHROW(X)
526#endif
527
528#ifndef CASACORE_NO_AUTO_TEMPLATES
529#include <casacore/casa/Exceptions/Error.tcc>
530#endif //# CASACORE_NO_AUTO_TEMPLATES
531#endif
Exception which halts execution.
Definition: Error.h:479
AbortError(const Char *str, Category c=GENERAL)
This constructs a "AbortError" from the error message.
AbortError(const String &str, Category c=GENERAL)
~AbortError() noexcept
Destructor which does nothing.
~AipsError() noexcept
Destructor which does nothing.
static String getLastStackTrace()
AipsError::Category getCategory() const
Definition: Error.h:151
String getStackTrace() const
static void throwIfError(Int errorCode, const String &prefix, const char *file, Int line, const char *func="")
Throw if the system error code is not 0.
AipsError(Category c=GENERAL)
AipsError(const Char *str, Category c=GENERAL)
Creates an AipsError and initializes the error message from the parameter.
static void getLastInfo(String &message, String &stackTrace)
Get or clear the stacktrace info.
static AipsError repackageAipsError(AipsError &error, const String &message, const char *file, Int line, const char *func)
Repackage an exception.
const String & getMesg() const
Definition: Error.h:148
static void throwIf(Bool condition, const String &message, const char *file, Int line, const char *func="")
Throw if the condition is true.
static String getLastMessage()
void setMessage(const String &msg) const
Append a message.
Definition: Error.h:156
static void clearLastInfo()
virtual const char * what() const noexcept
Simply returns the stored error message.
Definition: Error.h:146
AipsError(const String &str, Category c=GENERAL)
String message
Definition: Error.h:203
void addStackTrace()
Add the stack trace to the message (if USE_STACKTRACE is set).
AipsError(const String &msg, const String &filename, uInt lineNumber, Category c=GENERAL)
Category category
Definition: Error.h:204
String stackTrace
Definition: Error.h:205
Allocation errors.
Definition: Error.h:232
size_t size() const
This function returns the failed allocation size.
Definition: Error.h:248
AllocError(const Char *str, uInt sze)
This constructor takes the error message and the failed allocation size.
Definition: Error.h:241
~AllocError() noexcept
Destructor which does nothing.
AllocError(const String &str, uInt sze)
Definition: Error.h:242
Duplicate key errors.
Definition: Error.h:362
DuplError(const String &str, Category c=BOUNDARY)
Definition: Error.h:370
DuplError(Category c=BOUNDARY)
Creates an DuplError and initializes the error message from the parameter.
Definition: Error.h:368
DuplError(const Char *str, Category c=BOUNDARY)
Definition: Error.h:369
~DuplError() noexcept
Destructor which does nothing.
Base class for all indexing errors.
Definition: Error.h:280
~IndexError() noexcept
Destructor which does nothing.
IndexError(const Char *str, Category c=BOUNDARY)
Creates an GeneralIndexError and initializes the error message from the parameter.
Definition: Error.h:286
IndexError(const String &str, Category c=BOUNDARY)
Definition: Error.h:287
IndexError(Category c=BOUNDARY)
Definition: Error.h:288
Initialization error, typically of static data shared between objects.
Definition: Error.h:511
String: the storage and methods of handling collections of characters.
Definition: String.h:225
const Char * c_str() const
Get char array.
Definition: String.h:557
Exception for an error in a system call.
Definition: Error.h:435
static String errorMessage(int error)
Get the message belonging to an error.
~SystemCallError() noexcept
Destructor which does nothing.
SystemCallError(const String &funcName, int error, Category c=GENERAL)
This constructs a "SystemCallError" from the system call function name and the errno.
SystemCallError(int error, const String &msg, const String &filename, uInt lineNumber, Category c=GENERAL)
Duplicate key errors where the bad key is returned.
Definition: Error.h:402
duplError(t oI, Category c=BOUNDARY)
Definition: Error.h:413
duplError(t oI, const String &str, Category c=BOUNDARY)
duplError(t oI, const Char *str, Category c=BOUNDARY)
This constructs a "duplError" for the offending key, and an optional character string.
~duplError() noexcept
Destructor which does nothing.
Index errors returning the bad index.
Definition: Error.h:319
indexError(t oI, Category c=BOUNDARY)
Definition: Error.h:330
~indexError() noexcept
Destructor which does nothing.
indexError(t oI, const String &str, Category c=BOUNDARY)
indexError(t oI, const Char *str, Category c=BOUNDARY)
This constructor takes the error message and the index which cause the error to occur.
const Double c
Fundamental physical constants (SI units):
this file contains all the compiler specific defines
Definition: mainpage.dox:28
unsigned int uInt
Definition: aipstype.h:51
int Int
Definition: aipstype.h:50
bool Bool
Define the standard types used by Casacore.
Definition: aipstype.h:42
char Char
Definition: aipstype.h:46