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

#include <Exception.h>

Inheritance diagram for PLMD::Exception:

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__)

◆ plumed_dbg_assert

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

◆ plumed_dbg_massert

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

◆ plumed_error

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

◆ plumed_massert

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

◆ plumed_merror

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

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:

tools/Exception.h
tools/Exception.cpp

Public Member Functions

Private Member Functions

Static Private Member Functions

Private Attributes

Related Functions

Detailed Description

Constructor & Destructor Documentation

◆ Exception() [1/3]

◆ Exception() [2/3]

◆ Exception() [3/3]

◆ ~Exception()

Member Function Documentation

◆ abortIfExceptionsAreDisabled()

◆ format()

◆ stack()

◆ trace()

◆ what()

Friends And Related Function Documentation

◆ plumed_assert

◆ plumed_dbg_assert

◆ plumed_dbg_massert

◆ plumed_error

◆ plumed_massert

◆ plumed_merror

Member Data Documentation

◆ msg

◆ stackString