casacore
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
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>
34 #include <exception>
35 #include <sys/types.h>
36 
37 
38 namespace 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 
134 class AipsError: public std::exception
135 {
136 public:
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); }
150  String getStackTrace() const;
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);
163  AipsError (const String &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>
176  static void getLastInfo (String & message, String & stackTrace);
177  static String getLastMessage ();
178  static String getLastStackTrace ();
179  static void clearLastInfo ();
180  // </group>
181 
182  // Repackage an exception.
183  static AipsError repackageAipsError (AipsError& error,
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 
199 protected:
200  // Add the stack trace to the message (if USE_STACKTRACE is set).
201  void addStackTrace ();
202 
203  String message;
205  String stackTrace;
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 
232 class AllocError : public AipsError {
233 protected:
234  size_t Size;
235 public:
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 
280 class IndexError : public AipsError {
281 public:
282  //
283  // Creates an GeneralIndexError and initializes the error message from
284  // the parameter
285  // <group>
286  IndexError(const Char *str,Category c=BOUNDARY) : AipsError(str,c) {}
287  IndexError(const String &str,Category c=BOUNDARY) : AipsError(str,c) {}
288  IndexError(Category c=BOUNDARY) : AipsError(c) {}
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 
319 template<class t> class indexError : public IndexError {
320 protected:
321  t oIndex; // Offending Index
322 public:
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 
362 class DuplError : public AipsError {
363 public:
364  //
365  // Creates an DuplError and initializes the error message from
366  // the parameter
367  // <group>
368  DuplError(Category c=BOUNDARY) : AipsError(c) {}
369  DuplError(const Char *str,Category c=BOUNDARY) : AipsError(str,c) {}
370  DuplError(const String &str,Category c=BOUNDARY) : AipsError(str,c) {}
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 
402 template<class t> class duplError : public DuplError {
403 protected:
404  t oKey; // Offending Key
405 public:
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 
434 class SystemCallError : public AipsError
435 {
436 public:
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.
445  ~SystemCallError() noexcept;
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 
454 private:
455  int itsError;
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 
479 class AbortError : public AipsError {
480 public:
481  //
482  // This constructs a "AbortError" from the error message.
483  //
484  // <group>
485  AbortError(const Char *str,Category c=GENERAL);
486  AbortError(const String &str,Category c=GENERAL);
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 
511 class 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
int Int
Definition: aipstype.h:50
DuplError(const String &str, Category c=BOUNDARY)
Definition: Error.h:370
String getStackTrace() const
AipsError(const Char *str, Category c=GENERAL)
Creates an AipsError and initializes the error message from the parameter.
int error() const
Get the errno.
Definition: Error.h:448
DuplError(const Char *str, Category c=BOUNDARY)
Definition: Error.h:369
static void throwIf(Bool condition, const String &message, const char *file, Int line, const char *func="")
Throw if the condition is true.
DuplError(Category c=BOUNDARY)
Creates an DuplError and initializes the error message from the parameter.
Definition: Error.h:368
void setMessage(const String &msg) const
Append a message.
Definition: Error.h:156
IndexError(Category c=BOUNDARY)
Definition: Error.h:288
char Char
Definition: aipstype.h:46
Initialization error, typically of static data shared between objects.
Definition: Error.h:511
AllocError(const Char *str, uInt sze)
This constructor takes the error message and the failed allocation size.
Definition: Error.h:241
indexError(t oI, Category c=BOUNDARY)
Definition: Error.h:330
Index errors returning the bad index.
Definition: Error.h:319
const String & getMesg() const
Definition: Error.h:148
AllocError(const String &str, uInt sze)
Definition: Error.h:242
static String getLastMessage()
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.
static void getLastInfo(String &message, String &stackTrace)
Get or clear the stacktrace info.
duplError(t oI, Category c=BOUNDARY)
Definition: Error.h:413
Allocation errors.
Definition: Error.h:232
IndexError(const Char *str, Category c=BOUNDARY)
Creates an GeneralIndexError and initializes the error message from the parameter.
Definition: Error.h:286
Base class for all indexing errors.
Definition: Error.h:280
void addStackTrace()
Add the stack trace to the message (if USE_STACKTRACE is set).
const Char * c_str() const
Get char array.
Definition: String.h:557
AipsError::Category getCategory() const
Definition: Error.h:151
bool Bool
Define the standard types used by Casacore.
Definition: aipstype.h:42
static String getLastStackTrace()
virtual const char * what() const noexcept
Simply returns the stored error message.
Definition: Error.h:146
Exception which halts execution.
Definition: Error.h:479
Category category
Definition: Error.h:204
~AipsError() noexcept
Destructor which does nothing.
size_t size() const
This function returns the failed allocation size.
Definition: Error.h:248
String message
Definition: Error.h:203
IndexError(const String &str, Category c=BOUNDARY)
Definition: Error.h:287
Base class for all Casacore library errors.
Definition: Error.h:134
static void clearLastInfo()
const Double c
Fundamental physical constants (SI units):
Duplicate key errors.
Definition: Error.h:362
String: the storage and methods of handling collections of characters.
Definition: String.h:225
Duplicate key errors where the bad key is returned.
Definition: Error.h:402
String stackTrace
Definition: Error.h:205
static AipsError repackageAipsError(AipsError &error, const String &message, const char *file, Int line, const char *func)
Repackage an exception.
Exception for an error in a system call.
Definition: Error.h:434
unsigned int uInt
Definition: aipstype.h:51