casacore
Loading...
Searching...
No Matches
Assert.h
Go to the documentation of this file.
1//# Assert.h: Throw exceptions when Assertions fail.
2//# Copyright (C) 1993,1994,1995,1999,2000,2002
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: casa-feedback@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#ifndef CASA_ASSERT_H
27#define CASA_ASSERT_H
28
29#include <casacore/casa/aips.h>
30#include <casacore/casa/Exceptions/Error.h>
31
32
33namespace casacore { //# NAMESPACE CASACORE - BEGIN
34
35// <summary>Utility class for Assert macros.</summary>
36// <use visibility=export>
37// <reviewed reviewer="Friso Olnon" date="1995/03/13" tests="" demos="">
38// </reviewed>
39
40// <prerequisite>
41// <li> module <linkto module=Exceptions>Exceptions</linkto>
42// </prerequisite>
43
44// <etymology>
45// Templated class <src>assert_</src> is the basis for the macros
46// <src>DebugAssertExit</src>, <src>DebugAssert</src>,
47// <src>AlwaysAssertExit</src>, and <src>AlwaysAssert</src> which
48// form the "public interface" to the Assertion mechanism.
49// </etymology>
50
51// <synopsis>
52// The present Assertion mechanism uses the exception
53// handling mechanism to throw the errors when an Assertion
54// fails. It can be used in two ways:
55// <dl>
56// <dt> <src>DebugAssertExit(expr)</src>
57// <dt> <src>AlwaysAssertExit(expr)</src>
58// <dd> cause the program to abort if <src>expr</src> evaluates to a
59// null value. This form is intended for the <em>end users</em>
60// because presumabily at their level there is no way to recover
61// from errors.
62// <dt> <src>DebugAssert(expr, exception)</src>
63// <dt> <src>AlwaysAssert(expr, exception)</src>
64// <dd> throw the specified exception if the <src>expr</src> is
65// null. This form is designed to be used by <em>library
66// elements</em> because it actually raises an exception which
67// can be later caught in the regular way.
68// </dl>
69//
70// <note role=tip> <src>DebugAssertExit</src> and
71// <src>DebugAssert</src> are only invoked in
72// debug mode (i.e. when <src>AIPS_DEBUG</src> is defined); otherwise
73// they preprocess to null statements. <src>AlwaysAssertExit</src>
74// and <src>AlwaysAssert</src> are always invoked.
75// </note>
76//
77// <note role=tip> Class <src>assert_</src> is internal to the
78// Assertion mechanism and should be undocumented. However,
79// documenting the class is the only way to document this mechanism,
80// which for the rest consists of preprocessor macros.
81// </note>
82//
83// </synopsis>
84
85// <example>
86// The implementation of the <linkto module=Arrays>Array classes</linkto>
87// contains many examples of the Assertion mechanism. The following
88// application of the Assertion mechanism is taken from the archive of
89// the aips2-workers@nrao.edu mail group (Brian Glendenning, 1994/03/23):
90//
91// I thought I'd readvertise a technique I use that helps me find
92// problems in the classes I write. I have found this to be an
93// EXTREMELY useful way of discovering bugs automatically (so the users
94// of your class don't have to manually).
95//
96// In your class, write an <src>ok()</src> member function that
97// returns a <src>Bool</src>. Allow for inheritance and make it a
98// virtual function (in fact, the derived class's <src>ok()</src> would
99// probably call the <src>ok()</src> from its parent, as well as doing
100// specific stuff for the derived class).
101//
102// Then in every member function, place a call to <src>ok()</src> in
103// an Assertion. Like this:
104// <srcblock>
105// DebugAssert(ok(), AipsError); // include aips/Assert.h in your .cc file
106// </srcblock>
107//
108// The second argument is the exception you want to throw.
109// <src>AipsError</src> will always do, although you can throw a
110// more particular one if you want to. This Assertion will not be in
111// production code -- i.e. if <src>AIPS_DEBUG</src> is not defined, the
112// above line will be a null statement. I place these lines at the entry
113// to all member functions (except I place them at the <em>end</em> of a
114// constructor!). (I normally don't put an Assertion in an inline
115// function).
116//
117// In the <src>ok()</src> function you should Assert a class's
118// invariants. This is more or less the same as Asserting that an
119// object's private and protected data are <em>consistent</em>. For
120// example, one of the simple tests I do in the array classes is Assert
121// that the number of elements (which I cache) is indeed equal to the
122// product of its shape (I do ~15 tests in the <src>ok()</src> for the
123// new <src>Array<T></src> class).
124// </example>
125
126template<class t> class assert_ {
127public:
128 // <group>
129 assert_(int expr, const char *msg) {
130 if (! expr) throw(t(msg));
131 }
132 assert_(const void *ptr, const char *msg) {
133 if (! ptr) throw(t(msg));
134 }
135 assert_(int expr, const char *msg, const char* file, Int line);
136 assert_(const void *ptr, const char *msg, const char* file, Int line);
137 // </group>
138
139 // A no-op, but it keeps g++ from complaining about "variable not used"
140 // errors
141 void null() {}
142};
143
144// These marcos are provided for use instead of simply using the
145// constructors of <src>assert_</src> to allow addition of line
146// numbers and file name in the future.
147//
148// <src>DebugAssert</src> and <src>AlwaysAssert</src> are designed to
149// be used by library elements because they actually raise an exception
150// which can later be later caught.
151// <src>DebugAssertExit</src> and <src>AlwaysAssertExit</src> are
152// intended to be used by the applications writer, because they cause an
153// <src>exit(0)</src>.
154
155#define AlwaysAssert(expr, exception) \
156 {casacore::assert_<exception > dummy_(expr, "Failed AlwaysAssert " #expr,__FILE__,(casacore::Int)__LINE__); dummy_.null(); }
157#define AlwaysAssertExit(expr) \
158 {casacore::assert_<casacore::AbortError> dummy_(expr, "Unrecoverable AlwaysAssertExit: " #expr,__FILE__,(casacore::Int)__LINE__); dummy_.null();}
159
160#if defined(AIPS_DEBUG)
161
162//# The backslashes below have spaces after them to make the egcs
163// compiler happy # (otherwise it thinks they are multiline //
164// comments). If ever uncommented # the spaces should be removed.
165
166// #define DebugAssert(expr, exception)
167// (assert_<exception > (expr, "Failed Assertion: " #expr))
168// #define Assert(expr)
169// (assert_<AbortError> (expr, "Unrecoverable Assertion: " #expr))
170
171// #define DebugAssert(expr, exception)
172// (assert_<exception > (expr, "Failed Assertion: " #expr,__FILE__,(Int)__LINE__))
173// #define Assert(expr)
174// (assert_<AbortError> (expr, "Unrecoverable Assertion: " #expr,__FILE__,(Int)__LINE__))
175
176#define DebugAssert(expr, exception) \
177 {casacore::assert_<exception > dummy_(expr, "Failed Assertion: " #expr,__FILE__,(casacore::Int)__LINE__); dummy_.null();}
178#define DebugAssertExit(expr) \
179 {casacore::assert_<casacore::AbortError> dummy_(expr, "Unrecoverable Assertion: " #expr,__FILE__,(casacore::Int)__LINE__); dummy_.null();}
180
181#else
182
183#define DebugAssert(expr, exception)
184#define DebugAssertExit(expr)
185
186#endif
187
188
189} //# NAMESPACE CASACORE - END
190
191#ifndef CASACORE_NO_AUTO_TEMPLATES
192#include <casacore/casa/Utilities/Assert.tcc>
193#endif //# CASACORE_NO_AUTO_TEMPLATES
194#endif
void null()
A no-op, but it keeps g++ from complaining about "variable not used" errors.
Definition Assert.h:141
assert_(const void *ptr, const char *msg)
Definition Assert.h:132
assert_(int expr, const char *msg)
Definition Assert.h:129
assert_(int expr, const char *msg, const char *file, Int line)
assert_(const void *ptr, const char *msg, const char *file, Int line)
this file contains all the compiler specific defines
Definition mainpage.dox:28
int Int
Definition aipstype.h:48