Public Member Functions | Private Member Functions | Static Private Member Functions | Private Attributes | Related Functions | List of all members
PLMD::Exception Class Reference


Class to deal with Plumed runtime errors. More...

#include <Exception.h>

Inheritance diagram for PLMD::Exception:
Inheritance graph
[legend]

Public Member Functions

 Exception ()
 Without message. More...
 
 Exception (const std::string &)
 With message. More...
 
 Exception (const std::string &, const std::string &, unsigned, const std::string &)
 With message plus file, line and function (meant to be used through a preprocessor macro) More...
 
virtual const char * what () const throw ()
 Returns the error message. More...
 
virtual const char * stack () const throw ()
 Returns the stack trace. More...
 
virtual ~Exception () throw ()
 Destructor should be defined and should not throw other exceptions. More...
 

Private Member Functions

void abortIfExceptionsAreDisabled ()
 Method which aborts in case exceptions are disabled. More...
 

Static Private Member Functions

static std::string trace ()
 Create stack trace. More...
 
static std::string format (const std::string &, const std::string &, unsigned, const std::string &)
 Common tool, invoked by all the constructor to build the message string. More...
 

Private Attributes

std::string stackString
 Stack trace at exception. More...
 
std::string msg
 Reported message. More...
 

Related Functions

(Note that these are not member functions.)

#define plumed_error()   throw PLMD::Exception("",__FILE__,__LINE__,__PRETTY_FUNCTION__)
 
#define plumed_merror(msg)   throw PLMD::Exception(msg,__FILE__,__LINE__,__PRETTY_FUNCTION__)
 
#define plumed_assert(test)   if(!(test)) throw PLMD::Exception("assertion failed " #test,__FILE__,__LINE__,__PRETTY_FUNCTION__)
 
#define plumed_massert(test, msg)   if(!(test)) throw PLMD::Exception("assertion failed " #test ", " msg,__FILE__,__LINE__,__PRETTY_FUNCTION__)
 
#define plumed_dbg_assert(test)   if(!(test)) throw PLMD::Exception("assertion failed " #test,__FILE__,__LINE__,__PRETTY_FUNCTION__)
 
#define plumed_dbg_massert(test, msg)   if(!(test)) throw PLMD::Exception("assertion failed " #test ", " msg,__FILE__,__LINE__,__PRETTY_FUNCTION__)
 

Detailed Description


Class to deal with Plumed runtime errors.

This class, or better the related macros, can be used to detect programming errors. Typical cases are internal inconsistencies or errors in the plumed<->MD interface. Mistakes made by final users (i.e. in the plumed.dat file) should be documented in some better way (e.g. printing parts of the manual in the output).

To throw an error, just throw a c++ exception

  if(something_bad) throw Exception();

or better add an error message to that

  if(something_bad) throw Exception("describe the error here);

Even better, you can use the predefined macros plumed_error(), plumed_assert(), plumed_merror() and plumed_massert(), which add information about the exact location of the error in the file (filename, line and, for g++, function name). Macros ending in "error" unconditionally throw the exception, whereas macros ending in "assert" first perform a conditional check (similarly to standard assert()). The extra "m" in the name means that an extensive error message can be added.

// examples:
  plumed_assert(a>0);
  plumed_massert(a>0,"a should be larger than zero");
  if(a<=0) plumed_error();
  if(a<=0) plumed_merror("a should be larger than zero");

The additional macros plumed_dbg_assert() and plumed_dbg_massert() are similar to plumed_assert() and plumed_massert() respectively, but the corresponding check is only performed when NDEBUG macro is not defined. They should be used when the check is expensive and should be skipped in production code.

By default, execution is terminated imediately and a message is printed on stderr.

If PLUMED is compiled with -D__PLUMED_EXCEPTIONS execution will continue and the exception will be passed to c++, so that it will be possible to intercepted it at a higher level, even outside plumed. E.g., in an external c++ code using PLUMED as a library, one can type

  try{
    plumed.cmd("setPrecision",n);
  } catch (std::exception & e) {
    printf("ee %s",e.what());
    exit(1);
  }

This can be useful if an external code wants to exit in a controlled manner (e.g. flushing files, printing the error message in a specific file, etc.) but is anyway limited to c++ codes. Moreover, since these errors are expected to be unrecoverable, the MD code will usually not be able to do something more clever than exiting.

Note
In the future we might decide to extend the usage of exceptions to detect recoverable errors (e.g. optional arguments not found, etc), even if I am not fully convinced that this is a good idea. Notice that sometime people claim that code compiled with exception enabled is slower (GB)

Constructor & Destructor Documentation

◆ Exception() [1/3]

PLMD::Exception::Exception ( )

Without message.

◆ Exception() [2/3]

PLMD::Exception::Exception ( const std::string &  )
explicit

With message.

◆ Exception() [3/3]

PLMD::Exception::Exception ( const std::string &  ,
const std::string &  ,
unsigned  ,
const std::string &   
)

With message plus file, line and function (meant to be used through a preprocessor macro)

◆ ~Exception()

virtual PLMD::Exception::~Exception ( )
throw (
)
inlinevirtual

Destructor should be defined and should not throw other exceptions.

Member Function Documentation

◆ abortIfExceptionsAreDisabled()

void PLMD::Exception::abortIfExceptionsAreDisabled ( )
private

Method which aborts in case exceptions are disabled.

◆ format()

std::string PLMD::Exception::format ( const std::string &  msg,
const std::string &  file,
unsigned  line,
const std::string &  function 
)
staticprivate

Common tool, invoked by all the constructor to build the message string.

◆ stack()

virtual const char* PLMD::Exception::stack ( ) const
throw (
)
inlinevirtual

Returns the stack trace.

◆ trace()

std::string PLMD::Exception::trace ( )
staticprivate

Create stack trace.

◆ what()

virtual const char* PLMD::Exception::what ( ) const
throw (
)
inlinevirtual

Returns the error message.

In case the environment variable PLUMED_STACK_TRACE is defined, the error message will contain the stack trace as well.

Friends And Related Function Documentation

◆ plumed_assert

#define plumed_assert (   test)    if(!(test)) throw PLMD::Exception("assertion failed " #test,__FILE__,__LINE__,__PRETTY_FUNCTION__)
related

Conditionally print file/line/function information and exit

◆ plumed_dbg_assert

#define plumed_dbg_assert (   test)    if(!(test)) throw PLMD::Exception("assertion failed " #test,__FILE__,__LINE__,__PRETTY_FUNCTION__)
related

Conditionally print file/line/function information and exit when NDEBUG flag is not present

◆ plumed_dbg_massert

#define plumed_dbg_massert (   test,
  msg 
)    if(!(test)) throw PLMD::Exception("assertion failed " #test ", " msg,__FILE__,__LINE__,__PRETTY_FUNCTION__)
related

Conditionally print file/line/function information plus msg and exit when NDEBUG flag is not present

◆ plumed_error

#define plumed_error ( )    throw PLMD::Exception("",__FILE__,__LINE__,__PRETTY_FUNCTION__)
related

Just print file/line/function information and exit

◆ plumed_massert

#define plumed_massert (   test,
  msg 
)    if(!(test)) throw PLMD::Exception("assertion failed " #test ", " msg,__FILE__,__LINE__,__PRETTY_FUNCTION__)
related

Conditionally print file/line/function information plus msg and exit

◆ plumed_merror

#define plumed_merror (   msg)    throw PLMD::Exception(msg,__FILE__,__LINE__,__PRETTY_FUNCTION__)
related

Print file/line/function information plus msg and exit

Member Data Documentation

◆ msg

std::string PLMD::Exception::msg
private

Reported message.

◆ stackString

std::string PLMD::Exception::stackString
private

Stack trace at exception.


The documentation for this class was generated from the following files: