Detailed Description

An Exception class for exceptions thrown by DRAMA V2 classes.

DRAMA Traditionally uses an inherited status error handing convention. The DRAMA V2 classes will convert any error status from the underlying C libraries into an exception of this class (or a sub-class).

The underlying DRAMA Status is saved, and generally extra text is added at the point of the throw, as well as the line number and file where the throw was generated.

To throw an exception, construct objects of this class They allow conextual information to be provided (C++ source file, source line number and a message) to be provided with the exception. Then throw the object. Between constructing and throwing, other information can be added. The information is available to catching functions via the toString() method.

It is expected that all DRAMA 2 classes throw exceptions using this exception or sub-classes of it.

Two macros are provides which implement a simple interface to throwing these exceptions. DramaTHROW() needs only a DRAMA status and a contextual message, automatically inserting the C++ source file details. DramaTHROW_S() is similar except that message can include format characters with extra arguments added.

A stack-trace is also generated to help work out the location of the throw. This provides the best information if the program is linked with the "-rdynamic" option (at least, under gcc on linux, other cases to be determined).

Methods are provided which allow information the DRAMA C level Error Reporting System (ERS) to be added to the exception, and also too allow the exception information to be output to ERS. This allows transfer across C/C++ boundaries in either direction.

A << class operator allows any type supported by sstream to be written to the exception message. Various other ways of writing to the exception message are provided, such as FmtWrite().

An (non class) << operator allows the exception details to be written to a C++ ostream. Various other output methods are provided.

Author: Tony Farrell, AAO

Revision: 1.45

Date: 22-Feb-2016 14:09:57+11

Examples:: argtest.cpp, dramahello.cpp, monitor1.cpp, monitor2.cpp, threadbasic.cpp, and tocker.cpp.

#include "exception.hh"

Inheritance diagram for drama::Exception:

Public Member Functions
	Exception (const std::string func, const std::string &file, const int lineNum, const std::string &message="", const StatusType status=DRAMA2__CPP_ERROR)
	Create an Exception. More...

D2DEPRECATED	Exception (bool makeUnique, const std::string func, const std::string &file, const int lineNum, const StatusType status, const char *format,...)
	Create an exception using C printf() style string formatting. More...

	Exception (const Exception &source)
	Copy constructor. More...

	Exception (Exception &&source) noexcept
	Move constructor. More...

virtual	~Exception ()
	Virtual Destructor - since we will be inherited. More...

void	AddErs ()
	Add the any errors from the current ERS context to the exception. More...

virtual StatusType	dramaStatus () const
	Return the DRAMA Status code associated with the exception. More...

virtual std::string	dramaStatusStr () const
	Return the DRAMA Status code converted to a DRAMA. More...

virtual void	ErsOut () const
	Output a DRAMA ERS report about this exception. More...

virtual void	ErsRep () const
	Report details of this exception using ERS. More...

virtual const std::string &	fileName () const
	Returns the name of the C++ source file in which the exception occurred. More...

void	FmtWrite (const char *str)
	Safe formatted write to an example. More...

template<typename T , typename... Types>
void	FmtWrite (const char *format, T value, Types...args)
	Safe formated write to an exception. More...

virtual const std::string &	function () const
	Returns the name of the function in which the exception occurred. More...

virtual const std::string &	getOrigMessage () const
	Returns the exception original message. More...

virtual std::string	getStackTrace () const
	Return the stack trace created when the exception was created. More...

virtual int	lineNumber () const
	Returns the line number at which the exception occurred. More...

template<class T >
Exception &	operator<< (const T &t)
	Add extra information to an exception message. More...

Exception &	operator= (const Exception &rhs)
	Assignment operator. More...

Exception &	operator= (Exception &&rhs) noexcept
	Move assignment operator. More...

virtual void	Print (FILE *file=stderr) const
	Print exception details to a file. More...

virtual int	statusAsSysExitCode () const
	Return a system exit code based on the DRAMA Status. More...

virtual std::string	toString () const
	Return the exception string. More...

const char *	what () const noexcept override
	Get string identifying exception. More...

Constructor & Destructor Documentation

drama::Exception::Exception	(	const std::string	func,
		const std::string &	file,
		const int	lineNum,
		const std::string &	message = `""`,
		const StatusType	status = `DRAMA2__CPP_ERROR`
	)

inline

Create an Exception.

This is the main constructors, other delegate to this one.

Parameters

func	Name of the function where the exception was thrown
file	Name of the file in which the exception was constructed.
lineNum	Line number where the exception was constructed.
message	A textual message to associate with the exception.
status	A DRAMA Status code to be associated with the message if later converted to a DRAMA report. Defaults to DRAMA2__CPP_ERROR

D2DEPRECATED drama::Exception::Exception	(	bool	makeUnique,
		const std::string	func,
		const std::string &	file,
		const int	lineNum,
		const StatusType	status,
		const char *	format,
			...
	)

inline

Create an exception using C printf() style string formatting.

Deprecated:: This function should be replaced by using the FmtWrite method.

Parameters

makeUnique	Value ignored, used to ensure constructor is unique
func	Name of the function where the exception was thrown
file	Name of the file in which the exception was constructed.
lineNum	Line number where the exception was constructed.
status	A DRAMA Status code to be associated with the message if later converted to a DRAMA report. Set to DRAMA2__CPP_ERROR if not wanted.
format	C printf() format string.
...	Format extra argument.s

drama::Exception::Exception ( const Exception & source )

inline

Copy constructor.

drama::Exception::Exception ( Exception && source )

inlinenoexcept

Move constructor.

virtual drama::Exception::~Exception ( )

inlinevirtual

Virtual Destructor - since we will be inherited.

Member Function Documentation

void drama::Exception::AddErs ( )

inline

Add the any errors from the current ERS context to the exception.

After doing this, it will annul the message in ERS.

virtual StatusType drama::Exception::dramaStatus ( ) const

inlinevirtual

Return the DRAMA Status code associated with the exception.

If no DRAMA status is assoicated with the exception, will return DRAMA2__CPP_ERROR.

Examples:: dramahello.cpp, monitor1.cpp, and monitor2.cpp.

Referenced by ErsOut(), ErsRep(), operator<<(), and Print().

virtual std::string drama::Exception::dramaStatusStr ( ) const

inlinevirtual

Return the DRAMA Status code converted to a DRAMA.

See also: MessGetMsg()

Examples:: dramahello.cpp.

Referenced by ErsRep(), operator<<(), and Print().

virtual void drama::Exception::ErsOut ( ) const

inlinevirtual

Output a DRAMA ERS report about this exception.

Appropriate information is written using ErsRep() calls and ERS is then flushed.

References dramaStatus(), and ErsRep().

virtual void drama::Exception::ErsRep ( ) const

inlinevirtual

Report details of this exception using ERS.

A number of ErsRep() calls are made to report details of this exception using the traditional DRAMA approach.

If the DRAMA2_ERS_DUMP environment variable is set, then details are also printed to stderr - which gives you the stack dump etc, not otherwise available.

References dramaStatus(), dramaStatusStr(), fileName(), lineNumber(), and Print().

Referenced by ErsOut().

virtual const std::string& drama::Exception::fileName ( ) const

inlinevirtual

Returns the name of the C++ source file in which the exception occurred.

Referenced by ErsRep(), and Print().

void drama::Exception::FmtWrite ( const char * str )

Safe formatted write to an example.

Case with no arguments.

Parameters

str	The string to be written.

Referenced by drama::ExceptionThrowSafe(), and FmtWrite().

template<typename T , typename... Types>

void drama::Exception::FmtWrite	(	const char *	format,
		T	value,
		Types...	args
	)

inline

Safe formated write to an exception.

Parameters

format	The format string. Each % character is to be replaced by the corresponding argument. Note - only the % is needed and used, don't do for example "%d". To output a %, use "%%".
value	The first argument.
args	Arguments to the format. Any arbitrary types can be formatted as long as an overload of the << operator is available for that type.

References DramaTHROW, and FmtWrite().

virtual const std::string& drama::Exception::function ( ) const

inlinevirtual

Returns the name of the function in which the exception occurred.

virtual const std::string& drama::Exception::getOrigMessage ( ) const

inlinevirtual

Returns the exception original message.

Returns: The original exception message, without line number and file.

virtual std::string drama::Exception::getStackTrace ( ) const

inlinevirtual

Return the stack trace created when the exception was created.

Referenced by Print().

virtual int drama::Exception::lineNumber ( ) const

inlinevirtual

Returns the line number at which the exception occurred.

Referenced by ErsRep(), and Print().

template<class T >

Exception& drama::Exception::operator<< ( const T & t )

inline

Add extra information to an exception message.

Anything supported as a type by sstreams can be added.

Parameters

t	The information to be added.

Exception& drama::Exception::operator= ( const Exception & rhs )

inline

Assignment operator.

Exception& drama::Exception::operator= ( Exception && rhs )

inlinenoexcept

Move assignment operator.

virtual void drama::Exception::Print ( FILE * file = stderr ) const

inlinevirtual

Print exception details to a file.

Parameters

file	The file to print the exception details to. Defaults to stderr.

Examples:: argtest.cpp, monitor1.cpp, monitor2.cpp, threadbasic.cpp, and tocker.cpp.

References dramaStatus(), dramaStatusStr(), fileName(), getStackTrace(), and lineNumber().

Referenced by ErsRep().

virtual int drama::Exception::statusAsSysExitCode ( ) const

inlinevirtual

Return a system exit code based on the DRAMA Status.

See also: MessStatusToSysExit()

Examples:: dramahello.cpp, monitor1.cpp, monitor2.cpp, threadbasic.cpp, and tocker.cpp.

Referenced by drama::CreateRunDramaTask().

virtual std::string drama::Exception::toString ( ) const

inlinevirtual

Return the exception string.

Returns: The string added when the exception was generated, with line number and file name added.

Examples:: dramahello.cpp.

Referenced by operator<<(), and what().

const char* drama::Exception::what ( ) const

inlineoverridenoexcept

Get string identifying exception.

Returns a null terminated character sequence that may be used to identify the exception - in particular, the message that is part of this exception.

This method is an implementation of the std::exception method of the same name, but returns the same data as drama::Exception's toString() method.

Returns: A pointer to a c-string with content related to the exception. This is guaranteed to be valid at least until the exception object from which it is obtained is destroyed or until a non-const member function of the exception object is called.

References toString().

Referenced by drama::CreateRunDramaTask().

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

exception.hh

Detailed Description

Public Member Functions

Constructor & Destructor Documentation

Member Function Documentation