Exceptions and assertions

Classes

class  ExceptionBase
class  StandardExceptions::ExcDivideByZero
class  StandardExceptions::ExcOutOfMemory
class  StandardExceptions::ExcMemoryLeak
class  StandardExceptions::ExcIO
class  StandardExceptions::ExcFileNotOpen
class  StandardExceptions::ExcNotImplemented
class  StandardExceptions::ExcInternalError
class  StandardExceptions::ExcPureFunctionCalled
class  StandardExceptions::ExcInvalidConstructorCall
class  StandardExceptions::ExcNotInitialized
class  StandardExceptions::ExcInvalidState
class  StandardExceptions::ExcImpossibleInDim
class  StandardExceptions::ExcZero
class  StandardExceptions::ExcEmptyObject
class  StandardExceptions::ExcDimensionMismatch
class  StandardExceptions::ExcDimensionMismatch2
class  StandardExceptions::ExcIndexRange
class  StandardExceptions::ExcLowerRange
class  StandardExceptions::ExcNotMultiple
class  StandardExceptions::ExcIteratorPastEnd
class  StandardExceptions::ExcMessage
class  StandardExceptions::ExcCompatibility
class  StandardExceptions::ExcScalarAssignmentOnlyForZeroValue
class  StandardExceptions::ExcNeedsBLAS
class  StandardExceptions::ExcNeedsLAPACK
class  StandardExceptions::ExcNeedsUMFPACK
class  StandardExceptions::ExcNeedsMETIS
class  StandardExceptions::ExcNeedsPETSC
class  StandardExceptions::ExcNeedsNetCDF
class  StandardExceptions::ExcDisabled
class  Function< dim >::ExcNumberOfComponents
class  FunctionDerivative< dim >::ExcInvalidFormula
class  FunctionParser< dim >::ExcParseError
class  FunctionParser< dim >::ExcInvalidExpressionSize
class  Patterns::List::ExcInvalidRange
class  Patterns::MultipleSelection::ExcCommasNotAllowed
class  ParameterHandler::ExcEntryAlreadyExists
class  ParameterHandler::ExcDefaultDoesNotMatchPattern
class  ParameterHandler::ExcAlreadyAtTopLevel
class  ParameterHandler::ExcEntryUndeclared
class  ParameterHandler::ExcConversionError
class  PathSearch::ExcNoClass
class  PathSearch::ExcFileNotFound
class  QuadratureSelector< dim >::ExcInvalidQGaussOrder
class  QuadratureSelector< dim >::ExcInvalidOrder
class  QuadratureSelector< dim >::ExcInvalidQuadrature
class  Subscriptor::ExcInUse
class  Subscriptor::ExcNoSubscriber
class  Subscriptor::ExcNotUsed
class  TableHandler::ExcColumnNotExistent
class  TableHandler::ExcSuperColumnNotExistent
class  TableHandler::ExcColumnOrSuperColumnNotExistent
class  TableHandler::ExcWrongNumberOfDataEntries
class  TableHandler::ExcUndefinedTexFormat
class  Tensor< 1, dim >::ExcDimTooSmall
class  Threads::DummyBarrier::ExcBarrierSizeNotUseful
class  Threads::Thread< RT >::ExcNoThread
class  BlockTrianglePrecondition< number >::ExcNoDiagonal
class  BlockTrianglePrecondition< number >::ExcMultipleDiagonal
class  BlockMatrixBase< MatrixType >::ExcIncompatibleRowNumbers
class  BlockMatrixBase< MatrixType >::ExcIncompatibleColNumbers
class  BlockSparseMatrix< number >::ExcBlockDimensionMismatch
class  BlockSparsityPatternBase< SparsityPatternBase >::ExcIncompatibleRowNumbers
class  BlockSparsityPatternBase< SparsityPatternBase >::ExcIncompatibleColNumbers
class  BlockSparsityPatternBase< SparsityPatternBase >::ExcIncompatibleSizes
class  BlockSparsityPatternBase< SparsityPatternBase >::ExcInvalidConstructorCall
class  BlockVector< Number >::ExcIteratorRangeDoesNotMatchVectorSize
class  internal::BlockVectorIterators::Iterator< BlockVectorType, constness >::ExcPointerToDifferentVectors
class  internal::BlockVectorIterators::Iterator< BlockVectorType, constness >::ExcCastingAwayConstness
class  ChunkSparseMatrix< number >::ExcInvalidIndex
class  ChunkSparseMatrix< number >::ExcInvalidIndex1
class  ChunkSparseMatrix< number >::ExcDifferentChunkSparsityPatterns
class  ChunkSparseMatrix< number >::ExcIteratorRange
class  ChunkSparseMatrix< number >::ExcSourceEqualsDestination
class  ChunkSparsityPattern::ExcInvalidNumber
class  ChunkSparsityPattern::ExcInvalidIndex
class  ChunkSparsityPattern::ExcNotEnoughSpace
class  ChunkSparsityPattern::ExcNotCompressed
class  ChunkSparsityPattern::ExcMatrixIsCompressed
class  ChunkSparsityPattern::ExcEmptyObject
class  ChunkSparsityPattern::ExcInvalidConstructorCall
class  ChunkSparsityPattern::ExcDiagonalNotOptimized
class  ChunkSparsityPattern::ExcIteratorRange
class  ChunkSparsityPattern::ExcMETISNotInstalled
class  ChunkSparsityPattern::ExcInvalidNumberOfPartitions
class  ChunkSparsityPattern::ExcInvalidArraySize
class  ConstraintMatrix::ExcMatrixIsClosed
class  ConstraintMatrix::ExcMatrixNotClosed
class  ConstraintMatrix::ExcLineInexistant
class  ConstraintMatrix::ExcEntryAlreadyExists
class  ConstraintMatrix::ExcDoFConstrainedToConstrainedDoF
class  ConstraintMatrix::ExcDoFIsConstrainedFromBothObjects
class  ConstraintMatrix::ExcDoFIsConstrainedToConstrainedDoF
class  LACExceptions::ExcNotQuadratic
class  LACExceptions::ExcSingular
class  LACExceptions::ExcDifferentBlockIndices
class  LACExceptions::ExcPETScError
class  LACExceptions::ExcTrilinosError
class  FullMatrix< number >::ExcEmptyMatrix
class  FullMatrix< number >::ExcNotRegular
class  FullMatrix< number >::ExcInvalidDestination
class  FullMatrix< number >::ExcSourceEqualsDestination
class  PETScWrappers::BlockSparseMatrix::ExcIncompatibleRowNumbers
class  PETScWrappers::BlockSparseMatrix::ExcIncompatibleColNumbers
class  PETScWrappers::BlockVector::ExcIteratorRangeDoesNotMatchVectorSize
class  PETScWrappers::MPI::SparseMatrix::ExcLocalRowsTooLarge
class  PreconditionBlock< MATRIX, inverse_type >::ExcWrongBlockSize
class  PreconditionBlock< MATRIX, inverse_type >::ExcWrongNumberOfInverses
class  PreconditionBlock< MATRIX, inverse_type >::ExcInverseMatricesAlreadyExist
class  PreconditionBlock< MATRIX, inverse_type >::ExcDiagonalsNotStored
class  PreconditionSelector< Matrix, Vector >::ExcNoMatrixGivenToUse
class  SolverMinRes< VECTOR >::ExcPreconditionerNotDefinite
class  SparseLUDecomposition< number >::ExcInvalidStrengthening
class  SparseDirectMA27::ExcMA27AFailed
class  SparseDirectMA27::ExcMA27BFailed
class  SparseDirectMA27::ExcMA27CFailed
class  SparseDirectMA27::ExcInitializeAlreadyCalled
class  SparseDirectMA27::ExcFactorizeNotCalled
class  SparseDirectMA27::ExcDifferentSparsityPatterns
class  SparseDirectMA27::ExcReadError
class  SparseDirectMA27::ExcMatrixNotSymmetric
class  SparseDirectMA47::ExcMA47AFailed
class  SparseDirectMA47::ExcMA47BFailed
class  SparseDirectMA47::ExcMA47CFailed
class  SparseDirectMA47::ExcInitializeAlreadyCalled
class  SparseDirectMA47::ExcFactorizeNotCalled
class  SparseDirectMA47::ExcCantFactorizeAgain
class  SparseDirectMA47::ExcDifferentMatrices
class  SparseDirectMA47::ExcMatrixNotSymmetric
class  SparseILU< number >::ExcInvalidStrengthening
class  SparseMatrix< number >::ExcInvalidIndex
class  SparseMatrix< number >::ExcInvalidIndex1
class  SparseMatrix< number >::ExcDifferentSparsityPatterns
class  SparseMatrix< number >::ExcIteratorRange
class  SparseMatrix< number >::ExcSourceEqualsDestination
class  SparseMatrixEZ< number >::ExcNoDiagonal
class  SparseMatrixEZ< number >::ExcInvalidEntry
class  SparseMatrixEZ< number >::ExcEntryAllocationFailure
class  SparseMIC< number >::ExcStrengthenDiagonalTooSmall
class  SparseMIC< number >::ExcInvalidStrengthening
class  SparseMIC< number >::ExcDecompositionNotStable
class  internals::SparsityPatternIterators::Accessor::ExcInvalidIterator
class  SparsityPattern::ExcInvalidNumber
class  SparsityPattern::ExcInvalidIndex
class  SparsityPattern::ExcNotEnoughSpace
class  SparsityPattern::ExcNotCompressed
class  SparsityPattern::ExcMatrixIsCompressed
class  SparsityPattern::ExcEmptyObject
class  SparsityPattern::ExcInvalidConstructorCall
class  SparsityPattern::ExcDiagonalNotOptimized
class  SparsityPattern::ExcIteratorRange
class  SparsityPattern::ExcInvalidNumberOfPartitions
class  SparsityPattern::ExcInvalidArraySize
class  SwappableVector< number >::ExcSizeZero
class  SwappableVector< number >::ExcSizeNonzero
class  SwappableVector< number >::ExcInvalidFilename
class  SwappableVector< number >::ExcInvalidCopyOperation
class  TrilinosWrappers::BlockSparseMatrix::ExcIncompatibleRowNumbers
class  TrilinosWrappers::BlockSparseMatrix::ExcIncompatibleColNumbers
class  TrilinosWrappers::SparseMatrix::ExcTrilinosError
class  TrilinosWrappers::SparseMatrix::ExcInvalidIndex
class  TrilinosWrappers::SparseMatrix::ExcSourceEqualsDestination
class  TrilinosWrappers::SparseMatrix::ExcAccessToNonLocalElement
class  TrilinosWrappers::SparseMatrix::ExcAccessToNonPresentElement
class  TrilinosWrappers::SparsityPattern::ExcTrilinosError
class  TrilinosWrappers::SparsityPattern::ExcInvalidIndex
class  TrilinosWrappers::SparsityPattern::ExcSourceEqualsDestination
class  TrilinosWrappers::SparsityPattern::ExcAccessToNonLocalElement
class  TrilinosWrappers::SparsityPattern::ExcAccessToNonPresentElement
class  VectorMemory< VECTOR >::ExcNoMoreVectors
class  VectorMemory< VECTOR >::ExcNotAllocatedHere
class  DoFAccessor< structdim, DH >::ExcInvalidObject
class  DoFAccessor< structdim, DH >::ExcVectorNotEmpty
class  DoFAccessor< structdim, DH >::ExcVectorDoesNotMatch
class  DoFAccessor< structdim, DH >::ExcMatrixDoesNotMatch
class  DoFAccessor< structdim, DH >::ExcNotActive
class  DoFAccessor< structdim, DH >::ExcCantCompareIterators
class  DoFRenumbering::ExcRenumberingIncomplete
class  DoFRenumbering::ExcInvalidComponentOrder
class  DoFRenumbering::ExcNotDGFEM
class  FiniteElement< dim, spacedim >::ExcShapeFunctionNotPrimitive
class  FiniteElement< dim, spacedim >::ExcFENotPrimitive
class  FiniteElement< dim, spacedim >::ExcUnitShapeValuesDoNotExist
class  FiniteElement< dim, spacedim >::ExcFEHasNoSupportPoints
class  FiniteElement< dim, spacedim >::ExcEmbeddingVoid
class  FiniteElement< dim, spacedim >::ExcProjectionVoid
class  FiniteElement< dim, spacedim >::ExcConstraintsVoid
class  FiniteElement< dim, spacedim >::ExcWrongInterfaceMatrixSize
class  FiniteElement< dim, spacedim >::ExcComponentIndexInvalid
class  FiniteElement< dim, spacedim >::ExcInterpolationNotImplemented
class  FiniteElement< dim, spacedim >::ExcBoundaryFaceUsed
class  FiniteElement< dim, spacedim >::ExcJacobiDeterminantHasWrongSign
class  FETools::ExcInvalidFEName
class  FETools::ExcInvalidFEDimension
class  FETools::ExcInvalidFE
class  FETools::ExcFENotPrimitive
class  FETools::ExcTriangulationMismatch
class  FETools::ExcHangingNodesNotAllowed
class  FETools::ExcGridNotRefinedAtLeastOnce
class  FETools::ExcMatrixDimensionMismatch
class  FETools::ExcLeastSquaresError
class  FEValuesBase< dim, spacedim >::ExcAccessToUninitializedField
class  FEValuesBase< dim, spacedim >::ExcCannotInitializeField
class  FEValuesBase< dim, spacedim >::ExcInvalidUpdateFlag
class  FEValuesBase< dim, spacedim >::ExcFEDontMatch
class  FEValuesBase< dim, spacedim >::ExcShapeFunctionNotPrimitive
class  FEValuesBase< dim, spacedim >::ExcFENotPrimitive
class  FESubfaceValues< dim, spacedim >::ExcReinitCalledWithBoundaryFace
class  FESubfaceValues< dim, spacedim >::ExcFaceHasNoSubfaces
class  Triangulation< dim, spacedim >::ExcInvalidLevel
class  Triangulation< dim, spacedim >::ExcTriangulationNotEmpty
class  Triangulation< dim, spacedim >::ExcGridReadError
class  Triangulation< dim, spacedim >::ExcFacesHaveNoLevel
class  Triangulation< dim, spacedim >::ExcEmptyLevel
class  TriaAccessorExceptions::ExcCellNotUsed
class  TriaAccessorExceptions::ExcCellNotActive
class  TriaAccessorExceptions::ExcInvalidNeighbor
class  TriaAccessorExceptions::ExcCellHasNoChildren
class  TriaAccessorExceptions::ExcUnusedCellAsChild
class  TriaAccessorExceptions::ExcCantSetChildren
class  TriaAccessorExceptions::ExcUnusedCellAsNeighbor
class  TriaAccessorExceptions::ExcUncaughtCase
class  TriaAccessorExceptions::ExcDereferenceInvalidObject
class  TriaAccessorExceptions::ExcCantCompareIterators
class  TriaAccessorExceptions::ExcNeighborIsCoarser
class  TriaAccessorExceptions::ExcNeighborIsNotCoarser
class  TriaAccessorExceptions::ExcFacesHaveNoLevel
class  TriaAccessorExceptions::ExcSetOnlyEvenChildren
class  CellAccessor< dim, spacedim >::ExcRefineCellNotActive
class  CellAccessor< dim, spacedim >::ExcCellFlaggedForRefinement
class  CellAccessor< dim, spacedim >::ExcCellFlaggedForCoarsening
class  internal::Triangulation::TriaObjects< G >::ExcMemoryInexact
class  internal::Triangulation::TriaObjects< G >::ExcPointerIndexClash

Namespaces

namespace  deal_II_exceptions
namespace  deal_II_exceptions::internals
namespace  StandardExceptions

Defines

#define Assert(cond, exc)
#define AssertThrow(cond, exc)
#define DeclException0(Exception0)   class Exception0 : public ::ExceptionBase {}
#define DeclException1(Exception1, type1, outsequence)
#define DeclException2(Exception2, type1, type2, outsequence)
#define DeclException3(Exception3, type1, type2, type3, outsequence)
#define DeclException4(Exception4, type1, type2, type3, type4, outsequence)
#define DeclException5(Exception5, type1, type2, type3, type4, type5, outsequence)
#define AssertDimension(dim1, dim2)
#define AssertIndexRange(index, range)

Functions

 ConvergenceTable::DeclException0 (ExcWrongValueType)
 ConvergenceTable::DeclException1 (ExcRateColumnAlreadyExists, std::string,<< "Rate column <"<< arg1<< "> does already exist.")
 DataOutBase::Patch::DeclException2 (ExcInvalidCombinationOfDimensions, int, int,<< "It is not possible to have a structural dimension of "<< arg1<< " to be larger than the space dimension of the surrounding"<< " space "<< arg2)
 DataOutBase::DeclException2 (ExcInvalidDatasetSize, int, int,<< "The number of points in this data set is "<< arg1<< ", but we expected "<< arg2<< " in each space direction.")
 DataOutBase::DeclException0 (ExcNoPatches)
 DataOutBase::DeclException0 (ExcTecplotAPIError)
 DataOutBase::DeclException1 (ExcErrorOpeningTecplotFile, char *,<< "There was an error opening Tecplot file "<< arg1<< " for output")

Detailed Description

This module contains classes that are used in the exception mechanism of deal.II.

Brief overview

Exceptions are used in two different ways:

Detailed description

The error handling mechanism in deal.II is generally used in two ways. The first uses error checking in debug mode only and is useful for programs which are not fully tested. When the program shows no errors anymore, one may switch off error handling and get better performance by this, since checks for errors are done quite frequently in the library (a typical speed up is a factor of four!). This mode of exception generation is most useful for internal consistency checks such as range checking or checking of the validity of function arguments. Errors of this kind usually are programming errors and the program should abort with as detailed a message as possible, including location and reason for the generation of the exception.

The second mode is for error checks which should always be on, such as for I/O errors, failing memory requests and the like. It does not make much sense to turn this mode off, since this kind of errors may happen in tested and untested programs likewise. Exceptions of this kind do not terminate the program, rather they throw exceptions in the C++ manner, allowing the program to catch them and eventually do something about it. As it may be useful to have some information printed out if an exception could not be handled properly, additional information is passed along as for the first mode. The latter makes it necessary to provide a family of macros which enter this additional information into the exception class; this could in principle be done by the programmer himself each time by hand, but since the information can be obtained automatically, a macro is provided for this.

Both modes use exception classes, which need to have special features in additional to the C++ standard's std::exception class. Such a class is declared by the following lines of code:

     DeclException2 (ExcDomain, int, int,
                     << "Index= " << arg1 << "Upper Bound= " << arg2);

This declares an exception class named ExcDomain, which has two variables as additional information (named arg1 and arg2 by default) and which outputs the given sequence (which is appended to an std::ostream variable's name, thus the weird syntax). There are other DeclExceptionN macros for exception classes with more or no parameters. By convention, the name of all exception classes starts with Exc... and most of them are declared locally to the class it is to be used in (a few very frequently found ones are also declared in the StandardExceptions namespace and are available everywhere). Declaring exceptions globally is possible but pollutes the global namespace, is less readable and most of the time unnecessary.

Since exception classes are declared the same way for both modes of error checking, it is possible to use an exception declared through the DeclExceptionN(...) macro family for both static as well as dynamic checks.

Use of the debug mode exceptions (static checks)

To use the exception mechanism for debug mode error checking, write lines like the following in your source code:

    Assert (n<dim, ExcDomain(n,dim));

which by macro expansion does essentially the following:

    #ifdef DEBUG
        if (!(cond))
              issue error of class ExcDomain(n,dim)
    #else
        do nothing
    #endif

i.e. it issues an error only if the preprocessor variable DEBUG is set and if the given condition (in this case n < dim is violated).

If the exception was declared using the DeclException0 (...) macro, i.e. without any additional parameters, its name has nonetheless to be given with parentheses: Assert (i>m, ExcSomewhat());

How it works internally

If the DEBUG preprocessor directive is set, the call Assert (cond, exc); is basically converted by the preprocessor into the following sequence:

    if (!(cond))
      deal_II_exceptions::internals::issue_error_assert_1
             (__FILE__,
              __LINE__,
              __PRETTY_FUNCTION__,
              #cond,
              #exc,
              &exc);

(Note that function names and exact calling sequences may change over time, but the general principle remains the same.) I.e., if the given condition is violated, then the file and line in which the exception occured as well as the condition itself and the call sequence of the exception object is passed to the deal_II_exceptions::internals::issue_error_assert_1() function. Additionally an object of the form given by exc is created (this is normally an unnamed object like in ExcDomain (n, dim) of class ExcDomain) and transferred to this function.

__PRETTY__FUNCTION__ is a macro defined by some compilers and gives the name of the function. If another compiler is used, we try to set this function to something reasonable, if the compiler provides us with that, and "(not available)" otherwise.

In issue_error_assert, the given data is transferred into the exc object by calling the set_fields() function; after that, the general error info is printed onto std::cerr using the PrintError() function of exc and finally the exception specific data is printed using the user defined function PrintError() (which is normally created using the DeclException (...) macro family. If it can be obtained from the operating system, the output may also contain a stacktrace to show where the error happened. Several of the Tutorial programs programs show a typical output.

After printing all this information, deal_II_exceptions::internals::abort() is called (with one exception, see the end of this section). This terminates the program, which is the right thing to do for this kind of error checking since it is used to detect programming errors rather than run-time errors; a program can, by definition, not recover from programming errors.

If the preprocessor variable DEBUG is not set, then nothing happens, i.e. the Assert macro is expanded to {}.

Sometimes, there is no useful condition for an exception other than that the program flow should not have reached a certain point, e.g. a default section of a switch statement. In this case, raise the exception by the following construct:

    Assert (false, ExcInternalError());

See the step-7 and several other of the tutorial programs for a use of this construct.

As mentioned above, the program is terminated once a call to Assert fails. However, there is one case where we do not want to do this, namely when a C++ exception is active. The usual case where this happens is that someone throws an exception through the AssertThrow mechanism (see below) which, while the stack is unwound, leads to the destruction of other objects in stack frames above. If other objects refer to the objects being thus destroyed, some destructors raise an exception through Assert. If we would abort the program then, we would only ever see the message that an object is being destroyed which is still referenced from somewhere, but we would never see the original exception that triggered this. (You can see it in the debugger by putting a break point on the function __throw, but you cannot see it from the program itself.) In that case, we use a C++ standard library function to detect the presence of another active exception and do not terminate the program to allow that the thrown exception propagates to some place where its message can be displayed.

Since it is common that one failed assertion leads to a whole chain of others, we only ever print the very first message. If the program is then aborted, that is no problem. If it is not (since a C++ exception is active), only the first is displayed and a message about suppressed follow-up messages is shown.

Use of run-time exceptions

For this mode, the standard C++ throw and catch concept exists. We want to keep to this, but want to extend it a bit. In general, the structure is the same, i.e. you normally raise and exception by

    if (!(cond))
      throw ExcSomething();

and catch it using the statement

    try {
      do_something ();
    }
    catch (exception &e) {
      std::cerr << "Exception occured:" << std::endl
           << e.what ()
           << std::endl;
      do_something_to_reciver ();
    };

exception is a standard C++ class providing basic functionality for exceptions, such as the virtual function what() which returns some information on the exception itself. This information is useful if an exception can't be handled properly, in which case as precise a description as possible should be printed.

The problem here is that to get significant and useful information out of what(), it is necessary to overload this function in out exception class and call the throw operator with additional arguments to the exception class. The first thing, overloading the what function is done using the DeclExceptionN macros, but putting the right information, which is the same as explained above for the Assert expansion, requires some work if one would want to write it down each time:

    if (!(cond))
      {
        ExcSomething e(additional information);
        e.set_fields (__FILE__, __LINE__, __PRETTY_FUNCTION__,
                      "condition as a string",
                      "name of condition as a string");
        throw e;
      };

For this purpose, the macro AssertThrow was invented. It does mainly the same job as does the Assert macro, but it does not kill the program, it rather throws an exception as shown above. The mode of usage is

    AssertThrow (cond, ExcSomething(additional information));

The condition to be checked is incorporated into the macro in order to allow passing the violated condition as a string. The expansion of the AssertThrow macro is not affected by the DEBUG preprocessor variable.

Description of the DeclExceptionN macro family

There is a whole family of DeclExceptionX macros where X is to be replaced by the number of additional parameters (0 to 5 presently). These macros are used to declare exception classes in the following way:

    DeclException2 (ExcDomain,
                    int,
                    int,
                    << " i=" << arg1 << ", m=" << arg2);

The first argument denotes the name of the exception class to be created. The next arguments are the types of the parameters (in this case there two types, corresponding to the X in DeclExceptionX) and finally the output sequence with which you can print additional information.

The syntax of the output sequence is a bit weird but gets clearer once you see how this macro is defined (again schematically, actual function names and definitions may change over time and be different):

  class name : public ExceptionBase {
    public:
      name (const type1 a1, const type2 a2) :
                     arg1 (a1), arg2(a2) {};
      virtual void print_info (std::ostream &out) const {
        out outsequence << std::endl;
      };
    private:
      type1 arg1;
      type2 arg2;
  };

If declared as specified, you can later use this exception class in the following manner:

    int i=5;
    int m=3;
    Assert (i<m, MyExc2(i,m));

and the output if the condition fails will be

    --------------------------------------------------------
    An error occurred in line <301> of file <exc-test.cc>.
    The violated condition was: 
      i<m
    The name and call sequence of the exception was:
      MyExc2(i,m)
    Additional Information: 
      i=5, m=3
    --------------------------------------------------------

Obviously for the DeclException0(name) macro, no types and also no output sequence is allowed.

Author:
Wolfgang Bangerth, 1998-2006

Define Documentation

#define Assert ( cond,
exc   ) 
Value:
{                                                                 \
    if (!(cond))                                                    \
      ::::deal_II_exceptions::internals::                           \
      issue_error_assert_1 (__FILE__,                               \
                             __LINE__,                              \
                             __PRETTY_FUNCTION__, #cond, #exc, exc);\
  }

This is the main routine in the exception mechanism for debug mode error checking. It asserts that a certain condition is fulfilled, otherwise issues an error and aborts the program.

See the ExceptionBase class for more information.

Author:
Wolfgang Bangerth, November 1997, extensions 1998

Referenced by FilteredMatrix< VECTOR >::Accessor::Accessor(), Vector< Number >::add(), SparseMatrixEZ< number >::add(), CompressedSparsityPattern::add(), CompressedSimpleSparsityPattern::add(), CompressedSetSparsityPattern::add(), BlockSparseMatrixEZ< Number >::add(), CompressedSparsityPattern::add_entries(), CompressedSimpleSparsityPattern::add_entries(), CompressedSetSparsityPattern::add_entries(), BlockSparsityPatternBase< SparsityPatternBase >::add_entries(), ConstraintMatrix::add_entry(), ConstraintMatrix::add_line(), FilteredMatrix< VECTOR >::Accessor::advance(), SparseMatrixEZ< number >::allocate(), SparseMatrixEZ< number >::begin(), BlockSparsityPatternBase< SparsityPatternBase >::block(), BlockSparseMatrixEZ< Number >::block(), BlockIndices::block_size(), BlockIndices::block_start(), FiniteElement< dim, spacedim >::block_to_base_index(), TrilinosWrappers::BlockVector::BlockVector(), PETScWrappers::BlockVector::BlockVector(), TriaAccessor< 0, dim, spacedim >::boundary_indicator(), CellAccessor< dim, spacedim >::CellAccessor(), TriaAccessor< 0, dim, spacedim >::child(), internal::Triangulation::TriaObjects< G >::clear_user_data(), CompressedSparsityPattern::column_number(), CompressedSimpleSparsityPattern::column_number(), FiniteElement< dim, spacedim >::component_to_base_index(), FiniteElement< dim, spacedim >::component_to_system_index(), Tensor< rank_, dim >::contract(), Tensor< rank_, dim >::cross_product(), FunctionParser< dim >::default_variable_names(), Polynomials::Polynomial< number >::degree(), LAPACKFullMatrix< number >::eigenvalue(), SparseMatrixEZ< number >::end(), internal::Triangulation::TriaObject< structdim >::face(), internal::Triangulation::TriaObjectsHex::face_orientation(), FiniteElement< dim, spacedim >::face_system_to_base_index(), FiniteElement< dim, spacedim >::face_system_to_component_index(), internal::hp::DoFObjects< dim >::fe_index_is_active(), internal::DoFHandler::DoFObjects< dim >::fe_index_is_active(), FilteredIterator< BaseIterator >::FilteredIterator(), FiniteElement< dim, spacedim >::first_block_of_base(), Utilities::fixed_power(), GridTools::get_active_neighbors(), internal::hp::DoFObjects< dim >::get_dof_index(), internal::DoFHandler::DoFObjects< dim >::get_dof_index(), MGDoFHandler< dim, spacedim >::MGVertexDoFs::get_index(), FiniteElement< dim, spacedim >::get_nonzero_components(), BlockIndices::global_to_local(), hp::FECollection< dim, spacedim >::hp_constraints_are_implemented(), InvalidAccessor< structdim, dim, spacedim >::InvalidAccessor(), FiniteElement< dim, spacedim >::is_primitive(), BlockIndices::local_to_global(), SparseMatrixEZ< number >::locate(), DoFTools::make_sparsity_pattern(), hp::FECollection< dim, spacedim >::max_dofs_per_cell(), hp::FECollection< dim, spacedim >::max_dofs_per_face(), hp::FECollection< dim, spacedim >::max_dofs_per_hex(), hp::FECollection< dim, spacedim >::max_dofs_per_line(), hp::FECollection< dim, spacedim >::max_dofs_per_quad(), hp::FECollection< dim, spacedim >::max_dofs_per_vertex(), hp::QCollection< dim >::max_n_quadrature_points(), internal::SymmetricTensorAccessors::merge(), DataOut_DoFData< DH, patch_dim, patch_space_dim >::merge_patches(), internal::hp::DoFObjects< dim >::n_active_fe_indices(), hp::FECollection< dim, spacedim >::n_components(), FiniteElement< dim, spacedim >::n_nonzero_components(), internal::hp::DoFObjects< dim >::nth_active_fe_index(), Vector< Number >::operator()(), SparseMatrixEZ< number >::operator()(), TriaRawIterator< Accessor >::operator*(), Vector< Number >::operator*=(), SparseMatrixEZ< number >::const_iterator::operator++(), TriaRawIterator< Accessor >::operator++(), TriaRawIterator< Accessor >::operator--(), Vector< Number >::operator/=(), MatrixIterator< ACCESSOR >::operator<(), TriaRawIterator< Accessor >::operator<(), Vector< Number >::operator=(), FilteredIterator< BaseIterator >::operator=(), FiniteElement< dim, spacedim >::operator[](), MGLevelObject< Object >::operator[](), hp::QCollection< dim >::operator[](), hp::MappingCollection< dim, spacedim >::operator[](), hp::FECollection< dim, spacedim >::operator[](), VectorSlice< VECTOR >::operator[](), TableIndicesBase< N >::operator[](), internals::SparsityPatternTools::optimized_lower_bound(), SchurMatrix< MA_inverse, MB, MDt, MC >::postprocess(), BlockSparseMatrix< number >::precondition_Jacobi(), SchurMatrix< MA_inverse, MB, MDt, MC >::prepare_rhs(), Vector< Number >::reinit(), MGLevelObject< Object >::resize(), FiniteElement< dim, spacedim >::restriction_is_additive(), CompressedSparsityPattern::row_length(), CompressedSimpleSparsityPattern::row_length(), CompressedSetSparsityPattern::row_length(), Vector< Number >::sadd(), Vector< Number >::scale(), SparseMatrixEZ< number >::set(), BlockSparseMatrixEZ< Number >::set(), internal::hp::DoFObjects< dim >::set_dof_index(), internal::Triangulation::TriaObject< structdim >::set_face(), MGDoFHandler< dim, spacedim >::MGVertexDoFs::set_index(), ConstraintMatrix::set_inhomogeneity(), SolverSelector< VECTOR >::solve(), EigenInverse< VECTOR >::solve(), EigenPower< VECTOR >::solve(), TrilinosWrappers::BlockVector::swap(), TrilinosWrappers::MPI::BlockVector::swap(), PETScWrappers::MPI::BlockVector::swap(), PETScWrappers::BlockVector::swap(), BlockIndices::swap(), FiniteElement< dim, spacedim >::system_to_base_index(), FiniteElement< dim, spacedim >::system_to_block_index(), FiniteElement< dim, spacedim >::system_to_component_index(), Threads::internal::ThreadDescriptor< RT >::thread_entry_point(), GridTools::transform(), TriaAccessor< structdim, dim, spacedim >::TriaAccessor(), TriaAccessor< 0, dim, spacedim >::TriaAccessor(), TriaActiveIterator< Accessor >::TriaActiveIterator(), TriaIterator< Accessor >::TriaIterator(), internal::Triangulation::TriaObject< structdim >::TriaObject(), TransposeMatrix< MATRIX, VECTOR >::Tvmult(), PointerMatrixVector< number >::Tvmult(), PointerMatrixAux< MATRIX, VECTOR >::Tvmult(), PointerMatrix< MATRIX, VECTOR >::Tvmult(), MeanValueFilter::Tvmult(), ProductMatrix< VECTOR >::Tvmult(), BlockSparseMatrixEZ< Number >::Tvmult(), BlockDiagonalMatrix< MATRIX >::Tvmult(), MGMatrixSelect< MATRIX, number >::Tvmult(), MGMatrix< MATRIX, VECTOR >::Tvmult(), TransposeMatrix< MATRIX, VECTOR >::Tvmult_add(), PointerMatrixVector< number >::Tvmult_add(), PointerMatrixAux< MATRIX, VECTOR >::Tvmult_add(), PointerMatrix< MATRIX, VECTOR >::Tvmult_add(), MeanValueFilter::Tvmult_add(), ProductMatrix< VECTOR >::Tvmult_add(), BlockSparseMatrixEZ< Number >::Tvmult_add(), MGMatrixSelect< MATRIX, number >::Tvmult_add(), MGMatrix< MATRIX, VECTOR >::Tvmult_add(), TriaAccessor< 0, dim, spacedim >::used(), internal::Triangulation::TriaObjects< G >::user_index(), internal::Triangulation::TriaObjects< G >::user_pointer(), VectorSlice< VECTOR >::VectorSlice(), TransposeMatrix< MATRIX, VECTOR >::vmult(), PreconditionSelector< Matrix, Vector >::vmult(), PointerMatrixVector< number >::vmult(), PointerMatrixAux< MATRIX, VECTOR >::vmult(), PointerMatrix< MATRIX, VECTOR >::vmult(), ProductMatrix< VECTOR >::vmult(), BlockSparseMatrixEZ< Number >::vmult(), BlockDiagonalMatrix< MATRIX >::vmult(), MGMatrixSelect< MATRIX, number >::vmult(), MGMatrix< MATRIX, VECTOR >::vmult(), TransposeMatrix< MATRIX, VECTOR >::vmult_add(), PointerMatrixVector< number >::vmult_add(), PointerMatrixAux< MATRIX, VECTOR >::vmult_add(), PointerMatrix< MATRIX, VECTOR >::vmult_add(), ProductMatrix< VECTOR >::vmult_add(), BlockSparseMatrixEZ< Number >::vmult_add(), MGMatrixSelect< MATRIX, number >::vmult_add(), and MGMatrix< MATRIX, VECTOR >::vmult_add().

#define AssertThrow ( cond,
exc   ) 
Value:
{                                                              \
        if (__builtin_expect(!(cond), false))                        \
          ::::deal_II_exceptions::internals::                \
          issue_error_throw (__FILE__,                               \
                             __LINE__,                               \
                             __PRETTY_FUNCTION__, #cond, #exc, exc); \
      }

This is the main routine in the exception mechanism for run-time mode error checking. It assert that a certain condition is fulfilled, otherwise issues an error and aborts the program.

On some systems (we only know of DEC Alpha systems running under OSF1 or Linux), the compiler fails to compile the AssertThrow macro properly, yielding an internal compiler error. We detect this at configure time. For these cases, the AssertThrow macro aborts the program if the assertion is not satisfied. This, however, happens in debug and optimized mode likewise. Note that in these cases, the meaning of a program changes. In particular, one cannot catch exceptions thrown by AssertThrow, but we did not find another way to work around this compiler bug.

See the ExceptionBase class for more information.

ExceptionBase

Author:
Wolfgang Bangerth, November 1997, extensions 1998

Referenced by Threads::Thread< RT >::join(), and VectorView< Number >::swap().

#define DeclException0 ( Exception0   )     class Exception0 : public ::ExceptionBase {}

Declare an exception class derived from ExceptionBase without parameters.

Author:
Wolfgang Bangerth, November 1997
#define DeclException1 ( Exception1,
type1,
outsequence   ) 
Value:
class Exception1 : public ::ExceptionBase {                             \
  public:                                                             \
      Exception1 (const type1 a1) : arg1 (a1) {}                      \
      virtual ~Exception1 () throw () {}                              \
      virtual void print_info (std::ostream &out) const {              \
        out outsequence << std::endl;                                 \
      }                                                               \
  private:                                                            \
      const type1 arg1;                                               \
}

Declare an exception class derived from ExceptionBase with one additional parameter.

#define DeclException2 ( Exception2,
type1,
type2,
outsequence   ) 
Value:
class Exception2 : public ::ExceptionBase {                             \
  public:                                                             \
      Exception2 (const type1 a1, const type2 a2) :          \
              arg1 (a1), arg2(a2) {}                                  \
      virtual ~Exception2 () throw () {}                              \
      virtual void print_info (std::ostream &out) const {              \
        out outsequence << std::endl;                                 \
      }                                                               \
  private:                                                            \
      const type1 arg1;                                               \
      const type2 arg2;                                               \
}

Declare an exception class derived from ExceptionBase with two additional parameters.

#define DeclException3 ( Exception3,
type1,
type2,
type3,
outsequence   ) 
Value:
class Exception3 : public ::ExceptionBase {                             \
  public:                                                             \
      Exception3 (const type1 a1, const type2 a2, const type3 a3) : \
              arg1 (a1), arg2(a2), arg3(a3) {}                        \
      virtual ~Exception3 () throw () {}                              \
      virtual void print_info (std::ostream &out) const {              \
        out outsequence << std::endl;                                 \
      }                                                               \
  private:                                                            \
      const type1 arg1;                                               \
      const type2 arg2;                                               \
      const type3 arg3;                                               \
}

Declare an exception class derived from ExceptionBase with three additional parameters.

#define DeclException4 ( Exception4,
type1,
type2,
type3,
type4,
outsequence   ) 
Value:
class Exception4 : public ::ExceptionBase {                             \
  public:                                                             \
      Exception4 (const type1 a1, const type2 a2,                     \
            const type3 a3, const type4 a4) :                \
              arg1 (a1), arg2(a2), arg3(a3), arg4(a4) {}              \
      virtual ~Exception4 () throw () {}                              \
      virtual void print_info (std::ostream &out) const {              \
        out outsequence << std::endl;                                 \
      }                                                               \
  private:                                                            \
      const type1 arg1;                                               \
      const type2 arg2;                                               \
      const type3 arg3;                                               \
      const type4 arg4;                                               \
}

Declare an exception class derived from ExceptionBase with four additional parameters.

#define DeclException5 ( Exception5,
type1,
type2,
type3,
type4,
type5,
outsequence   ) 
Value:
class Exception5 : public ::ExceptionBase {                             \
  public:                                                             \
      Exception5 (const type1 a1, const type2 a2, const type3 a3,     \
            const type4 a4, const type5 a5) :                \
              arg1 (a1), arg2(a2), arg3(a3), arg4(a4), arg5(a5) {}    \
      virtual ~Exception5 () throw () {}                              \
      virtual void print_info (std::ostream &out) const {              \
        out outsequence << std::endl;                                 \
      }                                                               \
  private:                                                            \
      const type1 arg1;                                               \
      const type2 arg2;                                               \
      const type3 arg3;                                               \
      const type4 arg4;                                               \
      const type5 arg5;                                               \
}

Declare an exception class derived from ExceptionBase with five additional parameters.

#define AssertDimension ( dim1,
dim2   ) 
Value:
Assert((dim1) == (dim2), \
  ExcDimensionMismatch((dim1),(dim2)))

Special assertion for dimension mismatch.

Since this is used very often and always repeats the arguments, we introduce this special assertion for ExcDimensionMismatch in order to keep the user codes shorter.

Author:
Guido Kanschat 2007
#define AssertIndexRange ( index,
range   ) 
Value:
Assert((index) < (range), \
  ExcIndexRange((index),0,(range)))

Special assertion for index range of nonnegative indices.

Since this is used very often and always repeats the arguments, we introduce this special assertion for ExcIndexRange in order to keep the user codes shorter.

Called wit arguments index and range it asserts that index<range and throws ExcIndexRange(index,0,range) if it fails.

Author:
Guido Kanschat 2007

Function Documentation

ConvergenceTable::DeclException0 ( ExcWrongValueType   )  [inherited]

Exception

ConvergenceTable::DeclException1 ( ExcRateColumnAlreadyExists  ,
std::string   
) [inherited]

Exception

template<int dim, int spacedim = dim>
DataOutBase::Patch< dim, spacedim >::DeclException2 ( ExcInvalidCombinationOfDimensions  ,
int  ,
int  ,
<< "It is not possible to have a structural dimension of "<< arg1<< " to be larger than the space dimension of the surrounding"<< " space "<<  arg2 
) [inherited]

Exception

DataOutBase::DeclException2 ( ExcInvalidDatasetSize  ,
int  ,
int  ,
<< "The number of points in this data set is "<< arg1<< "  ,
but we expected"<< arg2<< "in each space direction."   
) [inherited]

Exception

DataOutBase::DeclException0 ( ExcNoPatches   )  [inherited]

An output function did not receive any patches for writing.

Reimplemented in DataOutReader< dim, spacedim >.

DataOutBase::DeclException0 ( ExcTecplotAPIError   )  [inherited]

Exception

DataOutBase::DeclException1 ( ExcErrorOpeningTecplotFile  ,
char *  ,
<< "There was an error opening Tecplot file "<< arg1<< " for output"   
) [inherited]

Exception


deal.II documentation generated on Mon Nov 23 22:57:24 2009 by doxygen 1.6.1