Error and Exception Module

For detailed information see Error and Exception Handling More...

Collaboration diagram for Error and Exception Module:

Classes
class	CallStack
	Encapsulates unix call stack functionality. More...
class	Exception
	Base class for exceptions. More...
struct	IntSignal
	Structure used in signal handlers to pass the signal and callstack. More...

Macros
#define	MIRA_THROW(ex, msg)
	Macro for throwing an exception. More...
#define	MIRA_THROW_NOSTACK(ex, msg)
	Same as MIRA_THROW, except that no stack trace information is stored. More...
#define	MIRA_THROW_EXTSTACK(ex, msg, stack, thread)
	Same as MIRA_THROW, except that the stack trace information that is stored is provided externally. More...
#define	MIRA_RETHROW(ex, msg)
	Macro for rethrowing an exception with file and line information and for adding additional information. More...
#define	MIRA_DEFINE_EXCEPTION(Ex, Base)
	Macro for easily defining a new compatible exception class. More...
#define	MIRA_DEFINE_SERIALIZABLE_EXCEPTION(Ex, Base)
	Macro for easily defining a new serializable exception class. More...

Functions
void MIRA_BASE_EXPORT	installSignalHandler (int sig, boost::function< void(const IntSignal &)> function)
	Registers a function for the specified interrupt signal. More...

Detailed Description

For detailed information see Error and Exception Handling

Macro Definition Documentation

MIRA_THROW

#define MIRA_THROW	(		ex,
			msg
	)

Value:

{                                                                   \
    std::ostringstream ex_str;                                      \
    ex_str << msg;                                                  \
    constexpr auto fileInMIRAPath = mira::chopMIRAPath(__FILE__);   \
    throw ex(ex_str.str(), fileInMIRAPath, __LINE__).addStackInfo<ex>();  \
}

Macro for throwing an exception.

The macro additionally stores the filename and the line of the source file where the exception was thrown. Additional information for the user can be specified as stream in the second macro parameter.

Example:

void readValue(istream& ioStream)
{
    if(...error while reading from io...)
        MIRA_THROW(XIO, "Invalid format, the tag '" << foo "' is missing");
}

MIRA_THROW_NOSTACK

#define MIRA_THROW_NOSTACK	(		ex,
			msg
	)

Value:

{                                                \
    std::ostringstream ex_str;                   \
    ex_str << msg;                               \
    constexpr auto fileInMIRAPath = mira::chopMIRAPath(__FILE__); \
    throw ex(ex_str.str(), fileInMIRAPath, __LINE__);  \
}

Same as MIRA_THROW, except that no stack trace information is stored.

This macro can be used when many exceptions are thrown and catched and no stack information is necessary, to avoid performance penalties.

MIRA_THROW_EXTSTACK

#define MIRA_THROW_EXTSTACK	(		ex,
			msg,
			stack,
			thread
	)

Value:

{                                                    \
    std::ostringstream ex_str;                       \
    ex_str << msg;                                   \
    constexpr auto fileInMIRAPath = mira::chopMIRAPath(__FILE__); \
    throw ex(ex_str.str(), fileInMIRAPath, __LINE__)       \
        .addExternalStackInfo<ex>(stack, thread);    \
}

Same as MIRA_THROW, except that the stack trace information that is stored is provided externally.

This macro can be used when an exception is thrown to signal another original exception, e.g. in RPC handling.

MIRA_RETHROW

#define MIRA_RETHROW	(		ex,
			msg
	)

Value:

{                                                \
    std::ostringstream ex_str;                   \
    ex_str << msg;                               \
    constexpr auto fileInMIRAPath = mira::chopMIRAPath(__FILE__); \
    ex.addInfo(ex_str.str(),fileInMIRAPath, __LINE__); \
    throw; /* rethrow */                         \
}

Macro for rethrowing an exception with file and line information and for adding additional information.

Example:

In the example the readValue() function is called for a file stream. readValue() will throw exceptions if the given stream violates certain syntax rules. The readFile() function below can now catch the exception in order to provide additional information like the filename or line number to the user. This information can be specified in the second parameter of MIRA_RETHROW.

void readFile(const char* filename)
{
    ifstream s(filename);
    try {
        readValue(s);
    } catch(mira::Exception& e) {
        // append additional information and rethrow
        MIRA_RETHROW(e, "filename: " << filename);
    }
}

MIRA_DEFINE_EXCEPTION

#define MIRA_DEFINE_EXCEPTION	(		Ex,
			Base
	)

Value:

class Ex : public Base                                                     \
    {                                                                          \
    public:                                                                    \
        Ex(std::string msg, const char* file=NULL, int line=0) MIRA_NOEXCEPT_OR_NOTHROW : \
            Base(std::move(msg), file, line) {}                                \
                                                                               \
        virtual ~Ex() MIRA_NOEXCEPT_OR_NOTHROW {}                              \
    };

Macro for easily defining a new compatible exception class.

Beside the name of the new exception class, the base class of the exception must be specified.

Example: The following example defines a new exception class XMyNewException that is derived from the XLogical exception.

MIRA_DEFINE_EXCEPTION(XMyNewException, XLogical)

MIRA_DEFINE_SERIALIZABLE_EXCEPTION

#define MIRA_DEFINE_SERIALIZABLE_EXCEPTION	(		Ex,
			Base
	)

Value:

class Ex : public Base                                                       \
    {                                                                            \
        MIRA_OBJECT(Ex)                                                          \
    protected:                                                                   \
        friend class mira::ClassFactoryDefaultConstClassBuilder;                 \
        Ex() MIRA_NOEXCEPT_OR_NOTHROW {}                                         \
                                                                                 \
    public:                                                                      \
        Ex(std::string msg, const char* file=NULL, int line=0) MIRA_NOEXCEPT_OR_NOTHROW :  \
            Base(std::move(msg), file, line) {}                                  \
        /* The exception object is copy-initialized from *this; */               \
        void raise(bool recursive = false) override { throw *this; }             \
    };

Macro for easily defining a new serializable exception class.

Beside the name of the new exception class, the base class of the exception must be specified.

Example: The following example defines a new exception class XMyNewException that is derived from the XLogical exception.

MIRA_DEFINE_SERIALIZABLE_EXCEPTION(XMyNewException, XLogical)

Function Documentation

installSignalHandler()

void MIRA_BASE_EXPORT mira::installSignalHandler	(	int	sig,
		boost::function< void(const IntSignal &)>	function
	)

Registers a function for the specified interrupt signal.

The function can be a static member function or a member function that is binded using boost::bind(). The specified function must take a single int parameter where the signal is passed.

Example:

class MyClass
{
public:
    MyClass() {
        installSignalHandler(SIGINT, boost::bind(&MyClass::myHandler, this, _1));
    }

private:

    void myHandler(const IntSignal& signal)
    {
        // this is called if SIGINT signal occurs
        // signal.sig contains SIGINT
        // signal.callStack contains a backtrace of the callstack
    }
};

Parameters

sig	The interupt signal
function	The function that should be called if the signal occurs.

To ensure compatibility with Windows the signal should be one of:

• SIGABRT: Abnormal termination
• SIGFPE: Floating-point error
• SIGILL: Illegal instruction
• SIGINT: CTRL+C signal
• SIGSEGV: Illegal storage access
• SIGTERM: Termination request