| Cantera 3.0.0

Loading...
Searching...
No Matches
Classes | Macros | Functions
Errors
Errors and Diagnostics

Handling of errors and unknown events within Cantera. More...

Collaboration diagram for Errors:

## Detailed Description

Handling of errors and unknown events within Cantera.

The general idea is that exceptions are thrown using the common base class called CanteraError. Derived types of CanteraError characterize what type of error is thrown. A list of all of the thrown errors is kept in the Application class.

Any exceptions which are not caught cause a fatal error exit from the program.

A group of defines may be used during debugging to assert conditions which should be true. These are named AssertTrace(), AssertThrow(), and AssertThrowMsg(). Examples of their usage is given below.

AssertTrace(p == OneAtm);
AssertThrow(p == OneAtm, "Kinetics::update");
AssertThrowMsg(p == OneAtm, "Kinetics::update",
"Algorithm limited to atmospheric pressure");
AssertThrow
#define AssertThrow(expr, procedure)
Assertion must be true or an error is thrown.
Definition ctexceptions.h:261
AssertTrace
#define AssertTrace(expr)
Assertion must be true or an error is thrown.
Definition ctexceptions.h:247
AssertThrowMsg
#define AssertThrowMsg(expr, procedure,...)
Assertion must be true or an error is thrown.
Definition ctexceptions.h:278
Cantera::OneAtm
const double OneAtm
One atmosphere [Pa].
Definition ct_defs.h:96

Their first argument is a boolean. If the boolean is not true, a CanteraError is thrown, with descriptive information indicating where the error occurred. The Assert* checks are skipped if the NDEBUG preprocessor symbol is defined, for example with the compiler option -DNDEBUG.

## Classes
class | CanteraError
| Base class for exceptions thrown by Cantera classes. More...
class | ArraySizeError
| Array size error. More...
class | IndexError
| An array index is out of range. More...
class | NotImplementedError
| An error indicating that an unimplemented function has been called. More...

## Macros
#define | AssertTrace(expr) ((expr) ? (void) 0 : throw CanteraError(STR_TRACE, string("failed assert: ") + #expr))
| Assertion must be true or an error is thrown.
#define | AssertThrow(expr, procedure) ((expr) ? (void) 0 : throw CanteraError(procedure, string("failed assert: ") + #expr))
| Assertion must be true or an error is thrown.
#define | AssertThrowMsg(expr, procedure, ...) ((expr) ? (void) 0 : throw CanteraError(procedure + string(":\nfailed assert: \"") + string(#expr) + string("\""), __VA_ARGS__))
| Assertion must be true or an error is thrown.
#define | AssertFinite(expr, procedure, ...) AssertThrowMsg(expr < BigNumber && expr > -BigNumber, procedure, __VA_ARGS__)
| Throw an exception if the specified exception is not a finite number.

## Functions
void | addError (const string &r, const string &msg="")
| Set an error condition in the application class without throwing an exception.
int | getErrorCount ()
| Return the number of errors that have been encountered so far.
void | popError ()
| Discard the last error message.
string | lastErrorMessage ()
| Retrieve the last error message in a string.
void | getErrors (std::ostream &f)
| Prints all of the error messages to an ostream.
void | logErrors ()
| Prints all of the error messages using writelog.

## Macro Definition Documentation

## ◆ AssertTrace

#define AssertTrace | ( |  | expr | ) | ((expr) ? (void) 0 : throw CanteraError(STR_TRACE, string("failed assert: ") + #expr))

Assertion must be true or an error is thrown.

Assertion must be true or else a CanteraError is thrown. A diagnostic string containing the file and line number, indicating where the error occurred is added to the thrown object.

Parameters

  expr | Boolean expression that must be true

Definition at line 247 of file ctexceptions.h.

## ◆ AssertThrow

#define AssertThrow | ( |  | expr,
|  |  | procedure
| ) |  | ((expr) ? (void) 0 : throw CanteraError(procedure, string("failed assert: ") + #expr))

Assertion must be true or an error is thrown.

Assertion must be true or else a CanteraError is thrown. A diagnostic string indicating where the error occurred is added to the thrown object.

Parameters

  expr | Boolean expression that must be true
  procedure | Character string or std:string expression indicating the procedure where the assertion failed

Definition at line 261 of file ctexceptions.h.

## ◆ AssertThrowMsg

#define AssertThrowMsg | ( |  | expr,
|  |  | procedure,
|  |  | ...
| ) |  | ((expr) ? (void) 0 : throw CanteraError(procedure + string(":\nfailed assert: \"") + string(#expr) + string("\""), __VA_ARGS__))

Assertion must be true or an error is thrown.

Assertion must be true or else a CanteraError is thrown. A diagnostic string indicating where the error occurred is added to the thrown object.

Parameters

  expr | Boolean expression that must be true
  procedure | Character string or std:string expression indicating the procedure where the assertion failed Additional arguments are passed on to the constructor for CanteraError to generate a formatted error message.

Definition at line 278 of file ctexceptions.h.

## ◆ AssertFinite

#define AssertFinite | ( |  | expr,
|  |  | procedure,
|  |  | ...
| ) |  | AssertThrowMsg(expr < BigNumber && expr > -BigNumber, procedure, __VA_ARGS__)

Throw an exception if the specified exception is not a finite number.

Definition at line 286 of file ctexceptions.h.

## Function Documentation

## ◆ addError()

void addError | ( | const string & | r,
|  | const string & | msg = `""`
| ) |  |

Set an error condition in the application class without throwing an exception.

This routine adds an error message to the end of the stack of errors that Cantera accumulates in the Application class.

Parameters

  r | Procedure name which is generating the error condition
  msg | Descriptive message of the error condition.

If only one argument is specified, that string is used as the entire message.

Definition at line 45 of file application.cpp.

## ◆ getErrorCount()

int getErrorCount | ( |  | ) |

Return the number of errors that have been encountered so far.

Definition at line 59 of file application.cpp.

## ◆ popError()

void popError | ( |  | ) |

Discard the last error message.

Cantera saves a stack of exceptions that it has caught in the Application class. This routine eliminates the last exception to be added to that stack.

Definition at line 183 of file application.cpp.

## ◆ lastErrorMessage()

string lastErrorMessage | ( |  | ) |

Retrieve the last error message in a string.

This routine will retrieve the last error message and return it in the return string.

Definition at line 190 of file application.cpp.

## ◆ getErrors()

void getErrors | ( | std::ostream & | f | ) |

Prints all of the error messages to an ostream.

Write out all of the saved error messages to the ostream f using the function Logger::writelog. Cantera saves a stack of exceptions that it has caught in the Application class. This routine writes out all of the error messages to the ostream and then clears them from internal storage.

Parameters

  f | ostream which will receive the error messages

Definition at line 199 of file application.cpp.

## ◆ logErrors()

void logErrors | ( |  | ) |

Prints all of the error messages using writelog.

Print all of the error messages using function writelog. Cantera saves a stack of exceptions that it has caught in the Application class. This routine writes out all of the error messages and then clears them from internal storage.

Definition at line 207 of file application.cpp.