Cantera  2.0
Classes | Macros | Functions
Error Handling

These classes and related functions are used to handle errors and unknown events within Cantera. More...

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...
 

Macros

#define AssertThrowVCS(expr, proc)   ((expr) ? (void) 0 : throw vcsError(proc, std::string("failed Assert: ") + #expr,-1))
 Assertion must be true or an error is thrown.
 
#define AssertTrace(expr)   ((expr) ? (void) 0 : throw Cantera::CanteraError(STR_TRACE, std::string("failed assert: ") + #expr))
 Assertion must be true or an error is thrown.
 
#define AssertThrow(expr, procedure)   ((expr) ? (void) 0 : throw Cantera::CanteraError(procedure, std::string("failed assert: ") + #expr))
 Assertion must be true or an error is thrown.
 
#define AssertThrowMsg(expr, procedure, message)   ((expr) ? (void) 0 : throw Cantera::CanteraError(procedure + std::string(": at failed assert: \"") + std::string(#expr) + std::string("\""), message))
 Assertion must be true or an error is thrown.
 

Functions

void addError (std::string r, std::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.
 
std::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.
 
void addError (std::string r, std::string msg)
 Set an error condition in the application class without throwing an exception.
 
void popError ()
 Discard the last error message.
 
std::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.
 
void deprecatedMethod (std::string classnm, std::string oldnm, std::string newnm)
 Print a warning when a deprecated method is called.
 
void removeAtVersion (std::string func, std::string version)
 Throw an error condition for a procedure that has been removed.
 
int nErrors ()
 Return the number of errors that have been encountered so far.
 
string lastErrorMessage ()
 Returns the last error message.
 
void setError (std::string r, std::string msg)
 Set an error condition in the application class without throwing an exception.
 
void showErrors (std::ostream &f)
 Prints all of the error messages to an ostream.
 
void showErrors ()
 Print all of the error messages using function writelog of class logger.
 
void popError ()
 Discard the last error message.
 

Detailed Description

These classes and related functions are used to handle 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.

Below is an example of how to catch errors that throw the CanteraError class. In general, all Cantera C++ programs will have this basic structure.

The function showErrors() will print out the fatal error condition to standard output.

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.

AssertThrow(p == OneAtm, "Kinetics::update");
AssertThrowMsg(p == OneAtm, "Kinetics::update",
"Algorithm limited to atmospheric pressure");

Their first argument is a boolean. If the boolean is not true, a CanteraError is thrown, with descriptive information indicating where the error occurred. These functions may be eliminated from the source code, if the -DNDEBUG option is specified to the compiler.

Macro Definition Documentation

#define AssertThrowVCS (   expr,
  proc 
)    ((expr) ? (void) 0 : throw vcsError(proc, std::string("failed Assert: ") + #expr,-1))

Assertion must be true or an error is thrown.

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

Parameters
exprBoolean expression that must be true
procCharacter string or std:string expression indicating the procedure where the assertion failed

Definition at line 40 of file vcs_Exception.h.

Referenced by VCS_SOLVE::vcs_basisOptMax().

#define AssertTrace (   expr)    ((expr) ? (void) 0 : throw Cantera::CanteraError(STR_TRACE, std::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
exprBoolean expression that must be true

Definition at line 237 of file ctexceptions.h.

Referenced by HMWSoln::applyphScale(), IonsFromNeutralVPSSTP::calcNeutralMoleculeMoleFractions(), Phase::entropyElement298(), Elements::entropyElement298(), IonsFromNeutralVPSSTP::getNeutralMoleculeMoleGrads(), Cantera::importPhase(), VPStandardStateTP::initThermoXML(), WaterTransport::initTP(), rxninfo::installReaction(), HMWSoln::s_updateScaling_pHScaling(), HMWSoln::s_updateScaling_pHScaling_dP(), HMWSoln::s_updateScaling_pHScaling_dT(), and HMWSoln::s_updateScaling_pHScaling_dT2().

#define AssertThrow (   expr,
  procedure 
)    ((expr) ? (void) 0 : throw Cantera::CanteraError(procedure, std::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
exprBoolean expression that must be true
procedureCharacter string or std:string expression indicating the procedure where the assertion failed

Definition at line 250 of file ctexceptions.h.

Referenced by MolalityVPSSTP::getActivityCoefficients(), IdealMolalSoln::getChemPotentials(), SimpleTransport::getSpeciesFluxesExt(), STITbyPDSS::initAllPtrs(), PDSS::initPtrs(), PDSS::initThermo(), PDSS::initThermoXML(), GeneralSpeciesThermo::install_STIT(), and RootFind::solve().

#define AssertThrowMsg (   expr,
  procedure,
  message 
)    ((expr) ? (void) 0 : throw Cantera::CanteraError(procedure + std::string(": at failed assert: \"") + std::string(#expr) + std::string("\""), message))

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
exprBoolean expression that must be true
procedureCharacter string or std:string expression indicating the procedure where the assertion failed
messageCharacter string or std:string expression containing a descriptive message is added to the thrown error condition.

Definition at line 268 of file ctexceptions.h.

Referenced by VPStandardStateTP::_updateStandardStateThermo(), Application::Messages::endLogGroup(), Phase::entropyElement298(), Elements::entropyElement298(), MolalityVPSSTP::setSolvent(), and STITbyPDSS::updatePropertiesTemp().

Function Documentation

void addError ( std::string  r,
std::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
rlocation
msgDescription of the error

Definition at line 112 of file application.cpp.

Referenced by Application::addError().

int getErrorCount ( )

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

Definition at line 119 of file application.cpp.

Referenced by Application::getErrorCount().

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 529 of file application.cpp.

References Application::Messages::errorMessage, and Application::Messages::errorRoutine.

Referenced by Application::popError().

std::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 537 of file application.cpp.

Referenced by Application::lastErrorMessage().

void getErrors ( std::ostream &  f)

Prints all of the error messages to an ostream.

Print all of the error messages using function writelog. Write out all of the saved error messages to the ostream f 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
fostream which will receive the error messages

Definition at line 551 of file application.cpp.

Referenced by Application::getErrors().

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 573 of file application.cpp.

References Application::writelog().

Referenced by Application::logErrors().

void addError ( std::string  r,
std::string  msg 
)
inline

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
rlocation
msgDescription of the error

Definition at line 372 of file application.h.

References Application::Messages::addError(), and Application::pMessenger.

Referenced by CanteraError::save(), and Cantera::setError().

void popError ( )
inline

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 392 of file application.h.

References Application::pMessenger, and Application::Messages::popError().

Referenced by Cantera::popError().

std::string lastErrorMessage ( )
inline

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 403 of file application.h.

References Application::Messages::lastErrorMessage(), and Application::pMessenger.

Referenced by Cantera::lastErrorMessage().

void getErrors ( std::ostream &  f)
inline

Prints all of the error messages to an ostream.

Print all of the error messages using function writelog. Write out all of the saved error messages to the ostream f 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
fostream which will receive the error messages

Definition at line 420 of file application.h.

References Application::Messages::getErrors(), and Application::pMessenger.

Referenced by Cantera::showErrors().

void logErrors ( )
inline

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 434 of file application.h.

References Application::Messages::logErrors(), and Application::pMessenger.

Referenced by Cantera::showErrors().

void deprecatedMethod ( std::string  classnm,
std::string  oldnm,
std::string  newnm 
)

Print a warning when a deprecated method is called.

These methods are slated to go away in future releases of Cantera. The developer should work towards eliminating the use of these methods in the near future.

Parameters
classnmClass the method belongs to
oldnmName of the deprecated method
newnmName of the method users should use instead

Definition at line 75 of file ctexceptions.cpp.

References Cantera::writelog().

Referenced by Kinetics::phase(), Kinetics::start(), and ThermoPhase::updateDensity().

void removeAtVersion ( std::string  func,
std::string  version 
)

Throw an error condition for a procedure that has been removed.

Parameters
funcString name for the function within which the error was generated.
versionVersion of Cantera that first removed this function.

Definition at line 84 of file ctexceptions.cpp.

References Cantera::writelog().

int nErrors ( )

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

Definition at line 146 of file global.cpp.

References Cantera::app(), and Application::getErrorCount().

std::string lastErrorMessage ( )

Returns the last error message.

Returns
String containing the description of the last error message.

Definition at line 156 of file global.cpp.

References Cantera::app(), and Application::lastErrorMessage().

Referenced by Cantera::equilibrate(), Cantera::vcs_determine_PhaseStability(), and Cantera::vcs_equilibrate_1().

void setError ( std::string  r,
std::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
rProcedure name which is generating the error condition
msgDescriptive message of the error condition.

Definition at line 171 of file global.cpp.

References Application::addError(), and Cantera::app().

Referenced by XML_IllegalUnits::XML_IllegalUnits(), XML_NoChild::XML_NoChild(), and XML_TagMismatch::XML_TagMismatch().

void showErrors ( 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 member function writelog of class logger. 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
fostream which will receive the error messages

Definition at line 161 of file global.cpp.

References Cantera::app(), and Application::getErrors().

void showErrors ( )

Print all of the error messages using function writelog of class logger.

Print all of the error messages using the member function writelog of class logger. Write out all of the saved error messages to the log device. 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 log, usually stdout, and then clears them from internal storage.

Definition at line 166 of file global.cpp.

References Cantera::app(), and Application::logErrors().

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 151 of file global.cpp.

References Cantera::app(), and Application::popError().

Referenced by SpeciesThermoFactory::newSpeciesThermo(), SpeciesThermoFactory::newSpeciesThermoOpt(), and VPSSMgrFactory::newVPSSMgr().