Loading...
Searching...
No Matches
Assert.h
Go to the documentation of this file.
//# Assert.h: Throw exceptions when Assertions fail.
//# Copyright (C) 1993,1994,1995,1999,2000,2002
//# Associated Universities, Inc. Washington DC, USA.
//#
//# This library is free software; you can redistribute it and/or modify it
//# under the terms of the GNU Library General Public License as published by
//# the Free Software Foundation; either version 2 of the License, or (at your
//# option) any later version.
//#
//# This library is distributed in the hope that it will be useful, but WITHOUT
//# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
//# FITNESS FOR A PARTICULAR PURPOSE. See the GNU Library General Public
//# License for more details.
//#
//# You should have received a copy of the GNU Library General Public License
//# along with this library; if not, write to the Free Software Foundation,
//# Inc., 675 Massachusetts Ave, Cambridge, MA 02139, USA.
//#
//# Correspondence concerning AIPS++ should be addressed as follows:
//# Internet email: casa-feedback@nrao.edu.
//# Postal address: AIPS++ Project Office
//# National Radio Astronomy Observatory
//# 520 Edgemont Road
//# Charlottesville, VA 22903-2475 USA
#ifndef CASA_ASSERT_H
#define CASA_ASSERT_H
#include <casacore/casa/aips.h>
#include <casacore/casa/Exceptions/Error.h>
namespace casacore { //# NAMESPACE CASACORE - BEGIN
// <summary>Utility class for Assert macros.</summary>
// <use visibility=export>
// <reviewed reviewer="Friso Olnon" date="1995/03/13" tests="" demos="">
// </reviewed>
// <prerequisite>
// <li> module <linkto module=Exceptions>Exceptions</linkto>
// </prerequisite>
// <etymology>
// Templated class <src>assert_</src> is the basis for the macros
// <src>DebugAssertExit</src>, <src>DebugAssert</src>,
// <src>AlwaysAssertExit</src>, and <src>AlwaysAssert</src> which
// form the "public interface" to the Assertion mechanism.
// </etymology>
// <synopsis>
// The present Assertion mechanism uses the exception
// handling mechanism to throw the errors when an Assertion
// fails. It can be used in two ways:
// <dl>
// <dt> <src>DebugAssertExit(expr)</src>
// <dt> <src>AlwaysAssertExit(expr)</src>
// <dd> cause the program to abort if <src>expr</src> evaluates to a
// null value. This form is intended for the <em>end users</em>
// because presumabily at their level there is no way to recover
// from errors.
// <dt> <src>DebugAssert(expr, exception)</src>
// <dt> <src>AlwaysAssert(expr, exception)</src>
// <dd> throw the specified exception if the <src>expr</src> is
// null. This form is designed to be used by <em>library
// elements</em> because it actually raises an exception which
// can be later caught in the regular way.
// </dl>
//
// <note role=tip> <src>DebugAssertExit</src> and
// <src>DebugAssert</src> are only invoked in
// debug mode (i.e. when <src>AIPS_DEBUG</src> is defined); otherwise
// they preprocess to null statements. <src>AlwaysAssertExit</src>
// and <src>AlwaysAssert</src> are always invoked.
// </note>
//
// <note role=tip> Class <src>assert_</src> is internal to the
// Assertion mechanism and should be undocumented. However,
// documenting the class is the only way to document this mechanism,
// which for the rest consists of preprocessor macros.
// </note>
//
// </synopsis>
// <example>
// The implementation of the <linkto module=Arrays>Array classes</linkto>
// contains many examples of the Assertion mechanism. The following
// application of the Assertion mechanism is taken from the archive of
// the aips2-workers@nrao.edu mail group (Brian Glendenning, 1994/03/23):
//
// I thought I'd readvertise a technique I use that helps me find
// problems in the classes I write. I have found this to be an
// EXTREMELY useful way of discovering bugs automatically (so the users
// of your class don't have to manually).
//
// In your class, write an <src>ok()</src> member function that
// returns a <src>Bool</src>. Allow for inheritance and make it a
// virtual function (in fact, the derived class's <src>ok()</src> would
// probably call the <src>ok()</src> from its parent, as well as doing
// specific stuff for the derived class).
//
// Then in every member function, place a call to <src>ok()</src> in
// an Assertion. Like this:
// <srcblock>
// DebugAssert(ok(), AipsError); // include aips/Assert.h in your .cc file
// </srcblock>
//
// The second argument is the exception you want to throw.
// <src>AipsError</src> will always do, although you can throw a
// more particular one if you want to. This Assertion will not be in
// production code -- i.e. if <src>AIPS_DEBUG</src> is not defined, the
// above line will be a null statement. I place these lines at the entry
// to all member functions (except I place them at the <em>end</em> of a
// constructor!). (I normally don't put an Assertion in an inline
// function).
//
// In the <src>ok()</src> function you should Assert a class's
// invariants. This is more or less the same as Asserting that an
// object's private and protected data are <em>consistent</em>. For
// example, one of the simple tests I do in the array classes is Assert
// that the number of elements (which I cache) is indeed equal to the
// product of its shape (I do ~15 tests in the <src>ok()</src> for the
// new <src>Array<T></src> class).
// </example>
template<class t> class assert_ {
public:
// <group>
assert_(int expr, const char *msg) {
if (! expr) throw(t(msg));
}
assert_(const void *ptr, const char *msg) {
if (! ptr) throw(t(msg));
}
assert_(int expr, const char *msg, const char* file, Int line);
assert_(const void *ptr, const char *msg, const char* file, Int line);
// </group>
// A no-op, but it keeps g++ from complaining about "variable not used"
// errors
void null() {}
};
// These marcos are provided for use instead of simply using the
// constructors of <src>assert_</src> to allow addition of line
// numbers and file name in the future.
//
// <src>DebugAssert</src> and <src>AlwaysAssert</src> are designed to
// be used by library elements because they actually raise an exception
// which can later be later caught.
// <src>DebugAssertExit</src> and <src>AlwaysAssertExit</src> are
// intended to be used by the applications writer, because they cause an
// <src>exit(0)</src>.
#define AlwaysAssert(expr, exception) \
{casacore::assert_<exception > dummy_(expr, "Failed AlwaysAssert " #expr,__FILE__,(casacore::Int)__LINE__); dummy_.null(); }
#define AlwaysAssertExit(expr) \
{casacore::assert_<casacore::AbortError> dummy_(expr, "Unrecoverable AlwaysAssertExit: " #expr,__FILE__,(casacore::Int)__LINE__); dummy_.null();}
#if defined(AIPS_DEBUG)
//# The backslashes below have spaces after them to make the egcs
// compiler happy # (otherwise it thinks they are multiline //
// comments). If ever uncommented # the spaces should be removed.
// #define DebugAssert(expr, exception)
// (assert_<exception > (expr, "Failed Assertion: " #expr))
// #define Assert(expr)
// (assert_<AbortError> (expr, "Unrecoverable Assertion: " #expr))
// #define DebugAssert(expr, exception)
// (assert_<exception > (expr, "Failed Assertion: " #expr,__FILE__,(Int)__LINE__))
// #define Assert(expr)
// (assert_<AbortError> (expr, "Unrecoverable Assertion: " #expr,__FILE__,(Int)__LINE__))
#define DebugAssert(expr, exception) \
{casacore::assert_<exception > dummy_(expr, "Failed Assertion: " #expr,__FILE__,(casacore::Int)__LINE__); dummy_.null();}
#define DebugAssertExit(expr) \
{casacore::assert_<casacore::AbortError> dummy_(expr, "Unrecoverable Assertion: " #expr,__FILE__,(casacore::Int)__LINE__); dummy_.null();}
#else
#define DebugAssert(expr, exception)
#define DebugAssertExit(expr)
#endif
} //# NAMESPACE CASACORE - END
#ifndef CASACORE_NO_AUTO_TEMPLATES
#include <casacore/casa/Utilities/Assert.tcc>
#endif //# CASACORE_NO_AUTO_TEMPLATES
#endif
casacore::assert_::null
void null()
A no-op, but it keeps g++ from complaining about "variable not used" errors.
Definition Assert.h:141
casacore::assert_::assert_
assert_(const void *ptr, const char *msg)
Definition Assert.h:132
casacore::assert_::assert_
assert_(int expr, const char *msg)
Definition Assert.h:129
casacore::assert_::assert_
assert_(int expr, const char *msg, const char *file, Int line)
casacore::assert_::assert_
assert_(const void *ptr, const char *msg, const char *file, Int line)
casacore
this file contains all the compiler specific defines
Definition mainpage.dox:28
casacore::Int
int Int
Definition aipstype.h:48