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